@assethub/cli 0.1.32 → 0.1.35

package/README.md

@@ -4,7 +4,7 @@ Command line interface for AssetHub.
 
 ## Quick setup
 
-Connect Claude Code and Codex to AssetHub in one step:
+Connect Claude Code, Codex and Cursor to AssetHub in one step:
 
 ```sh
 assethub setup                      # prompts for your API key and workspace
@@ -12,20 +12,51 @@ printf '%s' "$KEY" | assethub setup --api-key-stdin --workspace <id> --yes
 assethub setup --dry-run            # show every command and file change, change nothing
 ```
 
-Setup logs in (reusing a saved key), selects a workspace, registers the
-`assethub` MCP server in Claude Code (`claude mcp add-json ... --scope user`, run
-again safely), merges an `[mcp_servers.assethub]` section into
-`$CODEX_HOME/config.toml` (default `~/.codex`, original saved as
-`config.toml.bak-<timestamp>`), then runs `doctor --mcp` and prints a checklist
-(`--json` for machine output). Use `--client claude|codex|both` to limit the
-targets.
+`setup` runs these steps in order, and is safe to run again: each step checks the
+current state first and reports it as unchanged, updated, or (with `--dry-run`)
+what it would change.
+
+| Step | What it does |
+| --- | --- |
+| `login` | Reuses a saved key, or reads one from `--api-key-stdin`, `ASSETHUB_API_KEY` or a prompt. |
+| `workspace` | Uses `--workspace`, the saved selection, or asks you to pick one. |
+| agents | Finds Claude Code, Codex and Cursor on this machine (their folder or command), or uses `--agent`. |
+| `mcp` | Registers the `assethub` MCP server in each agent: Claude Code through `claude mcp add-json ... --scope user` (Claude Code owns `~/.claude.json`; when `claude` is not on PATH, for example with only an IDE extension, setup writes the same entry into that file itself), Codex as an `[mcp_servers.assethub]` section in `$CODEX_HOME/config.toml`, Cursor as `mcpServers.assethub` in `~/.cursor/mcp.json`. A file setup writes itself is backed up as `<file>.bak-<timestamp>` first and replaced in one step. If `claude mcp add` fails while replacing an outdated entry, the previous entry is put back. |
+| `skills` | Installs the bundled `assethub` skill under `~/.agents/skills/assethub` and links it into each agent's skill folder, so the agent knows the command sequence, cost rules and recovery steps. |
+| `app-env` | macOS: makes `ASSETHUB_API_KEY` visible to apps started from the Dock (see below). |
+| `doctor` | Runs `doctor --mcp` and prints a checklist (`--json` for machine output). |
+
+Choose agents with `--agent claude-code|codex|cursor` (repeat it, or separate
+names with commas; `claude` also works). Run only some steps with
+`--only <step,...>` or leave some out with `--skip <step,...>`; `--no-skills` and
+`--no-app-env` are short for skipping those. `--project` writes the MCP config
+and the skill into the current folder instead of your home folder
+(`.mcp.json`, `.codex/config.toml`, `.cursor/mcp.json`, `.agents/skills/assethub`
+with relative links), for a repository to share:
 
-MCP does not need the CLI. Setup is only a shortcut: both clients call the hosted
+```sh
+assethub setup --only skills --project   # put the agent guidance in this repository
+assethub setup --only mcp,skills         # wire the agents without logging in
+assethub doctor --setup                  # report missing or outdated MCP config and skill
+```
+
+`assethub doctor --setup` checks the same steps without changing anything and
+fails when an agent's MCP entry or the skill is missing or out of date; run
+`assethub setup` to fix it. Directories setup did not create are left untouched.
+After a CLI upgrade, the next command refreshes the installed skill automatically.
+Set `ASSETHUB_CLI_HOME` to redirect these writes, for example in tests.
+
+`assethub init` is deprecated: it now runs `setup --only mcp,skills` and prints
+the result as JSON, and will be removed in a later version. `--client
+claude|codex|both` still works and means the same as `--agent`.
+
+MCP does not need the CLI. Setup is only a shortcut: every agent calls the hosted
 `/api/mcp` server directly and read the key from the `ASSETHUB_API_KEY`
 environment variable. The Claude Code entry is
 `claude mcp add-json assethub '{"type":"http","url":"https://app.assethub.io/api/mcp","headers":{"Authorization":"Bearer ${ASSETHUB_API_KEY}","X-AssetHub-Workspace":"<id>"}}' --scope user`,
 so the key is never written to Claude Code's config or passed on a command line,
-and removing the CLI does not disconnect MCP. Codex uses `bearer_token_env_var`.
+and removing the CLI does not disconnect MCP. Codex uses `bearer_token_env_var`,
+and Cursor `${env:ASSETHUB_API_KEY}`.
 Setup never writes the key to a shell profile; run `assethub setup --print-env` to
 print the `export ASSETHUB_API_KEY=...` line, and export it in the shell that
 starts Claude Code or Codex. The key is redacted
