Sessions & projects¶
gdc remembers your work. Every conversation is a session that's saved as it happens, and sessions are organised by project so your history stays relevant to what you're working on. This page explains both.
Sessions¶
A session is one conversation with the agent, including every message and every tool it ran. Sessions are saved continuously — after each message and each completed action — so if gdc or your machine crashes, you lose at most the last few words being streamed, never your history.
Because sessions are durable, you can:
- Resume a previous session and keep going.
- Inspect exactly what the agent did, step by step.
- Audit past runs long after they finished.
Resuming¶
Each session has an id. Continue an earlier one from the command line:
In the terminal app, open a past session from the sessions list (the
/sessions slash command).
Resuming re-loads the conversation, not the side effects
Resuming brings back the conversation so the agent has context. It does not re-run the commands or edits from before — those already happened. This makes resuming safe.
Inspecting¶
gdc sessions list # recent sessions in this project
gdc sessions show <id> # full transcript of one session
gdc sessions show <id> --json # machine-readable, for tooling
Projects¶
A project is simply the directory you're working in. gdc figures out
which project you're in by looking for a version-control marker (a .git
folder) starting from your current directory and walking up; if it
doesn't find one, it uses the current directory itself.
Projects scope several things so they stay relevant:
- Sessions —
gdc sessions listshows only the current project's sessions by default. - Permissions — remembered approvals apply per project.
- Configuration — a project can have its own
.gdc/config.tomlthat overrides your user settings (see Configuration). - Memory — notes can be scoped to a project (see Memory).
Working across projects¶
Most commands accept flags to widen or change the scope:
gdc sessions list --all # every project
gdc sessions list --cwd /path/to/repo # a specific project, without cd
Subagent sessions¶
When the agent delegates work to a subagent, that subagent gets its own session, linked to the parent. This keeps the audit trail complete without cluttering your main history — you can hide subagent sessions or view the whole tree:
gdc sessions list --root-only # hide subagent sessions
gdc sessions list --tree # show the parent/child structure
Housekeeping¶
Sessions accumulate over time. You can clear out old ones in bulk: