Import your history

Import sessions recorded locally before you installed kcap, or bring in history you skipped during setup. Setup can import history for you; these commands let you preview and choose it yourself.

One command imports from every coding-agent format installed on this machine: Claude (~/.claude/projects/), Codex (~/.codex/sessions/), Gemini CLI (~/.gemini/tmp/), Pi (~/.pi/agent/), GitHub Copilot CLI (~/.copilot/session-state/), Cursor IDE (per-session transcripts under ~/.cursor/projects/), Kiro (~/.kiro/), OpenCode (~/.local/share/opencode/opencode.db), Antigravity (~/.gemini/antigravity/), Muse Code (~/.local/share/muse/sessions/), Grok Build (~/.grok/sessions/), and Mistral Vibe (~/.vibe/logs/session/). The import is idempotent — re-run it as often as you like; only missing or incomplete sessions get uploaded.

OpenCode needs a SQLite native library

OpenCode history lives in a local SQLite database, so the first OpenCode import downloads a small SQLite native library into ~/.cache/kcap (a one-time, per-platform fetch). For airgapped installs, point KCAP_SQLITE_NATIVE_BASE_URL at a mirror or a local copy. OpenCode is still captured live via the shipped plugin too (kcap plugin install --opencode) — importing and live capture aren’t mutually exclusive.

Antigravity is one vendor, two surfaces

Antigravity is Google’s agent product in two forms — the GUI IDE and the agy CLI — both sharing the ~/.gemini home. kcap import --antigravity backfills conversations from both roots: ~/.gemini/antigravity/brain/ (GUI) and ~/.gemini/antigravity-cli/brain/ (the agy CLI). It’s watermark-idempotent, so it’s safe to re-run alongside live capture (kcap plugin install --antigravity). On a machine that only has the agy CLI installed — no GUI — kcap setup still detects it and installs the shared capture plugin. Imported Antigravity sessions carry their transcript but not per-generation cost. If a recording has no recoverable working directory, repository filters cannot place it and a configured capture allow list excludes it.

You can also come back to this page later. Importing isn’t strictly an onboarding step; the same commands work for one-off backfills (“I’d forgotten about that session from last month, let me import just that one”).

kcap import

Preview the available sessions without uploading:

kcap import --discover
kcap import --discover --json

Then choose a scope:

kcap import                                  # interactive scope picker
kcap import --repo .                          # current repository
kcap import --repo acme/api --repo acme/web    # several repositories
kcap import --org acme                        # repositories owned by acme
kcap import --all                             # every discovered repository
kcap import --repo . --claude --codex         # selected agents only
kcap import --repo . --since 2026-01-01
kcap import --repo . --private
kcap import --repo . --yes                    # no confirmation prompt

In a non-interactive run, provide both a scope (--all, --org <owner>, or --repo) and --yes. Agent filters narrow that scope; they do not replace it. Available filters are --claude, --codex, --gemini, --pi, --copilot, --cursor, --kiro, --opencode, --antigravity, --muse, --grok, and --mistral-vibe.

Further options:

Option	Effect
--cwd <path>	Filter by working directory within the selected scope.
--session <id>	Import one session within the selected scope.
--min-lines <n>	Skip shorter sessions; default is 15 lines.
--skip-title	Skip local Claude/Codex title generation, which otherwise uses your agent subscription or configured provider key.
--generate-summaries	Also generate per-session summaries of completed work.
--reimport	Retry OpenCode sessions marked complete locally, for example after deleting their server copies. Has no effect on other vendors.

Capture allow lists and exclusions apply to imports too, including --all. --private changes visibility; it still uploads the session.

--org scopes the import to a single repo owner — the GitHub org (or user) that owns each session’s git remote, matched case-insensitively. It has two forms:

• --org <owner> — scope to that owner explicitly.
• bare --org — reuse the owner you last chose (remembered per-profile as the import_org config key) or, if none is remembered, pick one from the owners detected across your sessions in an interactive picker.

The remembered owner is per-profile, so it follows kcap use. A bare --org in a non-interactive run (no TTY) with nothing remembered is an error — pass --org <owner>, or run kcap import --org once interactively to choose and remember one.

Each run shows a confirmation summary (scope, matched count, repo samples, visibility) before uploading anything.

The command is resumable. Re-running with the same scope only uploads what’s missing or incomplete — there’s no “import was interrupted, start over” failure mode. Sessions upload most recent first, so your latest work appears in the dashboard earliest.

When the import doesn’t match as much as you expected

