# Sessions The word "session" names three different things in this stack, and most confusion about the daemon comes from blurring them. This chapter separates them, shows where each one lives on disk, and names the commands that answer the questions you will actually ask. The detail — every verb, every record shape, every refusal — lives in the installed **ccc-base** skill (`load /ccc-base` in a Claude seat); this page is the map, not the manual. ## The three things called a session 1. **A harness session.** One running agent process — Claude Code, Codex — with a UUID. Its transcript is `.jsonl` plus a sibling `/` directory under `$UCC_HOME/shared/projects//`. This is what your terminal pane is. 2. **A daemon client.** The same process, as `ccc-statusd` sees it: an entry in the daemon's session cache and, while its socket is open, in the connection register. `ccc-statusd session list` reads the register; `ccc-statusd status` prints the count. 3. **A session record.** A directory in the sessions root, `year=YYYY/month=MM/DD-HH-/`, holding an `INTENT.md`. This is the shared workspace of a piece of work: its board, its roster, its results. Many harness sessions join one session record. The first two are ephemeral and belong to a process; the third is durable and belongs to the work. The daemon ties them together through your **card**. ## From a running seat to its card and its session ```mermaid flowchart LR P["your seat: a process with a uuid"] -->|first prompt| C["your card: agents/short-id/short-id.md"] C -->|seat:| R C -->|owner:| T subgraph S["sessions root: year=YYYY/month=MM/DD-HH-slug/"] I["INTENT.md"] R["rosters/role-slug.md"] T["tasks/slug.md"] end ``` - **The short id.** The daemon addresses every seat by an 8-hex handle derived from its UUID. For a UUIDv4 (Claude Code, Kimi) it is the **first** 8 hex. For a UUIDv7 (Codex, Grok) it is the **last** 8 hex, because a v7 UUID opens with a timestamp and two Codex seats born in the same minute would otherwise share a handle. Every `session send`, `session read`, `check-health` and card path uses this handle. In a Codex seat, take the last 8 hex of the session id, never the first. - **The card.** On your first prompt the daemon births `agents//.md` in the sessions root. Its frontmatter carries `role`, `session`, `seat`, `host`, `claude-session-id`, `spawned-by`; you own `manifest` (what you exist to do), `status` (what you are doing now), `exit` (your own-exit claim) and the body sections `Memo`, `Todo`, `Notes`, `Handoff`. A card whose `seat:` is empty reads as vacant even while the process runs. The first `UserPromptSubmit` banner — `joined as agent ` — is the proof that hooks are live and the card exists; no banner, no hooks, no card. - **The seat.** `seat:` on your card points at a roster file, `rosters/-.md`, inside a session record. The roster is the charter of that seat: purpose, scope, who it reports to, its exit shape. A spawner seeds `session:` and `seat:` at birth; a seat you take yourself is one properties write on your own card. - **The session record.** Birthing `INTENT.md` at `year=YYYY/month=MM/DD-HH-/` is session birth; there is no scaffold. Subdirectories appear when something is first born in them: `tasks/` (the board), `rosters/` (who), `results/` (payload worth keeping), `decisions/`, `inbox/`, `code/`. One owner per fact: the card carries *now*, the roster carries *who*, the task carries *what*. ## The board `tasks/.md` files are the cards of a pull board — teammates read the board, not each other's messages. Each card has `status` in one of seven columns (`Backlog`, `Todo`, `In Progress`, `Waiting for others`, `Done`, `Canceled`, `Duplicate`) and an `owner` of the form `[[]]`. Claiming is a properties write of `owner` and `status`; moving is a properties write of `status`; a card that moved under you refuses with `fingerprint_mismatch` rather than losing the update. The owner never closes a card as `Done` — a reviewer does. The MCP `sql` tool over the sessions root lists a board in one query; the ccc-base skill has the query. ## Agent home, memos, and the work folder - `agents//` is your **agent home**: the card, `memos/`, and later `leases/`. It is flat — one directory per seat, under the root, not under a session. - A **memo** is one finding worth keeping past this conversation — a gotcha, a failed approach, a user correction — as one file at `agents//memos/.md` with `type: memo` and a `memo/` tag. Compound reads memos by their `session:` stamp and graduates them into the wiki; a memo written outside the record door has no stamp and is invisible to it. - Your **work folder** is outside the tree: `//`, by default `$UCC_HOME/work//`. Checkouts, builds, captures, git worktrees go there, never into the sessions root. When your process is gone the daily tick packs that folder into `agents//leases/.tar.zst` and removes it — so anything that must outlive you is promoted into the tree (a result into `results/`, a finding into a memo) while you live. ## What you never do in the sessions root A sessions root is a git repository, and it is committed by exactly one actor: `bin/sweep`, run by the daemon every ten minutes for every bound root. One cycle stages everything, commits, fetches and merges the canonical remote's `main`, pushes, copies annexed bytes to the special remote, and drops cold ones; its log is `/.ccc/sweep.log`. Agents never `git add`, `git commit`, `git push` or `git stash` there. Stash in particular is the trap: the tree is dirty by design with other seats' live work, and a stash reverts all of it silently while leaving the checkout looking clean. Records are born and changed through the MCP `put` tool (*Meridian tools*, folded under What you have); reads through `read` and `sql`. ## The commands you will ask questions with Every one of these prints its own contract with `--help`; the daemon binary is the authority, never a remembered flag. - `ccc-statusd status` — is the daemon up, how many sessions are connected. - `ccc-statusd session list --location global` — every connected seat on this host with role, model, token fill, status and liveness. A bare `list` is scoped to the current directory. The register is reborn empty at every daemon start (the header says `register since daemon start …`), so a young register is weak evidence that a seat is gone; `-a` includes cached disconnected ones. - `ccc-statusd session check-health ` — `healthy` (exit 0), `unreachable` (exit 1, process dead), `unknown` (exit 2, not in the registry). - `ccc-statusd session read ` — a seat's transcript as an outline: one line per message, tool runs folded, the position of any API error. It never wakes the seat. `--index 5,12-24` reads messages in full; `--usage` prints token usage only. - `ccc-statusd session send 'text'` — delivers over the daemon socket in an XML envelope naming the sender. The `Sent` tick means a non-empty body was accepted for delivery, not that it was read. `--needs-reply` marks that you expect an answer; `!@path` inlines a file at send time. - `ccc-statusd session schedule --in 10m 'text'` — an absolute-time alarm delivered as a message; `schedule list|get|delete` manage them. - `ccc-statusd session killme --delay 2` — ends the calling seat; a spawned pane closes itself. `restart` relaunches in place with history; `forkme` splits a parallel pane that inherits the parent's history. - `ccc-statusd session auq list|answer|resend` — the relay for a seat's pending `AskUserQuestion` dialog, so a person or another seat can answer it from outside the pane. - `ccc-agent list --table` — live agents by pane and role; liveness is computed from the process, never read from a file. Waking a seat that has been idle past the prompt cache's lifetime (about an hour) re-creates its whole context at full price — read it instead, and kill it from outside with the `CLAUDE_CODE_SESSION_ID=` override on `killme`. ## Where the detail lives - **ccc-base** — boot, the card, the board, memos, messaging, running and seating other agents, continuity. Reference files inside it: `session-dir.md` (the `INTENT.md` template and layout), `orchestration.md` (seating), `worker-continuity.md` (a worker's wrap-up), `hooks-reference.md` (the sensors that tell you to rotate). - **ccc-sessions-root** — where each byte goes, the storage doors and their refusals, `bin/init`, `bin/check`, `bin/sweep`. - **ccc-meridian** — `read`, `put`, `sql`, guarded writes, the refusal vocabulary. - **ccc-work**, **ccc-leader**, **ccc-advisor** — the role you play once seated.