Agent Studio CLI, files, and shortcuts

Command line

npx @sapiom/agent-studio@latest [dir] [options]

The command-line host requires Node.js 20 or newer and Claude Code available as claude on PATH. It prints the Node, Claude Code, and Git doctor results before startup. Git is reported but is not a launch gate.

Argument or option	Default	Exact behavior
`[dir]`	Current working directory	Resolves one folder to an absolute launch directory. A second positional argument is rejected.
`--port <n>`	`4100`	Requests a numeric local-server port. A missing or nonnumeric value is rejected.
`--login`	Off	When no cached Sapiom credential exists, completes browser sign-in before server startup. A cached credential is still reused; this does not force reauthentication.
`--no-auth`	Off	Skips reading the credential cache and skips startup authentication network access for this launch. The local server still requires its boot token, and Connect account remains available after Studio opens.
`--no-telemetry`	Off	Hard-disables both outbound telemetry tiers for this launch without changing the stored toggle values. The local event log is still written.
`--state-root <dir>`	`~/.sapiom/harness`	Relocates every Harness-owned path in the table below to one explicit root. It does not relocate shared credentials, analytics identity, Claude history, browser storage, desktop host data, or project files.
`--no-open`	Off	Keeps the server running without invoking the operating-system browser opener. Open the complete tokenized URL printed in the terminal.
`--no-session`	Off	Prevents automatic session creation on a returning launch. A genuine first launch already opens the welcome screen without a session.
`--dev`	Off	Internal diagnostic mode. Doctor, authentication, and consent still run; if server startup fails, the command reports that failure after verifying the pre-server flow instead of rethrowing it.

Unknown flags and extra positional arguments fail before Studio starts. Press Ctrl+C in the command-line host to close the server and its managed session processes; shutdown is bounded, so a second signal retains the operating system’s ordinary immediate-exit behavior.

Files and retention

Harness-owned global state

Unless --state-root is supplied, all paths in this table are under ~/.sapiom/harness/.

Path	Owner and lifetime
`machine-id`	Stable anonymous Studio install ID. Created on first use of this state root.
`sessions.json`	Studio’s session registry: working directory, coding-agent conversation ID when known, status, title, timestamps, and bound agent-project path. A running PTY itself is not persisted.
`workflows.json`	Registry of agent projects Studio has discovered or connected. It points to projects; it does not contain their source.
`settings.json`	Detailed-sharing choice, product-analytics choice, recent folders, project-root preference, first-run notice state, and background-summary choice.
`events.ndjson`	Append-only normalized local session events. Always written; newest data is retained within both 30 days and 50 MB. Corrupt lines are kept by the age pass but can fall out under the size cap.
`records/<session-id>.json`	Compact History records. Prompts and replies retain up to the collector’s 4,000-character field cap; tool input/result fields are clipped to 512 characters. The target is 64 KB per record, but one indivisible turn can exceed it; the hard store cap is 16 MB, with an age cap of 365 days. Oldest records leave first. Limitations are recorded in each reconstruction.
`generated/<session-id>/`	Per-session Claude Code settings, MCP configuration, hook emitter, system-prompt material, and optional rolling `summary.md`. Removed when the managed process exits; abandoned plain directories are eligible for a boot-time sweep after seven days. Live directories and symlinks are not swept.
`sample-project/`	Stable output location used only by the repository’s demo seed script. The running Studio neither creates nor reads it; an existing directory is leftover demo data.

Changing --state-root changes all eight paths together, including first-run detection and the consent notice’s printed local-event path. It does not create a privacy boundary around software outside Harness ownership; combine it with --no-telemetry for an outbound-silent disposable Studio run.

Session-directory files

Studio writes these inside the directory where a session runs:

Path	Contract
`.sapiom/harness-context.json`	Studio-owned current contract containing the session identity, bound agent, and all agent projects known to this Studio. It is refreshed on session creation, binding, and registry changes. Resume keeps a valid current file byte-for-byte, migrates the valid legacy shape, and reconstructs missing or invalid content before launching Claude.
`.sapiom/canvas/renders/<agent-slug>.html`	Studio-owned deterministic render for one bound agent. Coding agents should not edit these files.
`.sapiom/canvas/index.html`	Seeded unbound placeholder and optional custom-canvas fallback. Unlike `renders/`, an existing custom file is not overwritten by the deterministic pipeline.
`.sapiom/canvas/_template.html`	Pristine seeded Canvas document used as a local reference. Written only when missing.
`.sapiom/uploads/`	Images attached, pasted, or dropped into the composer before their local paths are sent to Claude Code.

The scaffolded .sapiom-dev/stubs.json file is different: it is authored, reviewable local-test input that belongs to the agent project. Do not classify it as removable Studio cache. The same applies to sapiom.json, agent source, package files, and Git history.

State outside the Harness root

Location	Owner
`~/.sapiom/credentials.json`	Cached Sapiom environments shared by Studio and the local authoring MCP. Standalone `@sapiom/tools` code does not read it automatically.
`~/.sapiom/analytics.json`	Analytics-core identity used by detailed telemetry clients. A normal Studio boot can migrate its machine ID into this shared identity once; an explicit `--state-root` boot does not seed the shared file.
`~/.claude/projects/<encoded-directory>/*.jsonl`	Claude Code’s own conversation transcripts. Studio scans the real-path and original-path encodings for History and native Resume; it never edits the global Claude configuration.
Browser local storage	`sapiom-harness-theme`, `sapiom-harness-ui-prefs`, `sapiom-harness-pane-widths`, and PostHog’s own identity/retry persistence for that origin.
Desktop operating-system app data	Electron host data plus the app-managed `runtime-bin` and `npm-global` directories. The exact parent is platform-specific.
Agent project directories	Your source and project-local `.sapiom/` / `.sapiom-dev/` files. Studio never moves them under its global state root.

Keyboard shortcuts

Use ⌘ on macOS and Ctrl on Windows/Linux unless a row says otherwise.

Shortcut	Scope	Result
`⌘`/`Ctrl`+`K` or `⌘`/`Ctrl`+`P`	Anywhere in Studio	Opens Quick Jump.
`↑`, `↓`, `Enter`, `Escape`	Quick Jump	Moves through results, opens the selected result, or closes the palette.
`⌘`/`Ctrl`+`1`…`9`	Anywhere in Studio	Selects that numbered live tab for the currently focused agent/folder. Tabs are numbered oldest first; no action occurs when the position does not exist.
`Escape`	Canvas	Clears the selected Canvas node first. Press again to leave expanded Canvas when no node is selected.
`⌘`/`Ctrl`+`Enter`	A step’s free-form Ask coding agent field	Sends the current step question.
`↑` / `↓`	Focused Canvas overview resize handle	Increases or decreases the overview height by 24 pixels.
`Home`	Focused Canvas overview resize handle	Resets the overview to automatic content height.

Most dialogs and popovers also close with Escape; when opened from a focusable control, focus returns to that control.