Sessions¶

Every interactive run is persisted as a JSONL file under ~/.letscode/sessions/<cwd-hash>/<uuid>.jsonl. One JSON object per line, one line per MessageEnd event.

Continuation¶

letscode -c

Continues the most recent session for the current working directory. The conversation history is reloaded, the system prompt is recomputed (so newly added skills / tools are visible), and the agent picks up where it left off.

Ephemeral runs¶

letscode --no-session "one-off question"

Skips persistence entirely. Use for piped pipelines, CI checks, or anything you don't want in the session history.

File format¶

The JSONL envelope:

{ "_v": 2, "msg": { "role": "user", "id": "...", "content": [...], "timestamp": ... } }
{ "_v": 2, "msg": { "role": "assistant", "id": "...", "content": [...], "tool_calls": [...], ... } }
{ "_v": 2, "msg": { "role": "tool", "id": "...", "tool_call_id": "...", "content": [...], ... } }
{ "_v": 2, "msg": { "role": "custom", "kind": "compaction", "payload": {...}, ... } }

• _v: 2 is the format version. v1 files still load (entries get a synthesized parent_id chain).
• parent_id lives on the envelope (not shown above for brevity) — entries form a tree, not a flat list, even though the default UX is linear. Tree navigation shipped in v0.4: /tree (numbered chain), /fork [n] (branch a new session at entry n), /clone (duplicate and continue on the copy).

Custom messages¶

The role: "custom" entries are letscode-specific. They live in the transcript but are not sent to the LLM by default. The most common kind is compaction — when the context window is approached, the agent collapses older turns into a single summary CustomMessage(kind="compaction") and the built-in plugin renders it as a synthetic assistant message at LLM-call time.

Plugins can define their own CustomMessage.kind values and render them via the letscode_render_custom_message hook. See Extension model for the contract.

Locations¶

The <cwd-hash> is a stable hash of the working directory's absolute path — sessions are scoped per project location, so -c continues the right conversation regardless of which repo you're in.