Skip to content
Kapacitor 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.

Two commands handle the backfill: kapacitor import for Claude and Codex (which write .jsonl transcripts to disk), and kapacitor cursor import for Cursor IDE (which stores Composer/Agent-mode sessions in a local SQLite database). Both are idempotent — re-run them 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”).

Claude and Codex: kapacitor import

Section titled “Claude and Codex: kapacitor import”
Terminal window
kapacitor import --all                 # every session discovered on this machine
kapacitor import --org                 # sessions whose repo owner matches your active profile name
kapacitor import --repo owner/repo     # one specific repo
kapacitor import --repo .              # the repo at the current cwd

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. kapacitor 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.

Useful flags:

Terminal window
kapacitor import --org --yes                   # skip confirmation
kapacitor import --org --private               # mark every imported session as Only Visible to You
kapacitor import --codex --org                 # Codex rollouts from ~/.codex/sessions
kapacitor import --org --since 2026-01-01      # on or after this date
kapacitor import --org --cwd /path/to/project  # filter by working directory
kapacitor import --org --session abc123        # single session

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.

Source paths:

  • Claude: ~/.claude/projects/
  • Codex (with --codex): ~/.codex/sessions/

Cursor: kapacitor cursor import

Section titled “Cursor: kapacitor cursor import”

Cursor IDE doesn’t have a hook API, so its Composer/Agent-mode sessions can’t be captured live. Import them post-hoc from Cursor’s local SQLite state:

Terminal window
kapacitor cursor import                          # the current directory's Cursor workspace
kapacitor cursor import --workspace /path/to/proj
kapacitor cursor import --all                    # every Cursor workspace

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.

What gets uploaded

Section titled “What gets uploaded”

For each session, Kapacitor 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 kapacitor disable <sessionId> (irreversible server-side).
Section titled “Related”