Store your first session, and bring in the old ones

Nothing special is needed. Once setup has finished, the hooks fire on their own

Run a session

In a repository, start the agent you normally use and give it anything to do:

cd ~/code/my-repo
claude          # or codex, gemini, cursor-agent, copilot, kiro-cli, opencode, pi, agy, muse, grok, vibe

One thing to know per agent: Codex asks you to trust the kcap hooks the first time it starts after setup; accept once. Agents that were already running need a restart. The rest is in Your coding agents

Watch it arrive

Open your workspace and choose Sessions. Within a few seconds a card appears with your repository, your avatar and a live status, and the title updates once the agent has started work. Open it: the transcript fills in turn by turn, and tool calls expand to show what ran and what came back

Setup ended by suggesting the guided tour. It is a set of seven questions you ask your agent about your own work, and you can start it in any stored session by typing Start kcap guided tour; Take the tour lists the questions

When you end the session the card changes to ended and, a little later, gains an outcome: a short account of what was done and what was left

If nothing shows up

Here are some troubleshooting steps to try, in order

1. Run kcap status and check three things: the server line names your workspace and says it is reachable, the auth line names you, and the line for the agent you used says it is wired. If the agent’s line shows an install command instead, run it
2. Was the agent already running when you ran setup? Restart it
3. Is it Codex? Accept the trust prompt, or trust the kcap hooks under Settings → Hooks in the Codex app
4. Is the folder excluded, or outside your allow list? kcap ignore --list and kcap allow --list
5. Is your default visibility private and are you signed into the web app as someone else? The session is there; only you can see it

For more troubleshooting steps, see My session doesn’t appear

Bring in the sessions you already have

Your agents have been writing transcripts to disk all along. Importing them gives recall something to work with from day one

If you said yes during setup, this already happened in the background. Otherwise, see what is there before you send anything:

kcap import --discover

Then choose a scope:

kcap import --repo .                    # this repository
kcap import --org acme                  # every repository owned by acme
kcap import --all                       # everything on this machine
kcap import --repo . --since 2026-06-01 --private

Every run shows what it matched and asks before uploading. It is safe to repeat: only sessions the server does not have yet are sent. Exclusions and allow lists apply to imports exactly as they do to live sessions, and --private makes the imported sessions owner-only whatever your default

If the import matches fewer sessions than you expected, the repository was probably renamed on disk since the sessions ran; Import found fewer sessions than expected shows how to map the old path

Further reading

• What you can do: the walkthroughs, if you want to skip the tour