Skip to content
Capacitor docs

Import your history

Once the CLI is set up and your first session is captured, you’ll usually want to backfill the work you ran before the hooks were in place. This is the last step in the standard onboarding flow.

One command imports from every coding-agent format installed on this machine: Claude (~/.claude/projects/), Codex (~/.codex/sessions/), and Cursor IDE (local SQLite). Cursor narrows to the current workspace by default; pass --cursor-all-workspaces to sweep them all. The import is idempotent — re-run it as often as you like; only missing or incomplete sessions get uploaded.

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

Section titled “kcap import”
Terminal window
kcap import                                   # everything detected (Cursor = current workspace)
kcap import --all                             # every session/repo (Cursor still narrows to current workspace)
kcap import --claude                          # only Claude sessions
kcap import --codex                           # only Codex sessions
kcap import --cursor                          # only Cursor (current workspace)
kcap import --cursor --cursor-all-workspaces  # only Cursor, every workspace
kcap import --cursor --cursor-workspace ~/p   # only Cursor, one specific workspace
kcap import --org                             # narrow by scope: org repos
kcap import --repo owner/name                 # narrow by scope: one repo
kcap import --repo .                          # narrow by scope: current cwd's repo
kcap import --org --yes                       # skip confirmation
kcap import --org --private                   # mark as Only Visible to You
kcap import --org --since 2026-01-01          # on or after this date
kcap import --org --cwd /path/to/project      # filter by working directory
kcap import --org --session abc123            # single session (dashed or dashless GUID)

You must pick an explicit scope. This is deliberate: without it, the command would happily upload your personal scratch repos, your private notes, and your client work to whichever tenant you happened to be logged into. If you run with no scope on an interactive terminal, you’ll get a picker. In a non-interactive run (no TTY, e.g. CI), missing both a scope flag and --yes is an error.

--org is a shortcut: it takes your active profile name and uses it as a GitHub org login to filter on. kcap setup names the profile after the picked tenant, so --org works out of the box for tenant-bound profiles. On the default profile, or a manually-named profile like work, use --repo <owner/name> instead.

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.

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

Section titled “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.

For Cursor specifically: only Composer/Agent-mode sessions are imported. Chat (Ask), Inline Edit (Cmd+K), and Tab autocomplete don’t fit the session model and are skipped. Sessions whose bubbles are still being generated are skipped until idle, so you don’t end up with half-imported turns. 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/
  • Cursor: local SQLite under Cursor’s user state dir (e.g. ~/Library/Application Support/Cursor/User/workspaceStorage/... on macOS; equivalent on Linux/Windows)

What gets uploaded

Section titled “What gets uploaded”

For each session, Capacitor uploads everything it would have captured live: lifecycle events, transcript turns, tool calls, token counts. There’s no separate sanitisation step — past sessions land in the dashboard exactly as new sessions do.

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).
Section titled “Related”