@@ -146,8 +177,7 @@ authentication. Existing workspace keys and user-token login remain supported.
 ```sh
 assethub --version
 assethub doctor --mcp --profile my-workspace
-assethub init --dry-run
-assethub init
+assethub doctor --setup
 assethub mcp config --client cursor
 assethub mcp config --client codex
 ```
@@ -168,18 +198,8 @@ Use the same key as your CLI profile. Personal profiles include the selected
 For a different API origin, pass
 `--base-url https://your-host/prefix` (HTTP is accepted only for localhost).
 
-`init` sets up every supported coding agent found on this machine — Claude Code,
-Codex, and Cursor — in one step. It writes the hosted MCP entry into each agent's
-own configuration (merging with what is already there), installs the bundled
-`assethub` skill under `~/.agents/skills/assethub`, and links it into each agent's
-skill directory so the agent knows the correct command sequence, cost rules, and
-recovery steps without being told. Pass `--agent <name>` to choose agents
-explicitly, `--project` to write project-level MCP files into the current
-directory instead of your home, and `--dry-run` to see the plan without writing.
-`init` never stores a key: the MCP entries read `ASSETHUB_API_KEY` from the
-agent's environment. Directories that `init` did not create are left untouched.
-After a CLI upgrade, the next command refreshes the installed skill automatically.
-Set `ASSETHUB_CLI_HOME` to redirect all of these writes, for example in tests.
+To write these settings into each agent for you, run `assethub setup` (see
+Quick setup above).
 
 Explicit `--profile` uses that profile's key and origin, ahead of environment
 variables, including user tokens and workspace MFA proofs. A missing profile fails.
@@ -378,12 +398,19 @@ assembly was made. Follow a run started without `--wait` with
 While a V4 run works, `--wait`, `runs watch` and `runs get` show where it is.
 The receipt's `progress` field has the phase, a one-line summary, each part's
 state and the Blender assembly rounds, in the words of the canvas Part Composer
-card. `--wait` and `runs watch` print a stderr line only when it changes:
+card. `--wait` and `runs watch` print a stderr line, with the local time, only
+when the run really moves on (a new step, another mesh ready, a part kept with
+an issue, the end); part states that come and go do not print:
 
 ```text
-[run] 557d2a58-… running · Step 3 of 4 · Making the parts · 3 of 9 meshes ready · 4 redoing, 2 checking
+19:52  run 557d2a58  3/4 Making the parts · 3 of 9 meshes ready
+19:58  run 557d2a58  ⚠ kept with an issue: Cropped top · open hem at the lower chest
+20:05  run 557d2a58  ✗ FAILED · at 3/4 Making the parts · Blender assembly failed
 ```
 
+`production batch --wait` prints the same lines per image, named by letter and
+file name, and a status table every 5 minutes; see `docs/guides/production-batch.md`.
+
 ```sh
 assethub runs watch <run-id> --timeout-ms 7200000 --download --out-dir ./character
 assethub runs get <run-id>                                   # JSON receipt, progress included

package/dist/agentSetup.d.ts

@@ -1,24 +1,36 @@
 export declare const AGENT_IDS: readonly ["claude-code", "codex", "cursor"];
 export type AgentId = (typeof AGENT_IDS)[number];
-type AgentSpec = {
+export type AgentSpec = {
     id: AgentId;
     name: string;
-    /** Presence of this directory under home means the agent is installed. */
+    /** The command on PATH; finding it, or `detectDir` under home, means the agent is installed. */
+    binary: string;
     detectDir: string;
-    globalMcpPath: string;
-    projectMcpPath: string;
     skillDir: string;
     format: 'claude' | 'cursor' | 'codex';
 };
+export declare const AGENT_SPECS: readonly AgentSpec[];
+export declare const agentSpec: (id: AgentId) => AgentSpec;
+/** `--agent` values: repeatable or comma separated; `claude` is accepted for `claude-code`. Keeps AGENT_IDS order. */
+export declare const parseAgentIds: (values: string[]) => AgentId[];
+/** Agents installed here: their folder exists under home (or $CODEX_HOME for Codex), or their command is on PATH. */
+export declare const detectAgents: (home: string, findBinary: (name: string) => Promise<string | undefined>, codexHome?: string) => Promise<AgentId[]>;
 /** `ASSETHUB_CLI_HOME` keeps tests and sandboxes from writing into the real home directory. */
 export declare const cliHome: () => string;
 export declare const packagedSkillDir: () => string;
 export declare const canonicalSkillDir: (home: string) => string;
 export declare const mcpServerEntry: (format: AgentSpec["format"], baseUrl: string, workspaceId?: string) => Record<string, unknown>;
-type WriteStatus = 'created' | 'updated' | 'unchanged';
-type SkillStatus = 'installed' | 'updated' | 'unchanged' | 'kept-existing';
-export declare const installSkill: ({ home, version, dryRun, }: {
-    home: string;
+/** The `mcpServers.assethub` entry of a JSON config, or undefined when the file has none or cannot be read. */
+export declare const readJsonServer: (text: string | undefined) => unknown;
+/**
+ * Sets `mcpServers.assethub` in a JSON config and keeps every other key.
+ * Returns the new text, or the input unchanged when the entry already matches.
+ */
+export declare const mergeJsonServer: (path: string, text: string | undefined, entry: Record<string, unknown>) => string;
+export type SkillStatus = 'installed' | 'updated' | 'unchanged' | 'kept-existing';
+export declare const installSkill: ({ root, version, dryRun, }: {
+    /** The home folder, or the project folder for a project install. */
+    root: string;
     version: string;
     dryRun: boolean;
 }) => Promise<{
@@ -26,44 +38,27 @@ export declare const installSkill: ({ home, version, dryRun, }: {
     status: SkillStatus;
     version?: string;
 }>;
-type LinkStatus = 'linked' | 'relinked' | 'unchanged' | 'kept-existing';
+export type LinkStatus = 'linked' | 'relinked' | 'unchanged' | 'kept-existing';
 /**
  * Refresh an installed skill after a CLI upgrade. Runs before every command;
  * the steady-state cost is one small file read. Never throws — a read-only or
  * missing home must not fail the user's actual command.
  */
 export declare const syncInstalledSkill: () => Promise<void>;
-export type InitOptions = {
-    baseUrl: string;
-    workspaceId?: string;
-    /** Agent ids to configure; defaults to every agent detected under home. */
-    agents?: string[];
-    /** Write project-level MCP config into the working directory instead of the user's home. */
-    project?: boolean;
-    dryRun?: boolean;
-    cwd?: string;
-    home?: string;
-};
-export type InitReport = {
-    version: string;
-    dryRun: boolean;
-    scope: 'global' | 'project';
-    skill: Awaited<ReturnType<typeof installSkill>>;
-    agents: {
-        id: AgentId;
-        name: string;
-        detected: boolean;
-        mcp: {
-            path: string;
-            status: WriteStatus;
-        };
-        skill: {
-            path: string;
-            status: LinkStatus;
-        };
+export type SkillsReport = {
+    path: string;
+    status: SkillStatus;
+    version?: string;
+    links: {
+        agent: AgentId;
+        path: string;
+        status: LinkStatus;
     }[];
-    next: string[];
 };
-export declare const initAgents: (options: InitOptions) => Promise<InitReport>;
-export {};
+/** Installs the skill under `<root>/.agents/skills` and links it into each agent's skill folder under root. */
+export declare const installAgentSkills: ({ root, agents, dryRun, }: {
+    root: string;
+    agents: AgentId[];
+    dryRun: boolean;
+}) => Promise<SkillsReport>;
 //# sourceMappingURL=agentSetup.d.ts.map

package/dist/agentSetup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentSetup.d.ts","sourceRoot":"","sources":["../src/agentSetup.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,SAAS,6CAA8C,CAAA;AACpE,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhD,KAAK,SAAS,GAAG;IACf,EAAE,EAAE,OAAO,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;CACtC,CAAA;AAoCD,+FAA+F;AAC/F,eAAO,MAAM,OAAO,QAAO,MAA4C,CAAA;AAEvE,eAAO,MAAM,gBAAgB,QAAO,MACiC,CAAA;AAErE,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MACJ,CAAA;AA2B7C,eAAO,MAAM,cAAc,GACzB,QAAQ,SAAS,CAAC,QAAQ,CAAC,EAC3B,SAAS,MAAM,EACf,cAAc,MAAM,KACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAYxB,CAAA;AAED,KAAK,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAA;AA2EtD,KAAK,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,eAAe,CAAA;AAmC1E,eAAO,MAAM,YAAY,GAAU,4BAIhC;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;CAChB,KAAG,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,CAwBhE,CAAA;AAED,KAAK,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,eAAe,CAAA;AAkCvE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,IAAI,CAevD,CAAA;AAID,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAA;IAC/C,MAAM,EAAE;QACN,EAAE,EAAE,OAAO,CAAA;QACX,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,OAAO,CAAA;QACjB,GAAG,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,WAAW,CAAA;SAAC,CAAA;QACxC,KAAK,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,UAAU,CAAA;SAAC,CAAA;KAC1C,EAAE,CAAA;IACH,IAAI,EAAE,MAAM,EAAE,CAAA;CACf,CAAA;AAED,eAAO,MAAM,UAAU,GAAU,SAAS,WAAW,KAAG,OAAO,CAAC,UAAU,CA4EzE,CAAA"}
+{"version":3,"file":"agentSetup.d.ts","sourceRoot":"","sources":["../src/agentSetup.ts"],"names":[],"mappings":"AAiCA,eAAO,MAAM,SAAS,6CAA8C,CAAA;AACpE,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhD,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,gGAAgG;IAChG,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;CACtC,CAAA;AAED,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAyB3C,CAAA;AAED,eAAO,MAAM,SAAS,GAAI,IAAI,OAAO,KAAG,SACiB,CAAA;AAEzD,sHAAsH;AACtH,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,EAAE,KAAG,OAAO,EAOvD,CAAA;AAED,qHAAqH;AACrH,eAAO,MAAM,YAAY,GACvB,MAAM,MAAM,EACZ,YAAY,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,EACzD,YAAY,MAAM,KACjB,OAAO,CAAC,OAAO,EAAE,CAUnB,CAAA;AAMD,+FAA+F;AAC/F,eAAO,MAAM,OAAO,QAAO,MAA4C,CAAA;AAEvE,eAAO,MAAM,gBAAgB,QAAO,MACiC,CAAA;AAErE,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MACJ,CAAA;AA2B7C,eAAO,MAAM,cAAc,GACzB,QAAQ,SAAS,CAAC,QAAQ,CAAC,EAC3B,SAAS,MAAM,EACf,cAAc,MAAM,KACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAYxB,CAAA;AAED,+GAA+G;AAC/G,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,GAAG,SAAS,KAAG,OAQzD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,MAAM,EACZ,MAAM,MAAM,GAAG,SAAS,EACxB,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MA2BF,CAAA;AAID,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,eAAe,CAAA;AAmCjF,eAAO,MAAM,YAAY,GAAU,4BAIhC;IACD,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;CAChB,KAAG,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,CAwBhE,CAAA;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,eAAe,CAAA;AAkC9E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,IAAI,CAevD,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAC,EAAE,CAAA;CAC5D,CAAA;AAED,+GAA+G;AAC/G,eAAO,MAAM,kBAAkB,GAAU,2BAItC;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,EAAE,CAAA;IACjB,MAAM,EAAE,OAAO,CAAA;CAChB,KAAG,OAAO,CAAC,YAAY,CAMvB,CAAA"}

package/dist/agentSetup.js

@@ -1,53 +1,68 @@
 /**
- * `assethub init` and the skill sync that keeps its output current.
+ * The agent-facing half of `assethub setup`: which coding agents are on this
+ * machine, where their MCP config lives, and the skill they read on demand.
  *
  * Coding agents learn a tool from two local files: an MCP server entry in their
- * own config, and a skill directory they read on demand. `init` writes both for
- * every supported agent found on this machine, merging into existing config
- * rather than replacing it, and never touching credentials — the MCP entries
+ * own config, and a skill directory. `setup` writes both, merging into existing
+ * config rather than replacing it and never writing credentials: the MCP entries
  * reference `ASSETHUB_API_KEY` from the agent's environment.
  *
- * The skill is copied once to `~/.agents/skills/assethub` and symlinked into
- * each agent's skill directory. A version marker lets every later command
- * refresh the copy when the CLI has been upgraded, so agents never read rules
- * written for a version they are no longer running.
+ * The skill is copied once to `<root>/.agents/skills/assethub` (root is the home
+ * folder, or the project with --project) and symlinked into each agent's skill
+ * directory. A version marker lets every later command refresh the home copy
+ * when the CLI has been upgraded, so agents never read rules written for a
+ * version they are no longer running.
  */
 import { cp, lstat, mkdir, readFile, readlink, rename, rm, stat, symlink, writeFile, } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
-import { cwd as processCwd, env, pid } from 'node:process';
+import { env, pid } from 'node:process';
 import { fileURLToPath } from 'node:url';
-import { cliVersion, mcpConfig, validatedBaseUrl } from './setup.js';
+import { cliVersion, validatedBaseUrl } from './setup.js';
 export const AGENT_IDS = ['claude-code', 'codex', 'cursor'];
-const AGENTS = [
+export const AGENT_SPECS = [
     {
         id: 'claude-code',
         name: 'Claude Code',
+        binary: 'claude',
         detectDir: '.claude',
-        globalMcpPath: '.claude.json',
-        projectMcpPath: '.mcp.json',
         skillDir: '.claude/skills',
         format: 'claude',
     },
     {
         id: 'codex',
         name: 'Codex',
+        binary: 'codex',
         detectDir: '.codex',
-        globalMcpPath: '.codex/config.toml',
-        projectMcpPath: '.codex/config.toml',
         skillDir: '.codex/skills',
         format: 'codex',
     },
     {
         id: 'cursor',
         name: 'Cursor',
+        binary: 'cursor',
         detectDir: '.cursor',
-        globalMcpPath: '.cursor/mcp.json',
-        projectMcpPath: '.cursor/mcp.json',
         skillDir: '.cursor/skills',
         format: 'cursor',
     },
 ];
+export const agentSpec = (id) => AGENT_SPECS.find(agent => agent.id === id);
+/** `--agent` values: repeatable or comma separated; `claude` is accepted for `claude-code`. Keeps AGENT_IDS order. */
+export const parseAgentIds = (values) => {
+    const names = values.flatMap(value => value.split(',')).map(value => value.trim().toLowerCase()).filter(Boolean);
+    const ids = names.map(name => (name === 'claude' ? 'claude-code' : name));
+    const unknown = ids.filter(id => !AGENT_IDS.includes(id));
+    if (unknown.length > 0)
+        throw new Error(`Unknown agent: ${unknown.join(', ')}. Use --agent ${AGENT_IDS.join('|')}.`);
+    return AGENT_IDS.filter(id => ids.includes(id));
+};
+/** Agents installed here: their folder exists under home (or $CODEX_HOME for Codex), or their command is on PATH. */
+export const detectAgents = async (home, findBinary, codexHome) => {
+    const found = await Promise.all(AGENT_SPECS.map(async (agent) => (await isDirectory(join(home, agent.detectDir))) ||
+        (agent.id === 'codex' && codexHome !== undefined && (await isDirectory(codexHome))) ||
+        (await findBinary(agent.binary)) !== undefined));
+    return AGENT_SPECS.filter((_, index) => found[index]).map(agent => agent.id);
+};
 const SERVER_NAME = 'assethub';
 const SKILL_NAME = 'assethub';
 const VERSION_MARKER = '.assethub-cli-version';
@@ -92,16 +107,31 @@ export const mcpServerEntry = (format, baseUrl, workspaceId) => {
         },
     };
 };
-const writeJsonServer = async (path, entry, dryRun) => {
-    const text = await readText(path);
+/** The `mcpServers.assethub` entry of a JSON config, or undefined when the file has none or cannot be read. */
+export const readJsonServer = (text) => {
+    if (text === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed?.mcpServers?.[SERVER_NAME];
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Sets `mcpServers.assethub` in a JSON config and keeps every other key.
+ * Returns the new text, or the input unchanged when the entry already matches.
+ */
+export const mergeJsonServer = (path, text, entry) => {
     let document = {};
-    if (text !== undefined) {
+    if (text !== undefined && text.trim() !== '') {
         let parsed;
         try {
             parsed = JSON.parse(text);
         }
         catch {
-            throw new Error(`${path} is not valid JSON. Fix or move it, then rerun init.`);
+            throw new Error(`${path} is not valid JSON. Fix or move it, then rerun setup.`);
         }
         if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
             throw new Error(`${path} must contain a JSON object.`);
@@ -112,45 +142,11 @@ const writeJsonServer = async (path, entry, dryRun) => {
         (typeof document.mcpServers !== 'object' ||
             document.mcpServers === null ||
             Array.isArray(document.mcpServers)))
-        throw new Error(`${path} has a non-object "mcpServers" value. Fix or move it, then rerun init.`);
+        throw new Error(`${path} has a non-object "mcpServers" value. Fix or move it, then rerun setup.`);
     const servers = (document.mcpServers ?? {});
-    if (JSON.stringify(servers[SERVER_NAME]) === JSON.stringify(entry))
-        return 'unchanged';
-    const next = { ...document, mcpServers: { ...servers, [SERVER_NAME]: entry } };
-    if (!dryRun) {
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
-    }
-    return text === undefined ? 'created' : 'updated';
-};
-/** Replaces or appends one `[mcp_servers.assethub]` table; every other line is kept verbatim. */
-const writeTomlSection = async (path, section, dryRun) => {
-    const header = `[mcp_servers.${SERVER_NAME}]`;
-    const body = section.trimEnd();
-    const text = await readText(path);
-    const lines = (text ?? '').split('\n');
-    const start = lines.findIndex(line => line.trim() === header);
-    let next;
-    if (start === -1) {
-        const base = (text ?? '').trimEnd();
-        next = `${base ? `${base}\n\n` : ''}${body}\n`;
-    }
-    else {
-        const endOffset = lines
-            .slice(start + 1)
-            .findIndex(line => /^\s*\[/.test(line));
-        const end = endOffset === -1 ? lines.length : start + 1 + endOffset;
-        if (lines.slice(start, end).join('\n').trimEnd() === body)
-            return 'unchanged';
-        const before = lines.slice(0, start).join('\n').trimEnd();
-        const after = lines.slice(end).join('\n').trim();
-        next = `${before ? `${before}\n\n` : ''}${body}\n${after ? `\n${after}\n` : ''}`;
-    }
-    if (!dryRun) {
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, next);
-    }
-    return text === undefined ? 'created' : 'updated';
+    if (text !== undefined && JSON.stringify(servers[SERVER_NAME]) === JSON.stringify(entry))
+        return text;
+    return `${JSON.stringify({ ...document, mcpServers: { ...servers, [SERVER_NAME]: entry } }, null, 2)}\n`;
 };
 const readMarker = async (dir) => (await readText(join(dir, VERSION_MARKER)))?.trim();
 /**
@@ -182,11 +178,11 @@ const replaceSkillDir = async (source, target, version) => {
     if (hadTarget)
         await rm(previous, { recursive: true, force: true });
 };
-export const installSkill = async ({ home, version, dryRun, }) => {
+export const installSkill = async ({ root, version, dryRun, }) => {
     const source = packagedSkillDir();
     if (!(await isDirectory(source)))
         throw new Error('This CLI installation does not include the packaged agent skill.');
-    const target = canonicalSkillDir(home);
+    const target = canonicalSkillDir(root);
     const marker = await readMarker(target);
     // A directory without our marker is the user's own; leave it alone.
     const status = marker === undefined
@@ -259,53 +255,11 @@ export const syncInstalledSkill = async () => {
         // best effort
     }
 };
-export const initAgents = async (options) => {
-    const home = options.home ?? cliHome();
-    const cwd = options.cwd ?? processCwd();
-    const dryRun = options.dryRun ?? false;
-    const version = await cliVersion();
-    const requested = options.agents ?? [];
-    const unknown = requested.filter(id => !AGENT_IDS.includes(id));
-    if (unknown.length > 0)
-        throw new Error(`Unknown agent: ${unknown.join(', ')}. Use --agent ${AGENT_IDS.join('|')}.`);
-    const detected = new Map(await Promise.all(AGENTS.map(async (agent) => [agent.id, await isDirectory(join(home, agent.detectDir))])));
-    const selected = requested.length > 0
-        ? AGENTS.filter(agent => requested.includes(agent.id))
-        : AGENTS.filter(agent => detected.get(agent.id));
-    if (selected.length === 0)
-        throw new Error(`No supported coding agent found under ${home}. Pass --agent ${AGENT_IDS.join('|')} to choose one.`);
-    const skill = await installSkill({ home, version, dryRun });
-    const agents = [];
-    for (const spec of selected) {
-        const mcpPath = options.project
-            ? join(cwd, spec.projectMcpPath)
-            : join(home, spec.globalMcpPath);
-        const mcp = spec.format === 'codex'
-            ? await writeTomlSection(mcpPath, mcpConfig('codex', options.baseUrl, false, options.workspaceId), dryRun)
-            : await writeJsonServer(mcpPath, mcpServerEntry(spec.format, options.baseUrl, options.workspaceId), dryRun);
-        const link = await linkSkill(join(home, spec.skillDir), skill.path, dryRun);
-        agents.push({
-            id: spec.id,
-            name: spec.name,
-            detected: detected.get(spec.id) ?? false,
-            mcp: { path: mcpPath, status: mcp },
-            skill: link,
-        });
-    }
-    return {
-        version,
-        dryRun,
-        scope: options.project ? 'project' : 'global',
-        skill,
-        agents,
-        next: [
-            ...(env.ASSETHUB_API_KEY
-                ? []
-                : [
-                    "Provide ASSETHUB_API_KEY in each agent's environment; the MCP entries read it from there and never store it.",
-                ]),
-            'Restart the agent so it reloads MCP servers and skills.',
-            'Run `assethub doctor --mcp` to verify the connection.',
-        ],
-    };
+/** Installs the skill under `<root>/.agents/skills` and links it into each agent's skill folder under root. */
+export const installAgentSkills = async ({ root, agents, dryRun, }) => {
+    const skill = await installSkill({ root, version: await cliVersion(), dryRun });
+    const links = [];
+    for (const agent of agents)
+        links.push({ agent, ...(await linkSkill(join(root, agentSpec(agent).skillDir), skill.path, dryRun)) });
+    return { ...skill, links };
 };

package/dist/hooks/command.d.ts

@@ -9,6 +9,7 @@ export type HooksCommandDeps = {
     now?: () => Date;
     startUpload?: (sessionDir: string, profile?: string) => void;
     startSweep?: (profile?: string) => void;
+    startWorkingUpload?: (sessionDir: string, profile?: string) => void;
 };
 export declare const runHooksCommand: (argv: string[], deps?: HooksCommandDeps) => Promise<number>;
 //# sourceMappingURL=command.d.ts.map

package/dist/hooks/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/hooks/command.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IACjC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5D,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC,CAAA;AA+CD,eAAO,MAAM,eAAe,GAC1B,MAAM,MAAM,EAAE,EACd,OAAM,gBAAqB,KAC1B,OAAO,CAAC,MAAM,CAiIhB,CAAA"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/hooks/command.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IACjC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5D,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACpE,CAAA;AA+CD,eAAO,MAAM,eAAe,GAC1B,MAAM,MAAM,EAAE,EACd,OAAM,gBAAqB,KAC1B,OAAO,CAAC,MAAM,CAkIhB,CAAA"}

package/dist/hooks/command.js

@@ -2,7 +2,7 @@
 // runHooksCommand(argv).
 import { installHooks, sessionSaveDisclosure, uninstallHooks } from './install.js';
 import { listSessionDirs, readMeta } from './paths.js';
-import { saveSession } from './save.js';
+import { saveSession, spawnDetachedSessionUpload } from './save.js';
 import { canUploadSessions, resolveUploadAuth, uploadPending, uploadSession } from './upload.js';
 const USAGE = 'Usage: assethub hooks <install|uninstall|save|upload|list|status> [--client claude|codex] [--json]\n' +
     '  install|uninstall [--global]   (the current folder by default; --global for every project)\n' +
@@ -118,6 +118,7 @@ export const runHooksCommand = async (argv, deps = {}) => {
                     upload: { profile: uploadOptions.profile },
                     startUpload: deps.startUpload,
                     startSweep: deps.startSweep,
+                    startWorkingUpload: deps.startWorkingUpload ?? spawnDetachedSessionUpload,
                 });
                 // A hook must never fail the agent, so save always exits 0.
                 // Claude Code adds SessionStart hook output to the model's context, so

package/dist/hooks/save.d.ts

@@ -22,6 +22,12 @@ export type SaveSessionOptions = {
     startUpload?: (sessionDir: string, profile?: string) => void;
     /** Starts the background retry of pending sessions on SessionStart. */
     startSweep?: (profile?: string) => void;
+    /**
+     * Starts `assethub hooks upload --session <dir> --auto` for a session that is
+     * still running (Stop, PreCompact). Omitted: no upload while working. The
+     * hooks command passes spawnDetachedSessionUpload; tests pass a stub.
+     */
+    startWorkingUpload?: (sessionDir: string, profile?: string) => void;
 };
 export type SaveSessionResult = {
     sessionDir: string;
@@ -33,6 +39,8 @@ export type SaveSessionResult = {
 };
 /** SessionEnd: upload this session, then retry up to SWEEP_LIMIT older pending ones. */
 export declare const spawnDetachedUpload: (sessionDir: string, profile?: string) => void;
+/** Stop / PreCompact: upload this running session only; no sweep. */
+export declare const spawnDetachedSessionUpload: (sessionDir: string, profile?: string) => void;
 /** SessionStart: retry up to SWEEP_LIMIT pending sessions. */
 export declare const spawnDetachedSweep: (profile?: string) => void;
 export declare const retentionDays: (env: NodeJS.ProcessEnv) => number | null;
@@ -42,6 +50,12 @@ export declare const pruneSessions: (root: string, now: Date, days: number, keep
 export declare const ABANDONED_AFTER_MS: number;
 /** Sessions retried in the background per SessionStart / SessionEnd. */
 export declare const SWEEP_LIMIT = 3;
+/**
+ * A running session is uploaded at most this often. Claude Code app sessions
+ * stay open for days and rarely reach SessionEnd, so without this they would
+ * only be uploaded once abandoned (ABANDONED_AFTER_MS quiet, then a new session).
+ */
+export declare const WORKING_UPLOAD_INTERVAL_MS: number;
 /**
  * Copy + redact the transcript Claude Code keeps at `meta.transcriptPath`, and
  * collect its images. Runs once per SessionEnd and before an upload, never per

package/dist/hooks/save.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/hooks/save.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAgB,WAAW,EAAC,MAAM,YAAY,CAAA;AAChF,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,aAAa,CAAA;AAE9C,eAAO,MAAM,UAAU,KAAK,CAAA;AAC5B,eAAO,MAAM,eAAe,QAAmB,CAAA;AAC/C,eAAO,MAAM,sBAAsB,KAAK,CAAA;AASxC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oCAAoC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAA;IACvC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5D,uEAAuE;IACvE,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,SAAS,GAAG,UAAU,CAAA;CACjC,CAAA;AAYD,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,GAAI,YAAY,MAAM,EAAE,UAAU,MAAM,KAAG,IACgC,CAAA;AAE3G,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,IAC+B,CAAA;AAErF,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,CAAC,UAAU,KAAG,MAAM,GAAG,IAM/D,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,KAAK,IAAI,EACT,MAAM,MAAM,EACZ,MAAM,MAAM,KACX,OAAO,CAAC,MAAM,CAwBhB,CAAA;AAgFD,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,QAAqB,CAAA;AACpD,wEAAwE;AACxE,eAAO,MAAM,WAAW,IAAI,CAAA;AAK5B;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,MAAM,EAClB,UAAS;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAM,KAC/D,OAAO,CAAC,WAAW,GAAG,IAAI,CA6C5B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,KAAK,IAAI,EACT,mBAAmB,MAAM,KACxB,OAAO,CAAC,MAAM,CAmBhB,CAAA;AAED,eAAO,MAAM,WAAW,GAAU,UAAS,kBAAuB,KAAG,OAAO,CAAC,iBAAiB,CAkF7F,CAAA"}
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/hooks/save.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAgB,WAAW,EAAC,MAAM,YAAY,CAAA;AAChF,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,aAAa,CAAA;AAE9C,eAAO,MAAM,UAAU,KAAK,CAAA;AAC5B,eAAO,MAAM,eAAe,QAAmB,CAAA;AAC/C,eAAO,MAAM,sBAAsB,KAAK,CAAA;AASxC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oCAAoC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAA;IACvC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5D,uEAAuE;IACvE,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CACpE,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,SAAS,GAAG,UAAU,CAAA;CACjC,CAAA;AAYD,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,GAAI,YAAY,MAAM,EAAE,UAAU,MAAM,KAAG,IACgC,CAAA;AAE3G,qEAAqE;AACrE,eAAO,MAAM,0BAA0B,GAAI,YAAY,MAAM,EAAE,UAAU,MAAM,KAAG,IACP,CAAA;AAE3E,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,IAC+B,CAAA;AAErF,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,CAAC,UAAU,KAAG,MAAM,GAAG,IAM/D,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,KAAK,IAAI,EACT,MAAM,MAAM,EACZ,MAAM,MAAM,KACX,OAAO,CAAC,MAAM,CAwBhB,CAAA;AAgFD,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,QAAqB,CAAA;AACpD,wEAAwE;AACxE,eAAO,MAAM,WAAW,IAAI,CAAA;AAE5B;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAiB,CAAA;AAMxD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,MAAM,EAClB,UAAS;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAM,KAC/D,OAAO,CAAC,WAAW,GAAG,IAAI,CA6C5B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,KAAK,IAAI,EACT,mBAAmB,MAAM,KACxB,OAAO,CAAC,MAAM,CAmBhB,CAAA;AAED,eAAO,MAAM,WAAW,GAAU,UAAS,kBAAuB,KAAG,OAAO,CAAC,iBAAiB,CAgG7F,CAAA"}

package/dist/hooks/save.js

@@ -30,6 +30,8 @@ const spawnCli = (args, profile) => {
 };
 /** SessionEnd: upload this session, then retry up to SWEEP_LIMIT older pending ones. */
 export const spawnDetachedUpload = (sessionDir, profile) => spawnCli(['hooks', 'upload', '--session', sessionDir, '--auto', '--sweep', String(SWEEP_LIMIT)], profile);
+/** Stop / PreCompact: upload this running session only; no sweep. */
+export const spawnDetachedSessionUpload = (sessionDir, profile) => spawnCli(['hooks', 'upload', '--session', sessionDir, '--auto'], profile);
 /** SessionStart: retry up to SWEEP_LIMIT pending sessions. */
 export const spawnDetachedSweep = (profile) => spawnCli(['hooks', 'upload', '--pending', '--limit', String(SWEEP_LIMIT)], profile);
 export const retentionDays = (env) => {
@@ -155,6 +157,13 @@ const collectImages = async (sessionDir, transcript, cwd) => {
 export const ABANDONED_AFTER_MS = 2 * 60 * 60 * 1000;
 /** Sessions retried in the background per SessionStart / SessionEnd. */
 export const SWEEP_LIMIT = 3;
+/**
+ * A running session is uploaded at most this often. Claude Code app sessions
+ * stay open for days and rarely reach SessionEnd, so without this they would
+ * only be uploaded once abandoned (ABANDONED_AFTER_MS quiet, then a new session).
+ */
+export const WORKING_UPLOAD_INTERVAL_MS = 20 * 60 * 1000;
+const WORKING_UPLOAD_EVENTS = new Set(['Stop', 'PreCompact']);
 /** Events that copy and redact the transcript now; the rest only mark it changed. */
 const FULL_SAVE_EVENTS = new Set(['SessionEnd', 'Manual']);
 /**
@@ -312,6 +321,17 @@ export const saveSession = async (options = {}) => {
         if (full)
             await materializeSession(sessionDir, { env, transcriptPath });
         const result = { sessionDir, event };
+        if (uploadOn && options.startWorkingUpload && WORKING_UPLOAD_EVENTS.has(event)) {
+            const latest = await readMeta(sessionDir);
+            // Counts uploads any path started (an earlier Stop, SessionEnd, a sweep).
+            const lastStart = Math.max(Date.parse(latest?.lastWorkingUploadAt ?? '') || 0, Date.parse(latest?.lastUploadAttemptAt ?? '') || 0);
+            if (latest && now.getTime() - lastStart >= WORKING_UPLOAD_INTERVAL_MS) {
+                // Stamped before spawning, so the next few turns do not start more.
+                await updateMeta(sessionDir, latest, current => ({ ...current, lastWorkingUploadAt: now.toISOString() }));
+                options.startWorkingUpload(sessionDir, options.upload?.profile);
+                result.uploadStarted = true;
+            }
+        }
         if (event === 'SessionEnd') {
             const days = retentionDays(env);
             if (days != null)

package/dist/hooks/types.d.ts

@@ -39,6 +39,8 @@ export type SessionMeta = {
     abandoned?: boolean;
     /** How far the graph is compacted after uploads failed for size or time (0 = none). */
     compactLevel?: number;
+    /** When Stop or PreCompact last started a background upload of this running session. */
+    lastWorkingUploadAt?: string;
     /** Failed uploads in a row; spaces out the automatic retries. */
     failedAttempts?: number;
     /** Size of the live transcript the local copy was made from (before masking). */

package/dist/hooks/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/hooks/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE3C,MAAM,MAAM,SAAS,GAAG;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,gBAAgB,GAAG,UAAU,CAAA;AAEnE,MAAM,MAAM,YAAY,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAA;AAEvF,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,aAAa,CAAA;IACrB,MAAM,EAAE,YAAY,EAAE,CAAA;IACtB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,gGAAgG;IAChG,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sFAAsF;IACtF,SAAS,CAAC,EAAE,IAAI,CAAA;CACjB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/hooks/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE3C,MAAM,MAAM,SAAS,GAAG;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,gBAAgB,GAAG,UAAU,CAAA;AAEnE,MAAM,MAAM,YAAY,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAA;AAEvF,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,aAAa,CAAA;IACrB,MAAM,EAAE,YAAY,EAAE,CAAA;IACtB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,gGAAgG;IAChG,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wFAAwF;IACxF,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sFAAsF;IACtF,SAAS,CAAC,EAAE,IAAI,CAAA;CACjB,CAAA"}