Iteration CLI

Connect a computer with the command shown on your Iteration workspace's overview:

npx iteration-cli connect --workspace <workspace ID>

--workspace connects to that workspace without a prompt. The collectors keep running from their own copy of the CLI, so the command does not need a global install. To keep the iteration command for status and later changes, install it globally:

npm install --global iteration-cli
iteration connect

The collectors run on macOS, Linux, or Windows with Node.js 22 or later. Cursor's local Agents window collector is tested on macOS. Each platform gets a background collector that starts at login and restarts on failure: a LaunchAgent on macOS, a systemd user service on Linux, and a scheduled task on Windows, which collects while the user is signed in. On Linux the CLI also enables background collection after logout. If server policy does not let the user enable this, an administrator must allow background services for the account. The setting applies to the whole Linux account and remains enabled after iteration disconnect; the CLI does not turn off other user services. iteration connect finds supported agents with local session directories, shows how many saved sessions each one has, asks once before uploading them and future activity, and connects them to one workspace. Saved sessions import newest first, and each collector reports its import progress to Iteration until it completes. A connected collector checks for newly detected supported agents and connects them under that approval. Each source has its own background process, local checkpoint, and upload queue. Run iteration to see connected sources, iteration status cursor for Cursor details, and iteration help for other commands. Source-specific connect commands remain available for advanced setups.

Cursor's This Mac Agents sessions are read from ~/.cursor/projects/*/agent-transcripts/<conversation>/<conversation>.jsonl. Connecting Cursor also installs user-level hooks in ~/.cursor/hooks.json automatically. They capture tool output, thought blocks, model and usage fields, subagent transcripts, and other lifecycle records that the main transcript omits; the collector queues those records locally before upload. Existing hooks are preserved, and iteration disconnect cursor removes only Iteration's entries. No Cursor approval or settings step is needed. A custom Cursor directory can be selected with iteration connect cursor --cursor-home DIR. Local history predating connection has transcript messages and tool calls, but tool results that Cursor never wrote to its transcript cannot be recovered. Cloud Agents are outside this local collector.

The collector replaces detected secrets with [REDACTED] before writing trace events to the upload outbox. It also redacts pending events left by an older collector before uploading them. This applies to Codex, Claude Code, and Cursor, including Cursor subagent transcript bytes stored as base64. Detection is best effort; original local agent files and previously uploaded traces are unchanged.

Claude Code sessions are read from ~/.claude/projects, including session subagents. If Claude uses CLAUDE_CONFIG_DIR, the collector follows that setting during connection; iteration connect claude --claude-home DIR selects another directory explicitly. The collector reads only saved local JSONL records. Claude Code may remove old transcripts under its own retention settings, so connect before local history is removed. The records can contain prompts, reasoning, tool input and output, and context snapshots; workspace members can read what uploads. Unknown record shapes are reported as capture gaps in the collector log. Remote Claude sessions are outside this local collector.

Connecting Codex or Claude Code also adds a Stop hook to the coding agent. After an agent turn in a git repository where you had friction episodes this week, it shows one line such as ◆ Iteration · 3 friction episodes in this repo this week · 1 new since yesterday. The hook reads local files only and adds a few milliseconds to a turn. Codex asks you to approve it once with /hooks. iteration disconnect removes it.

Iteration updates itself. Collectors run from their own copy of the CLI in ~/.config/iteration/runtime, so package-manager upgrades and removals never stop them. About every six hours a collector checks npm for a newer release, verifies its published hash, confirms it can read this computer's collector data, and switches to it; new releases reach computers gradually over six hours. If a new version stops three times on any source before completing a collection pass, collectors return to the previous version and skip that release. iteration shows the running version and any failed update. iteration update updates immediately, iteration update off turns automatic updates off, and iteration update --registry URL uses an npm mirror. A global iteration command older than the collectors hands each command to the installed version.

Computers that installed a release before 0.10.0 update once by hand: run npm install --global iteration-cli, then iteration.

To rescan older local sessions, preview with iteration import-history claude, then confirm with iteration import-history claude --yes. Use iteration start claude to restart collection and iteration disconnect claude to stop its background process without deleting local pending data.

If you previously installed the Codex-specific package, remove it with the package manager you used:

pnpm remove --global iteration-codex-collector
# Or, if you installed it with npm:
npm uninstall --global iteration-codex-collector

Then install iteration-cli and run iteration start codex. This points the existing background collector at the new CLI and schedules a one-time backfill of earlier local sessions. Its local configuration and pending events remain in place.