Tape

Using tape

Tape archives coding-agent sessions into a local store the user owns, makes them searchable, and can replay them into another agent. Run tape like any shell command.

Output contract

• stdout is one JSON object {"schema_version":1,"data":{...}} whenever it is piped (always the case for you). Parse data, ignore unknown fields.
• Errors arrive on stderr as JSON: {"error":"<type>","message":"...","suggestion":"...","retryable":bool}.
• Exit codes: 0 ok · 1 error · 2 usage error · 3 no results · 10 dry-run passed. Branch on exit codes, not output text. Exit 3 still emits valid data with count: 0 — empty is not a failure.
• tape schema [command...] returns the full command/flag tree as JSON. Prefer it over --help parsing.

Core workflows

Refresh the archive first (cheap and idempotent — checksums skip unchanged sessions):

tape sync                          # local agents
tape sync --remote user@host       # also pull from an SSH machine
tape sync --full                   # re-archive everything (after a parser bump)

tape ls --host local               # hide remote-mirrored sessions
tape ls --host user@host           # only sessions from that remote
tape search "auth" --host user@host

Picker rows from remote hosts are tagged with a dim @host badge, and the Resume action on a remote row execs ssh <host> -t 'cd <cwd> && <agent> --resume <id>' automatically — you land inside the conversation on the right machine without copy-pasting anything.

Find past context (CJK queries fully supported):

tape search "jwt refactor" --limit 5
tape search "为什么不用 oauth2" --dir . --since 30d --agent claude-code
tape search codex                  # also matches by agent / title / project
tape search "memory leak" --sort relevance   # classic BM25 ranking

Default sort is recent — newest session first, capped at 5 hits per session so one long conversation can't push fresher matches off the page. Use --sort relevance for classic BM25 ranking when mining old archives. Each hit has session_id, snippet, title, project, timestamp. Every session also has a synthetic @meta row in the index so agent names, session titles and project names are searchable too. Every session has a synthetic @meta row in the index, so agent names, session titles and project names are searchable too — useful for "all my codex sessions about auth" style queries. Combine with --agent / --dir for precise filtering. --dir <path> (use . for the current directory) narrows by the session's working directory.

Paginate large result sets — both ls and search accept --limit N --page P (1-based) and return page, page_size, has_more, total (ls only) in JSON. Iterate until has_more is false.

Read a session:

tape ls --dir . --since 7d         # list; ids accept any unique fragment
tape show <session-id>             # full session with messages
tape overview                      # archive-wide stats

Continue a session in another agent (the user hit a token limit, or wants to switch tools):

tape restore <session-id> --to codex --dry-run   # preview plan, exit 10 = ok
tape restore <session-id> --to codex             # returns resume_command
tape restore @last --to cursor --strategy brief --llm none   # handoff file

Agents must always pass <session-id> and --to. Run with no args only on a real TTY; in that case tape opens a numbered picker (session → target agent → strategy). Piped or --json invocations always demand both args and exit 2 otherwise, so scripts stay deterministic.

Strategies, highest fidelity first:

auto (default) picks native if the target supports it, otherwise memory. For agents the recommended call is explicit, e.g. tape restore @last --to cursor --strategy memory --json.

Export the archive (or a filtered slice) as one file — or split across several. Tape only generates the snapshot — uploading to S3/git/Drive is the caller's job, by design:

tape export                                    # tape-export-<ts>.tar.zst in cwd
tape export snapshot.tar.gz --compress gzip    # explicit name + codec
tape export --agent codex --since 7d           # filter-scoped slice
tape export --exclude-agent cursor,opencode    # everything except those two
tape export --exclude-host local               # only remote-mirrored sessions
tape export --dir . --format zip --compress none  # current project as a .zip
tape export --split-by agent                   # one file per agent
tape export --split-by month --since 1y        # one file per calendar month
tape export --split-by size --split-size 200M  # 200 MiB buckets
tape export --split-by agent --jobs 4          # 4 chunks at a time
tape export --scan-only                        # audit secrets, write nothing

--format tar|zip × --compress zstd|gzip|xz|none (zip implies its own DEFLATE so --compress zstd etc. is a usage error). Default is tar+zstd. For large archives use --split-by none|size|agent|month to fan out; the chunk discriminator (agent name / YYYY-MM / part-001 …) is inserted before the extension and every chunk is listed under parts[] in the JSON envelope.

--jobs N controls parallelism for chunked exports: chunks run concurrently (capped at min(N, chunk-count)) and the remaining budget feeds each chunk's zstd encoder, so total threads stay ≈ N. --jobs 0 (default) is GOMAXPROCS; --jobs 1 is the reproducible single-thread baseline. JSON output adds split.jobs + split.encoder_concurrency so agents can verify the actual run shape.

