claude-git-sessions 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# ccgs — Claude Code Git Sessions
+
+Share [Claude Code](https://claude.com/claude-code) sessions across a team
+through an **orphan branch in your existing git repo**. No server, no extra
+infrastructure — your transcripts ride along with the code they belong to.
+
+> Published on npm as **`claude-git-sessions`** (the bare name `ccgs` is blocked by npm's
+> name-similarity filter). The command it installs is **`ccgs`**.
+
+```bash
+npx claude-git-sessions pull     # bring shared sessions onto this machine
+npx claude-git-sessions push     # publish your local sessions for this repo
+npx claude-git-sessions delete <id|name>
+```
+
+After `pull`, resume any teammate's session locally with:
+
+```bash
+claude --resume <session-id>
+```
+
+## Install
+
+Run on demand with `npx` (no install):
+
+```bash
+npx claude-git-sessions pull
+```
+
+…or install globally (this installs the `ccgs` command):
+
+```bash
+npm i -g claude-git-sessions
+ccgs --help
+```
+
+Requires **Node 20+** and **git 2.5+**. Run it from inside your git repo.
+
+## How it works
+
+Sessions are stored on an **orphan branch** named `@ccgs/<name>` (default
+`@ccgs/default`) on your repo's remote (default `origin`). The branch shares no
+history with `main` and never contains your source files — only session data:
+
+```
+sessions/<session-id>.jsonl        # the transcript, verbatim
+sessions/<session-id>.meta.json    # sidecar metadata (name, author, cwd, …)
+```
+
+Files are keyed by the globally-unique Claude Code session UUID, so transcripts
+from different authors never collide.
+
+Every `ccgs` operation is done with low-level git plumbing
+(`hash-object`/`update-index`/`write-tree`/`commit-tree`/`push`) against a
+private temporary index. **Your working tree, index, and current branch are
+never touched**, and everything works even with a dirty tree. Concurrent pushes
+are handled by re-fetching and replaying on a non-fast-forward rejection.
+
+### Branch namespacing
+
+The `@ccgs/<name>` namespace lets you keep separate session sets. Use the
+default for the team's shared sessions, and a private name for your own
+work-in-progress that you don't want to share yet:
+
+```bash
+ccgs push -b my-wip      # publish to @ccgs/my-wip
+ccgs pull -b my-wip      # only your private set
+ccgs push                # the shared @ccgs/default set
+```
+
+Branch names are validated with `git check-ref-format` before use.
+
+## Commands
+
+### `ccgs pull`
+
+Fetches `@ccgs/<name>` and writes each session where Claude Code expects it:
+`~/.claude/projects/<local-slug>/<id>.jsonl`. The structural `cwd` field in each
+transcript line is rewritten from the author's path to your local equivalent so
+`claude --resume` works. (Absolute paths inside tool *output* are left as-is —
+cosmetic only.)
+
+If a local session is **newer** than the shared copy it is skipped with a
+warning; pass `--force` to overwrite anyway. Prints what was pulled / skipped.
+
+If the branch doesn't exist, it prints `nothing to pull` and exits 0.
+
+### `ccgs push [targets...]`
+
+Finds local sessions whose working directory is this repo (or a subdirectory),
+copies each transcript verbatim onto the orphan branch, and (re)generates its
+`meta.json`. With no arguments it pushes all of them; pass session ids/names to
+push only those. Creates the orphan branch on first push. Reports added vs
+updated.
+
+### `ccgs delete <id|name> [--yes] [--local]`
+
+Resolves the target by full UUID, unambiguous UUID prefix (git-style, ≥4
+chars), or unique display name — listing candidates and aborting if ambiguous.
+Shows what will be deleted and asks for `y/N` confirmation (`--yes`/`-y` to skip
+for scripting). Removes both files from the branch and pushes. By default only
+the shared branch is touched; add `--local` to also remove the local copy.
+
+### Global options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `-b, --branch <name>` | `default` | session set → branch `@ccgs/<name>` |
+| `--remote <remote>` | `origin` | git remote to use |
+| `-v, --version` | | print version |
+| `-h, --help` | | help |
+
+## Step 0 findings — how Claude Code stores sessions
+
+These assumptions were verified empirically against a real `~/.claude/` before
+writing the tool. They live in one place each so they're easy to fix if the
+convention changes.
+
+### Project slug encoding (`src/slug.ts`)
+
+Claude Code stores each project's sessions under
+`~/.claude/projects/<slug>/`, where the slug is derived from the absolute
+working directory. Comparing real directories to the `cwd` recorded inside their
+session files showed the rule is: **replace every character that is not
+`[A-Za-z0-9]` with `-`**.
+
+| Working directory | Slug |
+| --- | --- |
+| `/home/user` | `-home-user` |
+| `/home/user/code/api` | `-home-user-code-api` |
+| `/home/user/code/my.app.dev` | `-home-user-code-my-app-dev` |
+| `/home/user/code/web-client` | `-home-user-code-web-client` |
+
+Note that both `/` and `.` map to `-`, so the encoding is **lossy and
+irreversible**. ccgs therefore only ever goes path → slug, and stores the real
+`originalCwd` separately in `meta.json`.
+
+The config root honors `CLAUDE_CONFIG_DIR` and falls back to `~/.claude`. Local
+sessions live at `<config>/projects/<slug>/<session-id>.jsonl`.
+
+### Session `.jsonl` schema (`src/session.ts`)
+
+Each session is **JSONL** — one JSON object per line, with many object `type`s
+(`user`, `assistant`, `attachment`, `ai-title`, `mode`, `tool_result`, …).
+Verified fields:
+
+- **Session UUID** — `sessionId`, present on most lines, equal to the filename.
+- **Title / name** — a `{ "type": "ai-title", "aiTitle": "…" }` line. Older
+  versions used `{ "type": "summary", "summary": "…" }`; some objects also carry
+  a `title`. The display name resolves: title → summary → first user message
+  (truncated) → session id.
+- **Working directory** — the `cwd` field, present on `user`/`assistant`/
+  `attachment` lines. This is the **only** field `pull` rewrites.
+- **Timestamps** — per-line `timestamp` (ISO-8601). `updatedAt` is the max.
+- **First user message** — `message.content` on the first `type:"user"` line;
+  `content` is a string or an array of content blocks (each may have `.text`).
+
+## Known considerations / future work
+
+- **Secret redaction** — transcripts are pushed verbatim. If your sessions may
+  contain secrets, scrub them before pushing. A `--redact` flag is a likely
+  future addition. **Not implemented today.**
+- **Git LFS** — very large transcripts are committed as ordinary blobs. LFS
+  handling may be added later.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc -> dist/, chmod +x the bin
+npm test           # node:test unit tests (no live Claude install needed)
+npm run typecheck
+```
+
+Tests cover the pure pieces: slug encoding, display-name resolution,
+id/prefix/name matching, and the `cwd` remap transform.
+
+## License
+
+MIT

package/dist/branch-sessions.js

@@ -0,0 +1,33 @@
+import { SESSIONS_DIR } from "./constants.js";
+import { lsSessions, showFile } from "./git.js";
+import { parseMeta } from "./meta.js";
+/** Session ids present on the branch ref (derived from `.jsonl` blobs). */
+export async function listBranchSessionIds(repo, ref) {
+    const paths = await lsSessions(repo, ref);
+    const ids = new Set();
+    for (const p of paths) {
+        const m = p.match(new RegExp(`^${SESSIONS_DIR}/([^/]+)\\.jsonl$`));
+        if (m)
+            ids.add(m[1]);
+    }
+    return [...ids];
+}
+/** Read every session id + its parsed sidecar meta from the branch ref. */
+export async function listBranchSessions(repo, ref) {
+    const ids = await listBranchSessionIds(repo, ref);
+    const out = [];
+    for (const id of ids) {
+        const raw = await showFile(repo, ref, `${SESSIONS_DIR}/${id}.meta.json`);
+        let meta = null;
+        if (raw) {
+            try {
+                meta = parseMeta(raw);
+            }
+            catch {
+                meta = null;
+            }
+        }
+        out.push({ id, meta });
+    }
+    return out;
+}

package/dist/commands/delete.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { SESSIONS_DIR } from "../constants.js";
+import { applyToOrphanBranch, assertRemote, fetchBranch, localTrackingRef, validateBranchName, } from "../git.js";
+import { listBranchSessions } from "../branch-sessions.js";
+import { resolveTarget, shortId } from "../match.js";
+import { sessionFilePath } from "../paths.js";
+function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+export async function deleteSession(opts) {
+    await validateBranchName(opts.repoRoot, opts.branch);
+    await assertRemote(opts.repoRoot, opts.remote);
+    const exists = await fetchBranch(opts.repoRoot, opts.remote, opts.branch);
+    if (!exists) {
+        console.log("nothing to delete (branch does not exist on remote)");
+        return 0;
+    }
+    const ref = localTrackingRef(opts.branch);
+    const sessions = await listBranchSessions(opts.repoRoot, ref);
+    if (sessions.length === 0) {
+        console.log("nothing to delete (no sessions on branch)");
+        return 0;
+    }
+    const candidates = sessions.map((s) => ({
+        id: s.id,
+        name: s.meta?.name ?? s.id,
+        meta: s.meta,
+    }));
+    const res = resolveTarget(opts.target, candidates);
+    if (res.kind === "none") {
+        console.error(`"${opts.target}" matched no session on @ccgs/${opts.branch}`);
+        return 1;
+    }
+    if (res.kind === "ambiguous") {
+        console.error(`"${opts.target}" is ambiguous; candidates:`);
+        for (const c of res.items)
+            console.error(`  ${shortId(c.id)}  ${c.name}`);
+        console.error("Refine your query (use a longer id prefix or exact name).");
+        return 1;
+    }
+    const item = res.item;
+    const meta = item.meta;
+    console.log("Will delete:");
+    console.log(`  id:        ${item.id}`);
+    console.log(`  name:      ${meta?.name ?? "(unknown)"}`);
+    console.log(`  author:    ${meta?.author ?? "(unknown)"}`);
+    console.log(`  updatedAt: ${meta?.updatedAt ?? "(unknown)"}`);
+    if (!opts.yes) {
+        const ok = await confirm(`Delete this session from @ccgs/${opts.branch}? [y/N] `);
+        if (!ok) {
+            console.log("Aborted.");
+            return 0;
+        }
+    }
+    const result = await applyToOrphanBranch(opts.repoRoot, opts.remote, opts.branch, `ccgs: delete session ${shortId(item.id)}`, async (b) => {
+        await b.removeBlob(`${SESSIONS_DIR}/${item.id}.jsonl`);
+        await b.removeBlob(`${SESSIONS_DIR}/${item.id}.meta.json`);
+    });
+    if (result.changed) {
+        console.log(`Deleted ${item.name} (${shortId(item.id)}) from ${opts.remote} @ccgs/${opts.branch}.`);
+    }
+    else {
+        console.log("Nothing changed on the branch (already absent).");
+    }
+    if (opts.local) {
+        const rel = meta?.cwdRelativeToRepoRoot ?? "";
+        const localCwd = rel ? path.join(opts.repoRoot, rel) : opts.repoRoot;
+        const localFile = sessionFilePath(localCwd, item.id);
+        if (fs.existsSync(localFile)) {
+            fs.rmSync(localFile);
+            console.log(`Removed local copy: ${localFile}`);
+        }
+        else {
+            console.log("No local copy found to remove.");
+        }
+    }
+    return 0;
+}

package/dist/commands/pull.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { SESSIONS_DIR } from "../constants.js";
+import { assertRemote, fetchBranch, localTrackingRef, showFile, validateBranchName, } from "../git.js";
+import { listBranchSessions } from "../branch-sessions.js";
+import { parseSession, remapCwd } from "../session.js";
+import { projectDirForCwd, sessionFilePath } from "../paths.js";
+import { shortId } from "../match.js";
+export async function pull(opts) {
+    await validateBranchName(opts.repoRoot, opts.branch);
+    await assertRemote(opts.repoRoot, opts.remote);
+    const exists = await fetchBranch(opts.repoRoot, opts.remote, opts.branch);
+    if (!exists) {
+        console.log("nothing to pull (branch does not exist on remote)");
+        return 0;
+    }
+    const ref = localTrackingRef(opts.branch);
+    const sessions = await listBranchSessions(opts.repoRoot, ref);
+    if (sessions.length === 0) {
+        console.log("nothing to pull (no sessions on branch)");
+        return 0;
+    }
+    const pulled = [];
+    const skipped = [];
+    for (const { id, meta } of sessions) {
+        const jsonl = await showFile(opts.repoRoot, ref, `${SESSIONS_DIR}/${id}.jsonl`);
+        if (jsonl === null) {
+            skipped.push(`${shortId(id)}: missing transcript blob`);
+            continue;
+        }
+        // Reconstruct the local cwd for this session: repo root + recorded subdir.
+        const rel = meta?.cwdRelativeToRepoRoot ?? "";
+        const localCwd = rel ? path.join(opts.repoRoot, rel) : opts.repoRoot;
+        const name = meta?.name ?? id;
+        // Conflict policy: newer local copy is kept unless --force.
+        const localFile = sessionFilePath(localCwd, id);
+        if (!opts.force && fs.existsSync(localFile)) {
+            const branchUpdated = meta?.updatedAt ?? "";
+            const localInfo = parseSession(fs.readFileSync(localFile, "utf8"), id);
+            const localUpdated = localInfo.updatedAt ?? "";
+            if (localUpdated && branchUpdated && localUpdated > branchUpdated) {
+                skipped.push(`${name} (${shortId(id)}): local copy is newer (use --force)`);
+                continue;
+            }
+        }
+        // Remap the structural cwd from the author's path to ours.
+        const remapped = meta?.originalCwd
+            ? remapCwd(jsonl, meta.originalCwd, localCwd)
+            : jsonl;
+        const dir = projectDirForCwd(localCwd);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(localFile, remapped);
+        pulled.push(`${name} (${shortId(id)})`);
+    }
+    if (pulled.length) {
+        console.log(`Pulled ${pulled.length} session(s):`);
+        for (const p of pulled)
+            console.log(`  + ${p}`);
+    }
+    else {
+        console.log("Pulled 0 sessions.");
+    }
+    if (skipped.length) {
+        console.log(`Skipped ${skipped.length}:`);
+        for (const s of skipped)
+            console.log(`  - ${s}`);
+    }
+    return 0;
+}

package/dist/commands/push.js

@@ -0,0 +1,91 @@
+import { SESSIONS_DIR } from "../constants.js";
+import { applyToOrphanBranch, assertRemote, fetchBranch, localTrackingRef, showFile, validateBranchName, } from "../git.js";
+import { listBranchSessionIds } from "../branch-sessions.js";
+import { discoverLocalSessions } from "../discover.js";
+import { buildMeta, gitAuthor, serializeMeta } from "../meta.js";
+import { resolveTarget, shortId } from "../match.js";
+export async function push(opts) {
+    await validateBranchName(opts.repoRoot, opts.branch);
+    await assertRemote(opts.repoRoot, opts.remote);
+    let sessions = discoverLocalSessions(opts.repoRoot);
+    if (sessions.length === 0) {
+        console.log("nothing to push (no local sessions found for this repo)");
+        return 0;
+    }
+    // Apply positional id/name filters if any were given.
+    if (opts.filters.length > 0) {
+        const candidates = sessions.map((s) => ({
+            id: s.info.id,
+            name: s.info.displayName,
+            session: s,
+        }));
+        const selected = new Map();
+        for (const f of opts.filters) {
+            const res = resolveTarget(f, candidates);
+            if (res.kind === "match") {
+                selected.set(res.item.id, res.item.session);
+            }
+            else if (res.kind === "ambiguous") {
+                console.error(`"${f}" is ambiguous; matches:`);
+                for (const c of res.items)
+                    console.error(`  ${shortId(c.id)}  ${c.name}`);
+                return 1;
+            }
+            else {
+                console.error(`"${f}" matched no local session for this repo`);
+                return 1;
+            }
+        }
+        sessions = [...selected.values()];
+    }
+    // Pre-compute what already exists on the branch so we can label each session
+    // as added / updated / unchanged by comparing the transcript blob.
+    await fetchBranch(opts.repoRoot, opts.remote, opts.branch);
+    const ref = localTrackingRef(opts.branch);
+    const existing = new Set(await listBranchSessionIds(opts.repoRoot, ref).catch(() => []));
+    const author = await gitAuthor(opts.repoRoot);
+    const added = [];
+    const updated = [];
+    let unchanged = 0;
+    for (const s of sessions) {
+        const label = `${s.info.displayName} (${shortId(s.info.id)})`;
+        if (!existing.has(s.info.id)) {
+            added.push(label);
+        }
+        else {
+            const prev = await showFile(opts.repoRoot, ref, `${SESSIONS_DIR}/${s.info.id}.jsonl`);
+            if (prev === s.content)
+                unchanged++;
+            else
+                updated.push(label);
+        }
+    }
+    const result = await applyToOrphanBranch(opts.repoRoot, opts.remote, opts.branch, buildCommitMessage(added.length + updated.length), async (b) => {
+        for (const s of sessions) {
+            const meta = buildMeta(s.info, opts.repoRoot, author);
+            await b.addBlob(`${SESSIONS_DIR}/${s.info.id}.jsonl`, s.content);
+            await b.addBlob(`${SESSIONS_DIR}/${s.info.id}.meta.json`, serializeMeta(meta));
+        }
+    });
+    if (!result.changed) {
+        console.log(`Already up to date — ${unchanged} session(s) unchanged.`);
+        return 0;
+    }
+    if (added.length) {
+        console.log(`Added ${added.length}:`);
+        for (const a of added)
+            console.log(`  + ${a}`);
+    }
+    if (updated.length) {
+        console.log(`Updated ${updated.length}:`);
+        for (const u of updated)
+            console.log(`  ~ ${u}`);
+    }
+    if (unchanged)
+        console.log(`(${unchanged} unchanged)`);
+    console.log(`Pushed to ${opts.remote} @ccgs/${opts.branch}.`);
+    return 0;
+}
+function buildCommitMessage(n) {
+    return `ccgs: push ${n} session(s)`;
+}

package/dist/constants.js

@@ -0,0 +1,19 @@
+/**
+ * Single source of truth for the package + command identity, so renaming is a
+ * one-line change.
+ */
+/**
+ * npm package name. The bare name `ccgs` is blocked by npm's name-similarity
+ * filter, so the package ships as `claude-git-sessions`; the installed command is still
+ * `ccgs` (see COMMAND_NAME). Both are one-line changes if either is renamed.
+ */
+export const PACKAGE_NAME = "claude-git-sessions";
+export const COMMAND_NAME = "ccgs";
+/** Orphan branches are namespaced as `@ccgs/<name>`. */
+export const BRANCH_PREFIX = "@ccgs/";
+export const DEFAULT_BRANCH_NAME = "default";
+export const DEFAULT_REMOTE = "origin";
+/** Path prefix used for session blobs on the orphan branch. */
+export const SESSIONS_DIR = "sessions";
+/** Max length of an auto-derived display name. */
+export const DISPLAY_NAME_MAX = 80;

package/dist/discover.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+import { projectsDir } from "./paths.js";
+import { parseSession } from "./session.js";
+/** Is `child` the same as, or nested under, `parent`? */
+function isWithin(parent, child) {
+    if (child === parent)
+        return true;
+    const rel = path.relative(parent, child);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/**
+ * Find local Claude Code sessions belonging to `repoRoot`.
+ *
+ * Sessions launched at the repo root live under the repo-root slug, but a
+ * session launched in a subdirectory lives under a *different* slug. So rather
+ * than rely on the slug alone, we scan every project directory, read each
+ * transcript, and keep the ones whose recorded `cwd` is the repo root or nested
+ * within it. The recorded cwd also gives us `cwdRelativeToRepoRoot` for free.
+ */
+export function discoverLocalSessions(repoRoot) {
+    const root = projectsDir();
+    let dirs;
+    try {
+        dirs = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return []; // no ~/.claude/projects yet
+    }
+    const found = [];
+    for (const dir of dirs) {
+        if (!dir.isDirectory())
+            continue;
+        const dirPath = path.join(root, dir.name);
+        let files;
+        try {
+            files = fs.readdirSync(dirPath);
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            if (!f.endsWith(".jsonl"))
+                continue;
+            const file = path.join(dirPath, f);
+            let content;
+            try {
+                content = fs.readFileSync(file, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const fallbackId = f.replace(/\.jsonl$/, "");
+            const info = parseSession(content, fallbackId);
+            if (info.cwd && isWithin(repoRoot, info.cwd)) {
+                found.push({ info, file, content });
+            }
+        }
+    }
+    return found;
+}

package/dist/git.js

@@ -0,0 +1,194 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { BRANCH_PREFIX, SESSIONS_DIR } from "./constants.js";
+export class GitError extends Error {
+    code;
+    stderr;
+    constructor(message, code, stderr) {
+        super(message);
+        this.code = code;
+        this.stderr = stderr;
+        this.name = "GitError";
+    }
+}
+/**
+ * Run git with an explicit argv (never a shell string) so no user input is ever
+ * interpolated into a shell. stdout is captured as a Buffer then decoded utf-8.
+ */
+export function git(args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", args, {
+            cwd: opts.cwd,
+            env: opts.env ?? process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on("data", (d) => out.push(d));
+        child.stderr.on("data", (d) => err.push(d));
+        child.on("error", (e) => reject(e));
+        child.on("close", (code) => {
+            const result = {
+                code: code ?? 0,
+                stdout: Buffer.concat(out).toString("utf8"),
+                stderr: Buffer.concat(err).toString("utf8"),
+            };
+            if (result.code !== 0 && !opts.allowFail) {
+                reject(new GitError(`git ${args.join(" ")} failed (exit ${result.code}): ${result.stderr.trim()}`, result.code, result.stderr));
+            }
+            else {
+                resolve(result);
+            }
+        });
+        if (opts.input !== undefined)
+            child.stdin.end(opts.input);
+        else
+            child.stdin.end();
+    });
+}
+/** Convenience: return trimmed stdout, throwing on failure unless allowFail. */
+export async function gitOut(args, opts = {}) {
+    const r = await git(args, opts);
+    return r.stdout;
+}
+/** Absolute repo root, or throw a clear error if not inside a git repo. */
+export async function repoRoot() {
+    const r = await git(["rev-parse", "--show-toplevel"], { allowFail: true });
+    if (r.code !== 0) {
+        throw new Error("not inside a git repository (run ccgs from within your repo)");
+    }
+    return r.stdout.trim();
+}
+/** Full `@ccgs/<name>` branch name. */
+export function branchName(name) {
+    return `${BRANCH_PREFIX}${name}`;
+}
+/** Local tracking ref we fetch the orphan branch into (kept out of refs/heads). */
+export function localTrackingRef(name) {
+    return `refs/ccgs/${name}`;
+}
+/** Fully-qualified remote head ref we push to / fetch from. */
+export function remoteHeadRef(name) {
+    return `refs/heads/${branchName(name)}`;
+}
+/** Validate the branch name with `git check-ref-format`; throw if invalid. */
+export async function validateBranchName(repo, name) {
+    const ref = remoteHeadRef(name);
+    const r = await git(["check-ref-format", ref], { cwd: repo, allowFail: true });
+    if (r.code !== 0) {
+        throw new Error(`invalid branch name "${name}": "${ref}" is not a valid git ref`);
+    }
+}
+/** Error clearly if the named remote does not exist. */
+export async function assertRemote(repo, remote) {
+    const r = await git(["remote"], { cwd: repo });
+    const remotes = r.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+    if (!remotes.includes(remote)) {
+        throw new Error(`remote "${remote}" not found (configured remotes: ${remotes.join(", ") || "none"})`);
+    }
+}
+/**
+ * Fetch the orphan branch from the remote into our local tracking ref.
+ * Returns true if it exists remotely, false if the remote ref is absent.
+ */
+export async function fetchBranch(repo, remote, name) {
+    const refspec = `+${remoteHeadRef(name)}:${localTrackingRef(name)}`;
+    const r = await git(["fetch", "--no-tags", remote, refspec], {
+        cwd: repo,
+        allowFail: true,
+    });
+    if (r.code === 0)
+        return true;
+    // git reports a missing branch as "couldn't find remote ref ...".
+    if (/couldn't find remote ref|couldn't find remote/i.test(r.stderr))
+        return false;
+    throw new GitError(`failed to fetch ${branchName(name)} from ${remote}: ${r.stderr.trim()}`, r.code, r.stderr);
+}
+/** SHA of the local tracking ref, or null if it does not exist. */
+export async function trackingTip(repo, name) {
+    const r = await git(["rev-parse", "--verify", "--quiet", localTrackingRef(name)], {
+        cwd: repo,
+        allowFail: true,
+    });
+    const sha = r.stdout.trim();
+    return sha || null;
+}
+/** List `sessions/*` paths present on a tree-ish ref. */
+export async function lsSessions(repo, ref) {
+    const r = await git(["ls-tree", "-r", "--name-only", ref], { cwd: repo, allowFail: true });
+    if (r.code !== 0)
+        return [];
+    return r.stdout
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((p) => p.startsWith(`${SESSIONS_DIR}/`));
+}
+/** Read a blob at `ref:path` as utf-8 text, or null if it does not exist. */
+export async function showFile(repo, ref, filePath) {
+    const r = await git(["show", `${ref}:${filePath}`], { cwd: repo, allowFail: true });
+    if (r.code !== 0)
+        return null;
+    return r.stdout;
+}
+const NONFF = /non-fast-forward|fetch first|\[rejected\]|cannot lock ref|failed to update ref|stale info/i;
+/**
+ * Build a new commit on the orphan branch and push it, WITHOUT touching the
+ * user's working tree, index or current branch, and tolerating a dirty tree.
+ *
+ * Mechanics (pure plumbing):
+ *   - work against a private temp index via GIT_INDEX_FILE
+ *   - seed it from the current branch tip (or empty, for a true orphan root)
+ *   - let `apply` hash-object/update-index the session blobs
+ *   - write-tree -> commit-tree (-p parent, omitted => orphan root)
+ *   - push <commit>:refs/heads/@ccgs/<name>
+ * On a non-fast-forward rejection it re-fetches the tip and replays, a few times.
+ */
+export async function applyToOrphanBranch(repo, remote, name, message, apply, maxRetries = 5) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        const exists = await fetchBranch(repo, remote, name);
+        const parent = exists ? await trackingTip(repo, name) : null;
+        const indexFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "ccgs-idx-")), "index");
+        const env = { ...process.env, GIT_INDEX_FILE: indexFile };
+        try {
+            // Seed the temp index from the parent tree (orphan root starts empty).
+            if (parent) {
+                await git(["read-tree", parent], { cwd: repo, env });
+            }
+            const builder = {
+                async addBlob(gitPath, content) {
+                    const sha = (await gitOut(["hash-object", "-w", "--stdin"], { cwd: repo, input: content })).trim();
+                    await git(["update-index", "--add", "--cacheinfo", `100644,${sha},${gitPath}`], { cwd: repo, env });
+                },
+                async removeBlob(gitPath) {
+                    await git(["update-index", "--force-remove", gitPath], { cwd: repo, env, allowFail: true });
+                },
+            };
+            await apply(builder);
+            const tree = (await gitOut(["write-tree"], { cwd: repo, env })).trim();
+            // No-op short-circuit: identical to parent tree -> nothing to push.
+            if (parent) {
+                const parentTree = (await gitOut(["rev-parse", `${parent}^{tree}`], { cwd: repo })).trim();
+                if (tree === parentTree)
+                    return { changed: false };
+            }
+            const commitArgs = ["commit-tree", tree];
+            if (parent)
+                commitArgs.push("-p", parent);
+            const commit = (await gitOut(commitArgs, { cwd: repo, input: message })).trim();
+            const push = await git(["push", remote, `${commit}:${remoteHeadRef(name)}`], { cwd: repo, allowFail: true });
+            if (push.code === 0)
+                return { changed: true, commit };
+            if (NONFF.test(push.stderr) && attempt < maxRetries - 1) {
+                continue; // re-fetch tip and replay on top
+            }
+            throw new GitError(`failed to push ${branchName(name)} to ${remote}: ${push.stderr.trim()}`, push.code, push.stderr);
+        }
+        finally {
+            // Clean up the temp index dir regardless of outcome.
+            fs.rmSync(path.dirname(indexFile), { recursive: true, force: true });
+        }
+    }
+    throw new Error(`could not push ${branchName(name)} after ${maxRetries} attempts (concurrent updates?)`);
+}

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { COMMAND_NAME, DEFAULT_BRANCH_NAME, DEFAULT_REMOTE, PACKAGE_NAME, } from "./constants.js";
+import { repoRoot } from "./git.js";
+import { pull } from "./commands/pull.js";
+import { push } from "./commands/push.js";
+import { deleteSession } from "./commands/delete.js";
+// Kept in sync with package.json at publish time; hardcoded to avoid a JSON
+// import assertion just for --version.
+const VERSION = "0.1.0";
+function globals(cmd) {
+    const opts = cmd.optsWithGlobals();
+    return {
+        branch: opts.branch ?? DEFAULT_BRANCH_NAME,
+        remote: opts.remote ?? DEFAULT_REMOTE,
+    };
+}
+async function run(fn) {
+    try {
+        process.exitCode = await fn();
+    }
+    catch (err) {
+        console.error(`${COMMAND_NAME}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
+}
+const program = new Command();
+program
+    .name(COMMAND_NAME)
+    .description(`${PACKAGE_NAME} — share Claude Code sessions through an orphan git branch`)
+    .version(VERSION, "-v, --version")
+    .option("-b, --branch <name>", "session set name (branch @ccgs/<name>)", DEFAULT_BRANCH_NAME)
+    .option("--remote <remote>", "git remote to use", DEFAULT_REMOTE);
+program
+    .command("pull")
+    .description("fetch shared sessions and place them where Claude Code can resume them")
+    .option("--force", "overwrite local copies even if they are newer", false)
+    .action(async (localOpts, cmd) => {
+    const g = globals(cmd);
+    await run(async () => {
+        const root = await repoRoot();
+        return pull({ repoRoot: root, remote: g.remote, branch: g.branch, force: localOpts.force });
+    });
+});
+program
+    .command("push")
+    .description("publish this repo's local sessions to the orphan branch")
+    .argument("[targets...]", "optional session ids/names to push (default: all)")
+    .action(async (targets, _localOpts, cmd) => {
+    const g = globals(cmd);
+    await run(async () => {
+        const root = await repoRoot();
+        return push({ repoRoot: root, remote: g.remote, branch: g.branch, filters: targets });
+    });
+});
+program
+    .command("delete")
+    .description("remove a session from the shared orphan branch")
+    .argument("<target>", "session id, unambiguous id prefix, or unique name")
+    .option("-y, --yes", "skip the interactive confirmation", false)
+    .option("--local", "also remove the local copy under ~/.claude/projects", false)
+    .action(async (target, localOpts, cmd) => {
+    const g = globals(cmd);
+    await run(async () => {
+        const root = await repoRoot();
+        return deleteSession({
+            repoRoot: root,
+            remote: g.remote,
+            branch: g.branch,
+            target,
+            yes: localOpts.yes,
+            local: localOpts.local,
+        });
+    });
+});
+program.parseAsync(process.argv);

package/dist/match.js

@@ -0,0 +1,32 @@
+export function resolveTarget(query, candidates) {
+    const q = query.trim();
+    // 1. Exact id wins outright.
+    const exactId = candidates.filter((c) => c.id === q);
+    if (exactId.length === 1)
+        return { kind: "match", item: exactId[0] };
+    // 2. Exact (case-insensitive) display-name match.
+    const exactName = candidates.filter((c) => c.name.toLowerCase() === q.toLowerCase());
+    if (exactName.length === 1)
+        return { kind: "match", item: exactName[0] };
+    if (exactName.length > 1)
+        return { kind: "ambiguous", items: exactName };
+    // 3. Git-style unambiguous id prefix (only for hex-ish queries).
+    if (/^[0-9a-fA-F-]+$/.test(q) && q.length >= 4) {
+        const byPrefix = candidates.filter((c) => c.id.startsWith(q.toLowerCase()));
+        if (byPrefix.length === 1)
+            return { kind: "match", item: byPrefix[0] };
+        if (byPrefix.length > 1)
+            return { kind: "ambiguous", items: byPrefix };
+    }
+    // 4. Fall back to a case-insensitive name substring.
+    const bySubstr = candidates.filter((c) => c.name.toLowerCase().includes(q.toLowerCase()));
+    if (bySubstr.length === 1)
+        return { kind: "match", item: bySubstr[0] };
+    if (bySubstr.length > 1)
+        return { kind: "ambiguous", items: bySubstr };
+    return { kind: "none" };
+}
+/** Short 8-char id, git-style, for display. */
+export function shortId(id) {
+    return id.slice(0, 8);
+}

package/dist/meta.js

@@ -0,0 +1,44 @@
+import os from "node:os";
+import path from "node:path";
+import { gitOut } from "./git.js";
+/** "Name <email>" from git config, best-effort. */
+export async function gitAuthor(repoRoot) {
+    const name = (await gitOut(["config", "user.name"], { cwd: repoRoot, allowFail: true })).trim();
+    const email = (await gitOut(["config", "user.email"], { cwd: repoRoot, allowFail: true })).trim();
+    if (name && email)
+        return `${name} <${email}>`;
+    if (name)
+        return name;
+    if (email)
+        return email;
+    return "unknown";
+}
+/**
+ * Build the sidecar metadata for a local session being pushed.
+ * `cwdRelativeToRepoRoot` is derived from the session's recorded cwd relative
+ * to the local repo root (POSIX-style, "" when at the root).
+ */
+export function buildMeta(info, repoRoot, author) {
+    const originalCwd = info.cwd ?? repoRoot;
+    let rel = path.relative(repoRoot, originalCwd);
+    if (rel === "" || rel === ".")
+        rel = "";
+    // Normalize to forward slashes so it round-trips across platforms.
+    rel = rel.split(path.sep).join("/");
+    return {
+        id: info.id,
+        name: info.displayName,
+        originalCwd,
+        cwdRelativeToRepoRoot: rel,
+        author,
+        machine: os.hostname(),
+        messageCount: info.messageCount,
+        updatedAt: info.updatedAt ?? new Date().toISOString(),
+    };
+}
+export function serializeMeta(meta) {
+    return JSON.stringify(meta, null, 2) + "\n";
+}
+export function parseMeta(raw) {
+    return JSON.parse(raw);
+}

package/dist/paths.js

@@ -0,0 +1,25 @@
+import os from "node:os";
+import path from "node:path";
+import { pathToProjectSlug } from "./slug.js";
+/**
+ * Root of the Claude Code config, honoring `CLAUDE_CONFIG_DIR` and falling back
+ * to `~/.claude`.
+ */
+export function claudeConfigDir() {
+    const override = process.env.CLAUDE_CONFIG_DIR;
+    if (override && override.trim() !== "")
+        return override;
+    return path.join(os.homedir(), ".claude");
+}
+/** `<config>/projects` — the directory holding one slug subdir per project. */
+export function projectsDir() {
+    return path.join(claudeConfigDir(), "projects");
+}
+/** Absolute project directory Claude Code uses for sessions launched in `absCwd`. */
+export function projectDirForCwd(absCwd) {
+    return path.join(projectsDir(), pathToProjectSlug(absCwd));
+}
+/** Where a session `.jsonl` lives locally for a given cwd + id. */
+export function sessionFilePath(absCwd, sessionId) {
+    return path.join(projectDirForCwd(absCwd), `${sessionId}.jsonl`);
+}

package/dist/session.js

@@ -0,0 +1,114 @@
+import { DISPLAY_NAME_MAX } from "./constants.js";
+function safeParse(line) {
+    if (!line)
+        return null;
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+/** Collapse whitespace and truncate for a tidy one-line display name. */
+export function truncateName(s, max = DISPLAY_NAME_MAX) {
+    const clean = s.replace(/\s+/g, " ").trim();
+    if (clean.length <= max)
+        return clean;
+    return clean.slice(0, max - 1).trimEnd() + "…";
+}
+/** Pull plain text out of a user message `content` (string or block array). */
+function userMessageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            if (block && typeof block === "object" && typeof block.text === "string") {
+                return block.text;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parse a session `.jsonl` body into a {@link SessionInfo}. `fallbackId` (the
+ * filename UUID) is used when no line carries a `sessionId`.
+ */
+export function parseSession(content, fallbackId) {
+    const lines = content.split("\n");
+    let id = null;
+    let cwd = null;
+    let title = null;
+    let summary = null;
+    let firstUserText = null;
+    let messageCount = 0;
+    let updatedAt = null;
+    for (const raw of lines) {
+        const obj = safeParse(raw);
+        if (!obj)
+            continue;
+        if (!id && typeof obj.sessionId === "string")
+            id = obj.sessionId;
+        // Track the most recent cwd we see (later lines win).
+        if (typeof obj.cwd === "string" && obj.cwd)
+            cwd = obj.cwd;
+        if (typeof obj.timestamp === "string") {
+            if (!updatedAt || obj.timestamp > updatedAt)
+                updatedAt = obj.timestamp;
+        }
+        if (!title) {
+            if (typeof obj.aiTitle === "string" && obj.aiTitle.trim())
+                title = obj.aiTitle;
+            else if (obj.type === "summary" && typeof obj.summary === "string" && obj.summary.trim())
+                summary = obj.summary;
+            else if (typeof obj.title === "string" && obj.title.trim())
+                title = obj.title;
+        }
+        if (obj.type === "user" || obj.type === "assistant")
+            messageCount++;
+        if (firstUserText === null && obj.type === "user" && obj.message) {
+            const t = userMessageText(obj.message.content);
+            if (t && t.trim())
+                firstUserText = t;
+        }
+    }
+    // Display name resolution order: title -> summary -> first user msg -> id.
+    const resolvedId = id ?? fallbackId;
+    let displayName;
+    if (title)
+        displayName = truncateName(title);
+    else if (summary)
+        displayName = truncateName(summary);
+    else if (firstUserText)
+        displayName = truncateName(firstUserText);
+    else
+        displayName = resolvedId;
+    return { id: resolvedId, cwd, displayName, messageCount, updatedAt };
+}
+/**
+ * Rewrite the structural `cwd` field from `fromCwd` to `toCwd` on every line
+ * whose parsed `cwd` exactly equals `fromCwd`.
+ *
+ * We deliberately do a TARGETED replacement of just the `"cwd":"..."` token
+ * (located by JSON-encoding the values) rather than a blind find-and-replace or
+ * a full re-serialize: this preserves every other byte of the transcript
+ * exactly, avoiding any risk of corrupting message/tool-output content that may
+ * happen to contain the same path string.
+ */
+export function remapCwd(content, fromCwd, toCwd) {
+    if (fromCwd === toCwd)
+        return content;
+    const fromToken = `"cwd":${JSON.stringify(fromCwd)}`;
+    const toToken = `"cwd":${JSON.stringify(toCwd)}`;
+    return content
+        .split("\n")
+        .map((line) => {
+        const obj = safeParse(line);
+        if (obj && typeof obj.cwd === "string" && obj.cwd === fromCwd) {
+            // Replace only the first occurrence (the structural field); any path in
+            // free-text content is left untouched.
+            return line.replace(fromToken, toToken);
+        }
+        return line;
+    })
+        .join("\n");
+}

package/dist/slug.js

@@ -0,0 +1,27 @@
+/**
+ * Convert an absolute filesystem path into the directory slug Claude Code uses
+ * under `~/.claude/projects/`.
+ *
+ * Verified empirically against a real `~/.claude/projects/` by comparing each
+ * project directory name to the `cwd` recorded inside its session `.jsonl`
+ * files. Illustrative examples:
+ *
+ *   /home/user                       -> -home-user
+ *   /home/user/code/api              -> -home-user-code-api
+ *   /home/user/code/my.app.dev       -> -home-user-code-my-app-dev   (dot  -> '-')
+ *   /home/user/code/web-client       -> -home-user-code-web-client   (existing '-' kept)
+ *
+ * Rule: replace every character that is NOT [A-Za-z0-9] with '-'. The leading
+ * '/' therefore becomes a leading '-'.
+ *
+ * IMPORTANT: this encoding is LOSSY — both '/' and '.' (and any other special
+ * character) map to '-', so it cannot be reversed back into a unique path.
+ * That is why ccgs only ever goes path -> slug, never slug -> path, and why the
+ * sidecar `meta.json` carries the real `originalCwd` separately.
+ *
+ * Keep this as the ONE place that encodes the convention, so it is trivial to
+ * fix if Claude Code ever changes it.
+ */
+export function pathToProjectSlug(absPath) {
+    return absPath.replace(/[^a-zA-Z0-9]/g, "-");
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "claude-git-sessions",
+  "version": "0.1.0",
+  "description": "Share Claude Code sessions across a team through an orphan git branch in your existing repo.",
+  "keywords": ["claude", "claude-code", "git", "sessions", "cli"],
+  "license": "MIT",
+  "author": "Ingram Technologies",
+  "homepage": "https://github.com/ingram-technologies/ccgs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ingram-technologies/ccgs.git"
+  },
+  "type": "module",
+  "bin": {
+    "ccgs": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "test": "node --test --import tsx test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  }
+}