At the start of every run, kcap import prints a one-shot report of transcripts whose working directory no longer exists on disk — typically because the local repo directory has been renamed (e.g. ~/dev/foo-cli → ~/dev/bar-cli). Those sessions silently fall out of an --org / --repo scope because the CLI can’t run git inside a path that isn’t there any more.

Sessions recorded inside an ephemeral worktree (<project>/.claude/worktrees/<slug>, <project>/.capacitor/worktrees/<slug>, or any <project>/.<anything>/worktrees/<slug> shape) are transparently attributed to <project> when the project directory still exists, so deleted-worktree paths never need a remap. The import surfaces a one-liner above the missing-cwds report when this happens:

Attributed N sessions to a parent project via worktree path.

For the renamed-directory case, use kcap remap <old-path> <new-path>. See Renamed repo directories (kcap remap) for the command surface and matching rules.

Gemini imports recover the working directory from the recording’s initial session context when it is present. This lets repository and directory filters match those sessions. Recordings without that context remain unplaced; they are skipped when an allow list requires a known path or repository.

For Cursor specifically: only Agent-mode sessions ship per-session transcripts, so that’s what gets imported — Chat (Ask), Inline Edit (Cmd+K), and Tab autocomplete don’t fit the session model. Re-running is safe — a server-side tracker deduplicates events on (stream, eventId), so previously imported turns don’t get re-appended.

Source paths:

• Claude: ~/.claude/projects/
• Codex: ~/.codex/sessions/
• Gemini CLI: ~/.gemini/tmp/<project>/chats/
• Pi: ~/.pi/agent/sessions/
• Copilot: ~/.copilot/session-state/ (plus the pre-GA ~/.copilot/history-session-state/; session dirs without an events.jsonl are failed-startup scaffolding and are skipped)
• Cursor: ~/.cursor/projects/<workspace>/agent-transcripts/
• Kiro: ~/.kiro/sessions/cli/ — Kiro Crew sub-agents are nested under the chat that spawned them, read from Crew’s own records
• OpenCode: ~/.local/share/opencode/opencode.db (honours XDG_DATA_HOME)
• Antigravity: ~/.gemini/antigravity/brain/ (GUI) and ~/.gemini/antigravity-cli/brain/ (the agy CLI) — shares the ~/.gemini home; honours GEMINI_CLI_HOME
• Muse Code: ~/.local/share/muse/sessions/YYYY/MM/DD/<id>/session.jsonl, plus subagent child logs (honours XDG_DATA_HOME)
• Grok Build: ~/.grok/sessions/<encoded-cwd>/<sid>/updates.jsonl, plus its subagents (honours GROK_HOME)
• Mistral Vibe: ~/.vibe/logs/session/unified/<id>/, and the legacy ~/.vibe/logs/session/session_<ts>/messages.jsonl (honours VIBE_HOME)

What gets uploaded

Imports use the transcript data available from each agent: lifecycle, messages, tool calls, and usage where recorded. See What kcap captures for limits and controls. Existing transcripts can contain sensitive prompts and command output; review your scope before uploading.

If a past session contains data you don’t want on the server, either:

• Run with --private to keep it owner-only.
• Skip it by scoping the import (--repo or --cwd) to exclude it.
• After import, delete it from the server with kcap disable <sessionId> (irreversible server-side).

Repair a session with missing records

Capture and import keep transcript records up to 4 MiB each. A record that cannot be processed safely is replaced by a numbered capture-loss marker, and the session detail shows a warning; its file totals or plan may be incomplete. Earlier CLI versions cut records at 64 KB, which could drop the evidence of a large file write.

For an ended Claude or Codex session that you own, preview recovery from the local transcripts, then apply it:

kcap import --session <id> --repair-capture --dry-run
kcap import --session <id> --repair-capture

Recovery reads the local root and child transcripts, redacts them as a normal import does, and compares them with what the server holds. It restores missing file-tool records and recomputes the affected turns, file totals, and summaries. It creates no new sessions, and other kinds of omitted records can remain as reported gaps. --claude or --codex narrows local discovery; scope and filter options such as --all, --repo, or --since are refused in repair mode. If the transcript is missing or changes during the scan, the command refuses.

The command reports candidate and restored counts and any remaining gaps. It exits 0 when nothing is left missing, 2 when recovery completed with gaps left, and 1 on refusal, failure, or a repair still running when the CLI stops waiting after two minutes. A validated repair continues on the server regardless; the output prints its repair ID and latest phase, so check that before running it again.

Related

• Visibility & sharing — defaults and overrides for imported sessions.
• CLI commands — the full set, including kcap disable.