Every filter flag has an --exclude-* counterpart on ls / search / export: --exclude-agent, --exclude-dir, --exclude-host. Each is repeatable (--exclude-agent cc --exclude-agent oc) or comma-separated (--exclude-agent cc,oc); the same agent-name normalization (canonical + shorthand + did-you-mean) applies. --exclude-host local is the natural "remote-only" idiom; positive and negative on the same axis layer as AND-NOT (--agent codex --exclude-dir /tmp). Secrets in session.json are redacted in stream ([REDACTED:<rule>] for text, length-preserving masks for binaries); pass --no-redact for verbatim bytes. --scan-only is exit 0 even when findings exist — it's an audit mode, not a gate (the redactor is the gate, and it always runs on real exports).

Keep the archive fresh — tape sync is idempotent and cheap, but the user has to remember to run it. Three options, lowest to highest effort:

tape sync                                # ad-hoc, on demand
tape sync --install --interval 1h        # systemd timer / LaunchAgent / schtasks
tape sync --status                       # is one installed?
tape sync --uninstall                    # remove it

--install writes a user-scoped job — systemd user timer on Linux (~/.config/systemd/user/tape-sync.timer), LaunchAgent on macOS (~/Library/LaunchAgents/com.tapeai.sync.plist), or a printed schtasks /Create command on Windows. The job runs as the user, never root. Repeat --remote user@host flags are preserved in the unit file so scheduled syncs cover remote machines too.

Versioning & updates — no background pings; checks are explicit:

tape version                       # version, commit, build date, install method
tape update --check                # any newer release? exit non-zero if so
tape update                        # upgrade in place via the matching installer
tape update --channel beta --dry-run
tape update --mirror gitee         # pin a release mirror (or TAPE_MIRROR=gitee)

tape update reads the install method from tape version and runs the right thing: npm install -g @tapeai/tape@<tag> for npm, go install github.com/chenhg5/tape/cmd/tape@<tag> for go install. Homebrew / manual installs get the suggested command printed but nothing is executed.

Release mirrors — every release lands on both github.com/chenhg5/tape and gitee.com/cg33/tape. The CLI races a HEAD probe at update time and uses whichever responds first, so mainland-China users get the Gitee path automatically. Agents that need deterministic behavior should pin with TAPE_MIRROR=github or TAPE_MIRROR=gitee; the tape update --json payload reports mirror so audit logs and bug reports can include it without an extra round-trip.

Operations log — tape history reads ~/.tape/operations.log (one JSONL line per sync / export / restore / update with scope, counts, bytes, duration, exit_code). Useful for "what did the agent's last sync archive?" without piecing it together from stdout. Disable with TAPE_NO_OPLOG=1.

Persistent defaults — tape config is the place to store preferences that would otherwise live in shell aliases:

tape config set defaults.exclude_agents cursor,opencode
tape config set defaults.jobs 4
tape config list --json
tape config unset defaults.jobs

CLI flags still win when explicitly passed; for slice values (exclude_*) configured defaults are merged with command-line flags. Agents that need deterministic behavior should pass every relevant flag explicitly and not rely on whatever config the human left behind.

Completion — tape completion {bash,zsh,fish,powershell} for shell tab-completion (see the command's --help for per-shell install locations). Re-run after upgrades.

Uninstall — tape uninstall [--dry-run|--force|--keep-archive] removes the scheduler unit, the archive + index, the operations log, and prints the install-method-specific command for the binary itself (we never auto-delete /usr/local/bin/tape).

Verbose diagnostics — -v / --debug on any command sends diagnostic lines (source detect paths, scheduler payloads, GitHub URL, chunk plans) to stderr. Useful when "tape sync didn't pick up iflow" surfaces — the debug line tells you exactly which path was probed and what was returned.

Conventions

• Session ids look like codex/019ea0af-...; any unique fragment resolves, @last means the most recent session.
• --agent / --to accept full names, the obvious aliases (claude/kimi/mimo), and a 2-letter shorthand: cc claude-code, cx codex, cu cursor, oc opencode, gm gemini, ag antigravity, qw qwen, qd qoder, if iflow, ad aider, mi mimocode, kc kimi-code. Case and separators are ignored (Claude_Code works); unknown names produce a usage error with a "did you mean…" hint. Agents should still pass the canonical spelling — the shorthand exists for humans typing in a terminal.
• --dry-run first for anything that writes (restore, export).
• All timestamps are RFC 3339; --since accepts 24h, 7d, 2026-01-31.
• The archive lives in $TAPE_HOME (default ~/.tape; legacy $TAPE_DIR is still honored). There is no --dir for tape's storage location on purpose: --dir on ls/search/restore filters by the project directory, not tape's data dir.
• Subcommand names accept any unambiguous prefix (tape sy → sync, tape sho → show, tape re → restore). For agents, always spell out the full name to stay forward-compatible if new commands are added.