agent-carry 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- `carry list --all` now shows the most recent sessions across every folder, newest first, with the title the desktop app shows and the folder; background-agent sessions (e.g. a memory plugin's observer) are hidden unless `--everything`. `carry export` with no id offers a numbered picker. `--limit N|all` shows more, `--project DIR` lists one folder, `--match TEXT` filters by title, folder or id, and `--desktop` / `--terminal` keep only sessions started in the desktop app or a terminal (every row is tagged; archived desktop sessions are marked; a desktop session with no project folder shows as "desktop scratch folder"). Nobody needs to know where sessions are stored. `/carry:share` uses it (plugin 0.3.0).
+
+- Plugin 0.2.1 (released): commands check the CLI version first and say how to upgrade if it is older, instead of aborting on an unknown-command error.
 - Plugin 0.2.0: `/carry:share` and `/carry:pickup` ask what they need (session, encryption, passphrase source, destination folder, desktop app and account) instead of expecting flags. Needs the CLI from this release.
 - `export --generate-passphrase` (saved to `FILE.pass`, never printed); `carry bundles`; `carry desktop-dirs`.
 - `--desktop` targets the signed-in account (read from the app's log) instead of any folder with sessions, and works for a freshly signed-in account by borrowing only app-level settings.

package/README.md

@@ -16,9 +16,11 @@ copied session can't be resumed elsewhere. `carry` fixes that:
 ```
 npm i -g agent-carry          # installs `carry` (also available as `agent-carry`)
 
-# machine A, in the project folder
-carry list
-carry export --latest -o session.carry.gz
+# machine A (any folder): pick a session from a numbered list, with desktop-app titles
+carry export -o session.carry.gz
+# or: carry list --all   then   carry export <id> -o session.carry.gz
+# more rows: --limit 50 | --limit all    one folder: --project DIR    search: --match word
+# only desktop-app sessions: --desktop    only terminal ones: --terminal   (each row is tagged [desktop] / [terminal])
 
 # machine B, in the same project (any path)
 carry import session.carry.gz
@@ -70,8 +72,8 @@ Passphrases are never put on a command line. A generated one is saved beside the
 
 | command | |
 |---|---|
-| `carry list [--all]` | sessions for this folder, or all |
-| `carry export <id\|--latest> [-o FILE]` | `--generate-passphrase`, `--no-redact`, `--redact-emails`, `--strip-thinking`, `--allow-thinking-secrets`, `--project-root DIR` |
+| `carry list [--all] [--project DIR] [--desktop\|--terminal] [--match TEXT] [--limit N]` | sessions for this folder, or `--all`: recent sessions from every folder, each tagged by where it was started (`[desktop]`, `[terminal]`, `[print mode]`) with the desktop app's title. `--desktop` / `--terminal` keep only those. Background-agent sessions are hidden; `--everything` shows them |
+| `carry export [id\|--latest] [-o FILE]` | with no id, pick from a numbered list (takes the same `--desktop`, `--terminal`, `--project`, `--match`).  `--generate-passphrase`, `--no-redact`, `--redact-emails`, `--strip-thinking`, `--allow-thinking-secrets`, `--project-root DIR` |
 | `carry inspect FILE` | header, parts, redaction counts |
 | `carry import FILE [--project-root DIR] [--dry-run]` | write into the target folder's session store |
 | `carry bundles` / `carry desktop-dirs` | bundle files nearby; desktop-app account folders |
@@ -79,6 +81,7 @@ Passphrases are never put on a command line. A generated one is saved beside the
 
 ## Limits
 
+- **Usage limit:** the CLI needs no Claude usage, so it still works when you have hit your limit; the plugin commands do not, because Claude has to run them.
 - **Resume** is verified on one real session (Claude Code 2.1.299); the transcript format is internal and can change. Run `scripts/verify-resume.sh <id>` to check yours.
 - **Thinking blocks are signed**, so they travel verbatim. If one contains a credential-like string, export refuses unless you pass `--strip-thinking` (resume with stripped thinking is untested) or `--allow-thinking-secrets`. `push` skips such sessions.
 - **Redaction is best effort.** It misses passwords that read like sentences and letters-only lowercase `password=word`. Read `carry inspect` before sharing, and encrypt anything you send to someone else.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-carry",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Move coding-agent sessions between machines and folders: path-portable, redacted, encrypted, merge-safe bundles. Claude Code today; adapter-ready for Codex and others.",
   "type": "module",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "carry",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Move coding-agent sessions between machines and folders: /carry:share exports a redacted, path-portable bundle, /carry:pickup imports one.",
   "author": { "name": "Harsh Gajjar", "email": "harshgajjar2812@gmail.com" },
   "license": "MIT"

package/plugin/commands/pickup.md

@@ -4,19 +4,23 @@ argument-hint: [bundle-file]
 allowed-tools: Bash(carry:*), Bash(npx -y agent-carry@latest:*), Bash(ls:*), Bash(pwd), AskUserQuestion
 ---
 
+carry CLI version (this command needs 0.2.0 or newer): !`carry --version 2>&1 || echo 'not installed'`
+
 Bundle files nearby (this folder, ~/Downloads, ~/Desktop), newest first:
 
-!`carry bundles 2>&1 || npx -y agent-carry@latest bundles 2>&1`
+!`carry bundles 2>&1 || true`
 
 Current folder: !`pwd`
 
 Claude desktop app account folders (macOS only; an error here just means no desktop app):
 
-!`carry desktop-dirs 2>&1`
+!`carry desktop-dirs 2>&1 || true`
 
 Arguments the user typed: $ARGUMENTS
 
-You are importing one session with the `carry` CLI. If `carry` was not found above, use `npx -y agent-carry@latest` in its place; if that also fails, tell the user to run `npm i -g agent-carry` and stop. If a command says it is unknown, the CLI is old: tell the user to run `npm i -g agent-carry@latest`.
+**Step 0.** Look at the version line above. If it says "not installed" or shows anything older than 0.2.0, stop and say exactly this, with nothing else: "This command needs the carry CLI 0.2.0 or newer. Run `npm i -g agent-carry@latest`, then try again." (If that install still gives an older version, 0.2.0 has not been published to npm yet.) Any error text shown in the listings below comes from the same cause; do not try to work around it.
+
+You are importing one session with the `carry` CLI.
 
 Ask with the AskUserQuestion tool, one short question at a time, and skip any question the typed arguments already answer. If AskUserQuestion is not available, ask as a short numbered list in plain text and wait.
 

package/plugin/commands/share.md

@@ -4,17 +4,23 @@ argument-hint: [optional carry export flags, e.g. -o FILE --strip-thinking]
 allowed-tools: Bash(carry:*), Bash(npx -y agent-carry@latest:*), AskUserQuestion
 ---
 
-Sessions in this folder, newest first (the top one is usually this conversation):
+carry CLI version (this command needs 0.2.0 or newer): !`carry --version 2>&1 || echo 'not installed'`
 
-!`carry list 2>&1 || npx -y agent-carry@latest list 2>&1`
+Recent sessions from every folder, newest first, including ones started in the Claude desktop app (the top one is usually this conversation):
+
+!`carry list --all --limit 8 2>&1 || true`
+
+Current folder: !`pwd`
 
 Arguments the user typed: $ARGUMENTS
 
-You are exporting one session with the `carry` CLI. If `carry` was not found above, use `npx -y agent-carry@latest` in its place; if that also fails, tell the user to run `npm i -g agent-carry` and stop. If a command below says it is unknown, the CLI is old: tell the user to run `npm i -g agent-carry@latest`.
+**Step 0.** Look at the version line above. If it says "not installed" or shows anything older than 0.2.0, stop and say exactly this, with nothing else: "This command needs the carry CLI 0.2.0 or newer. Run `npm i -g agent-carry@latest`, then try again." (If that install still gives an older version, 0.2.0 has not been published to npm yet.) Any error text shown in the listings below comes from the same cause; do not try to work around it.
+
+You are exporting one session with the `carry` CLI.
 
 Ask with the AskUserQuestion tool, one short question at a time, and skip any question the typed arguments already answer. If AskUserQuestion is not available, ask the same questions as a short numbered list in plain text and wait for the reply.
 
-1. **Which session.** Ignore rows with 0 turns. If only one has turns, use it without asking. Otherwise ask, offering the newest first as "(Recommended)" and up to three more; label each with its id prefix and title, and describe it with its date and turn count.
+1. **Which session.** The user may not know where sessions are stored, so offer them from the list above, never ask for a folder. If the arguments name a session or `--latest`, use it. Otherwise ask, offering the newest first as "(Recommended)" and up to three more; label each with its title, and describe it with its folder, date, turn count and `[desktop app]` when shown. If none fit, offer "show more" (`carry list --all --limit 30`), or search by a word from the title or folder (`carry list --all --match WORD`), or one folder (`carry list --project DIR`). If the user only wants sessions from the Claude desktop app (or only terminal ones), list them with `carry list --all --desktop` (or `--terminal`); each row's tag in brackets shows where it was started. Export by id: `carry export <id>` works from any folder.
 2. **Encrypt?** Options:
    - "No, plain file": readable by anyone who gets it (secrets are still redacted).
    - "Yes, generate a passphrase (Recommended when sending it to someone)": run with `--generate-passphrase`.

package/src/browse.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectFolders } from './store.js';
+import { parseJsonl, summarize } from './transcript.js';
+import { desktopSessionInfo, firstPrompt } from './desktop.js';
+
+// The desktop app runs a conversation that has no project folder in a scratch folder with a long account/org path.
+const SCRATCH = /\/scratch-workspaces\/[0-9a-f-]{36}\/[0-9a-f-]{36}(?:\/(.*))?$/;
+const tilde = (p, home) => {
+  const scratch = p && SCRATCH.exec(p);
+  if (scratch) return `(desktop scratch folder${scratch[1] ? `: ${scratch[1]}` : ''})`;
+  return p && home && (p === home || p.startsWith(home + path.sep)) ? `~${p.slice(home.length)}` : p;
+};
+
+// Programmatic agents (for example a memory plugin's background observer) record this entrypoint. They are
+// not conversations a person had, and on a machine with such a plugin they can outnumber real sessions 50 to 1.
+/**
+ * Where a session was started, from the entrypoint Claude records on every line: `claude-desktop` is the desktop
+ * app, `cli` the terminal, `sdk-cli` a `claude -p` run. A session the desktop app lists in its index counts as
+ * desktop even if it began elsewhere (for example one imported with --desktop).
+ */
+export function sourceOf(sum, inDesktopIndex) {
+  const e = sum.entrypoints;
+  if (inDesktopIndex || e.includes('claude-desktop')) return 'desktop';
+  if (e.includes('cli')) return 'terminal';
+  if (e.some((x) => x.startsWith('sdk'))) return 'print mode';
+  return e[0] ?? 'unknown';
+}
+
+const isBackgroundAgent = (sum) => sum.entrypoints.length > 0 && sum.entrypoints.every((e) => e === 'sdk-ts');
+
+/**
+ * The most recent sessions across every project folder, so nobody needs to know where Claude keeps them.
+ * Skips sessions with no prompts and background-agent sessions (unless `everything`). Each gets the title the
+ * desktop app shows for it when there is one, else Claude's own title, else the first prompt.
+ * `source` ('desktop' or 'terminal') keeps only sessions started there. `folders` restricts the search to those project folders; `match` keeps rows whose title, folder or id contains the text.
+ */
+export function recentSessions({ home, userHome, limit = 20, everything = false, folders, match, source }) {
+  const files = [];
+  for (const folder of folders ?? projectFolders(home)) {
+    if (!fs.existsSync(folder)) continue;
+    for (const n of fs.readdirSync(folder)) {
+      if (!n.endsWith('.jsonl')) continue;
+      const file = path.join(folder, n);
+      files.push({ file, folder, id: n.slice(0, -'.jsonl'.length), mtimeMs: fs.statSync(file).mtimeMs });
+    }
+  }
+  files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const desk = desktopSessionInfo({ home: userHome });
+  const needle = match ? String(match).toLowerCase() : null;
+  const out = [];
+  for (const x of files) {
+    if (out.length >= limit) break;
+    const entries = parseJsonl(fs.readFileSync(x.file, 'utf8'));
+    const sum = summarize(entries);
+    if (sum.turns === 0 || (!everything && isBackgroundAgent(sum))) continue;
+    const d = desk.get(x.id);
+    const row = { ...x, ...sum, source: sourceOf(sum, !!d), archived: !!d?.archived, label: d?.title || sum.title || firstPrompt(entries) || '(untitled)', where: tilde(sum.dominantCwd ?? x.folder, userHome) };
+    if (source && row.source !== source) continue;
+    if (needle && !`${row.label} ${row.where} ${row.id}`.toLowerCase().includes(needle)) continue;
+    out.push(row);
+  }
+  return out;
+}
+
+export const formatSession = (s, n) => {
+  const when = new Date(s.mtimeMs).toISOString().slice(0, 16).replace('T', ' ');
+  return `${n === undefined ? '' : `${String(n).padStart(2)}. `}${s.id.slice(0, 8)}  ${when}  ${String(s.turns).padStart(3)} turns  ${s.label}  [${s.source}${s.archived ? ', archived' : ''}]  ${s.where}`;
+};

package/src/cli.js

@@ -10,11 +10,14 @@ import crypto from 'node:crypto';
 import { isEncrypted } from './crypto.js';
 import { pushProject, pullProject } from './sync.js';
 import { registerDesktopSession, listDesktopDirs } from './desktop.js';
+import { recentSessions, formatSession } from './browse.js';
 
 const HELP = `carry (agent-carry): move coding-agent sessions between machines and folders. Supported agent: claude-code
 
-  carry list    [--all] [--project DIR]
-  carry export  <id|prefix|--latest> [-o FILE] [--project-root DIR]
+  carry list    [--all] [--project DIR] [--desktop | --terminal] [--match TEXT] [--limit N|all] [--everything]
+                (this folder, or --project DIR; --all: recent sessions from every folder; --desktop: only sessions
+                 from the Claude desktop app; --terminal: only terminal ones; --match: title, folder or id contains TEXT)
+  carry export  [id|prefix|--latest] [-o FILE]   no id: pick from a numbered list (also --desktop, --terminal, --project DIR, --match TEXT, --limit N) [--project-root DIR]
                 [--no-redact] [--redact-emails] [--strip-thinking | --allow-thinking-secrets]
                 [--generate-passphrase]   encrypt with a random passphrase saved next to the bundle as FILE.pass
   carry bundles                                            bundle files in this folder, ~/Downloads and ~/Desktop
@@ -32,7 +35,7 @@ Global: --claude-home DIR (default $CLAUDE_CONFIG_DIR or ~/.claude), --home DIR
 function parseArgs(argv) {
   const flags = {};
   const pos = [];
-  const valued = new Set(['-o', '--out', '--project', '--project-root', '--claude-home', '--home', '--name', '--passphrase-file', '--desktop-dir']);
+  const valued = new Set(['-o', '--out', '--project', '--project-root', '--claude-home', '--home', '--name', '--passphrase-file', '--desktop-dir', '--limit', '--match']);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a.startsWith('-') && a !== '-') {
@@ -43,6 +46,29 @@ function parseArgs(argv) {
   return { flags, pos };
 }
 
+/** One line from stdin, or null at end of input. Synchronous so the rest of the CLI stays simple. */
+function readLine() {
+  const buf = Buffer.alloc(1);
+  let line = '';
+  let got = false;
+  for (;;) {
+    let n;
+    try {
+      n = fs.readSync(0, buf, 0, 1, null);
+    } catch (e) {
+      if (e.code === 'EAGAIN') continue;
+      if (e.code === 'EOF') break;
+      throw e;
+    }
+    if (n === 0) break;
+    got = true;
+    const c = buf.toString();
+    if (c === '\n') return line.trim();
+    line += c;
+  }
+  return got ? line.trim() : null;
+}
+
 function fail(msg) {
   process.stderr.write(`carry: ${msg}\n`);
   process.exit(1);
@@ -60,22 +86,25 @@ function main() {
   const cwd = flags['project-root'] || flags.project || process.cwd();
   let passphrase = flags['passphrase-file'] ? fs.readFileSync(flags['passphrase-file'], 'utf8').replace(/\r?\n$/, '') : process.env.CARRY_PASSPHRASE || undefined;
   const say = (m) => flags.quiet || process.stdout.write(`${m}\n`);
+  // --desktop / --terminal on list and export: only sessions started in the desktop app / in a terminal.
+  const sourceFlag = () => {
+    if (flags.desktop && flags.terminal) fail('use --desktop or --terminal, not both');
+    return flags.desktop ? 'desktop' : flags.terminal ? 'terminal' : undefined;
+  };
 
   try {
     if (!cmd || cmd === 'help' || flags.help) return process.stdout.write(HELP);
 
     if (cmd === 'list') {
-      const folders = flags.all ? projectFolders(home) : [path.join(projectsDir(home), mangle(realpathOr(cwd)))];
-      let n = 0;
-      for (const f of folders) {
-        for (const s of listSessions(f)) {
-          n++;
-          const when = new Date(s.mtimeMs).toISOString().slice(0, 16).replace('T', ' ');
-          const where = flags.all ? `  ${s.dominantCwd ?? path.basename(f)}` : '';
-          process.stdout.write(`${s.id.slice(0, 8)}  ${when}  ${String(s.turns).padStart(3)} turns  ${s.title ?? '(untitled)'}${where}\n`);
-        }
-      }
-      if (!n) process.stdout.write(`no sessions found for ${flags.all ? 'any project' : realpathOr(cwd)}\n`);
+      // Default: this folder (or --project DIR), every session. --all: recent sessions from every folder.
+      const scope = flags.all ? undefined : [path.join(projectsDir(home), mangle(realpathOr(cwd)))];
+      const limit = flags.limit === 'all' ? Infinity : Number(flags.limit) || (flags.all ? 20 : Infinity);
+      const list = recentSessions({ home, userHome, limit, everything: !!flags.everything, folders: scope, match: flags.match, source: sourceFlag() });
+      for (const x of list) process.stdout.write(`${formatSession(x)}\n`);
+      const where = flags.all ? 'any project' : realpathOr(cwd);
+      const what = sourceFlag() ? `${sourceFlag()} ` : '';
+      if (!list.length) process.stdout.write(`no ${what}sessions found for ${where}${flags.match ? ` matching "${flags.match}"` : ''}${flags.all ? '' : '; try: carry list --all'}\n`);
+      else if (list.length === limit) process.stdout.write(`(showing the ${limit} most recent; --limit N or --limit all for more)\n`);
       return;
     }
 
@@ -91,8 +120,19 @@ function main() {
         if (!s) fail(`every session for ${realpathOr(cwd)} is empty (no prompts yet); run \`carry list\``);
         if (s !== all[0]) process.stderr.write(`carry: skipped ${all.indexOf(s)} newer empty session(s); exporting ${s.id.slice(0, 8)}\n`);
         target = { folder: here, id: s.id };
+      } else if (!pos[0]) {
+        // No id and no --latest: pick from recent sessions anywhere, so nobody needs to know where they are stored.
+        const scope = flags.project ? [path.join(projectsDir(home), mangle(realpathOr(flags.project)))] : undefined;
+        const list = recentSessions({ home, userHome, limit: Number(flags.limit) || 10, folders: scope, match: flags.match, source: sourceFlag() });
+        if (!list.length) fail('no sessions found' + (flags.match ? ` matching "${flags.match}"` : '') + '; nothing to export');
+        list.forEach((x, i) => process.stdout.write(`${formatSession(x, i + 1)}\n`));
+        process.stdout.write('Export which one? [1] ');
+        const ans = readLine();
+        if (ans === null) fail('no session chosen; pass an id (see `carry list --all`) or --latest');
+        const pick = list[(ans === '' ? 1 : Number(ans)) - 1];
+        if (!pick) fail(`"${ans}" is not one of the numbers above`);
+        target = { folder: pick.folder, id: pick.id };
       } else {
-        if (!pos[0]) fail('export needs a session id (see `carry list`) or --latest');
         // Same id can exist in several project folders (a session that was carried). Prefer the folder
         // named by --project, else the current one, and only then search everything.
         const scoped = path.join(projectsDir(home), mangle(realpathOr(flags.project || process.cwd())));
@@ -127,7 +167,7 @@ function main() {
       if (generated) fs.writeFileSync(`${out}.pass`, `${generated}\n`, { mode: 0o600 });
       const red = Object.entries(header.redaction.counts || {}).map(([k, v]) => `${k}:${v}`).join(' ') || 'none found';
       process.stdout.write(
-        `exported ${header.sessionId.slice(0, 8)} "${header.title ?? 'untitled'}" -> ${out}\n` +
+        `exported ${header.sessionId.slice(0, 8)} "${header.title ?? 'untitled'}" -> ${path.resolve(out)}\n` +
           `  parts: ${header.parts.length}   paths rewritten: ${header.pathsRewritten}\n` +
           `  redacted: ${header.redaction.enabled ? red : 'OFF'}   encrypted: ${passphrase ? 'yes' : 'no'}\n` +
           (generated ? `  passphrase saved to ${out}.pass (not printed); share it by a different channel than the bundle\n` : ''),

package/src/desktop.js

@@ -111,7 +111,7 @@ function lastModel(entries) {
   return model;
 }
 
-function firstPrompt(entries) {
+export function firstPrompt(entries) {
   for (const { rec } of entries) {
     if (rec?.type !== 'user' || rec.isMeta || rec.isSidechain) continue;
     const c = rec.message?.content;
@@ -189,3 +189,16 @@ export function registerDesktopSession({ id, root, mainFile, home, dir, platform
   fs.renameSync(tmp, dest);
   return { status: 'registered', file, dir: target, how, borrowed };
 }
+
+/** cliSessionId -> { title, archived } as the desktop app lists it. Empty when there is no desktop app data. */
+export function desktopSessionInfo({ home, platform }) {
+  const out = new Map();
+  try {
+    for (const { dir } of listDesktopDirs({ home, platform })) {
+      for (const { json } of readEntries(dir)) if (json.cliSessionId) out.set(json.cliSessionId, { title: json.title || null, archived: !!json.isArchived });
+    }
+  } catch {
+    // no desktop app, unreadable data, or a platform we don't know: this is a nicety, not a requirement
+  }
+  return out;
+}