Import Your Coding-agent Conversations

Claude Code, Codex, and Cursor each write a log of every session onto the machine they run on. Import brings that history into the Conversations Dotabase as rows, which are searchable, connectable, and readable by the next agent you talk to.

Import runs from the dots CLI, reads the logs on the machine you run it from, and pushes them to the workspace your credential resolves to. Run it on the machine that holds the history; a hosted workspace has no view of your filesystem.

Before You Start

• The CLI installed and signed in. dots auth whoami should print your identity and company. Install the CLI covers the install.
• One of the three supported agents with local history: Claude Code, Codex, or Cursor.
• Nothing else. There is no connector to authorize and no token to paste — the logs are already on disk.

1. Know What A Source Is

Import does not treat "Claude Code" as one thing to switch on. It detects one source per session-bearing folder: Claude Code and Codex keep their sessions under your home directory, and Cursor keeps its conversations in an operating-system-dependent user-data store.

Each detected folder gets a stable identity — a source key of the form <platform>:<folder-hash> — and that key is the unit of everything below: consent, progress checkpoints, retries, and error reporting. Consenting to one project's history therefore does not consent to the folder next to it.

Detection itself reads no session content. It locates folders and enumerates the top-level sessions in them; nested subagent and workflow histories are left out, and Cursor's pre-consent pass counts conversations from an index without opening the content. Nothing is read until you say so.

2. Record Consent

Consent is a hard gate, and it fails closed: with no recorded decision the run refuses rather than proceeding. Absence of a decision is not permission, and a dismissed offer is not permission either.

Record it with --consent. Bare, it attests every source detected on this machine:

dots coding-agents sync --consent

To approve a single folder instead, name its key — --source is repeatable:

dots coding-agents sync --consent --source <platform>:<folder-hash>

If you target a source with no recorded consent, the command exits with a usage error naming --consent before the import machinery is even built: zero sessions read, zero data sent.

3. Back-fill The History

Once consent is on record, the one-shot backfill is the same command without the flag:

dots coding-agents sync

It walks every consented source and prints a summary of what it imported, skipped, and failed, per source. Failures are contained rather than fatal — a malformed session costs that one session, and the rest of a long history still lands. Anything that does fail is recorded so it can be retried rather than silently dropped.

4. Re-running Is Safe

Every session is identified by where it came from, so a second run is not a second copy:

• A session that has not changed since the last run is skipped.
• A session that has grown since the last run updates the row it already owns.
• Only a session that has never been seen creates a new row.

That holds across an overlapping backfill and tail, and across two runs racing each other — they converge on one row rather than duplicating it.

5. Keep It Current

To catch up and then stay caught up, use the tail instead. It performs the same catch-up backfill, then watches your consented folders and pushes each session as it changes:

dots coding-agents watch

It runs in the foreground until you interrupt it with Ctrl-C. Standard output stays empty and diagnostics go to standard error, so it composes cleanly in a pipeline. Only consented roots are ever watched, and consent recorded later is picked up without a restart.

6. Read What Landed

Imported sessions are ordinary rows in the Conversations Dotabase, so every read you already know works on them:

dots conversations list --limit 10 --level scan
dots conversations get CONVO-7
dots search "migration rollback" --dotabase conversations --limit 5

Those three lines are one pattern: survey, then select. --level scan reduces the listing to each session's id and title, which is what you need in order to name one. Search does the same job when you remember what was said but not which session said it. Then conversations get pulls the one you chose back whole. Both survey reads answer at summary without the flag, and --level full restores the widest record on either of them.

conversations get prints the conversation as an agent envelope — the same block a model would receive. In the app, open the Conversations Dotabase and it behaves like any other: filter it, group it, chart it, or walk its graph. Conversations describes what the Dotabase holds and how the rest of the platform reads it.

What Never Leaves Your Machine

• Unconsented folders are not read. The gate is checked before enumeration, not after.
• Secrets are scrubbed before anything is persisted, so a key pasted into a session three months ago does not become a row property.
• Detection is not import. Locating a folder and counting its sessions never opens their content.

Cursor Conversation Import records when the third provider arrived and the consent posture that shipped with it.