Document Format

Structure

Session documents are markdown files with YAML frontmatter:

---
session: 05304d74-90f1-46a1-8a79-55736341b193
agent: claude
model: null
branch: null
---

# Session: Topic Name

## User

Your question or instruction here.

## Assistant

(agent writes here)

## User

Follow-up. You can also annotate inline:

> What about edge cases?

Frontmatter fields

All fields are optional and default to null.

Frontmatter parsing

Delimited by ---\n at the start of the file and a closing \n---\n. If frontmatter is absent, all fields default to null and the entire content is treated as the body.

Interaction modes

Append mode

Structured ## User / ## Assistant blocks. Each run appends a new assistant response.

Inline mode

Annotations anywhere — blockquotes, edits to previous responses, comments in the body. The diff captures what changed; the agent addresses inline edits alongside new ## User content.

Both modes work simultaneously because the run sends a diff, not a parsed structure.

Components

Documents can contain components — named, re-renderable regions marked with HTML comment pairs:

<!-- agent:status -->
| Field | Value |
|-------|-------|
| build | passing |
<!-- /agent:status -->

Components are updated via agent-doc patch or by agents/scripts. Their content can be replaced, appended to, or prepended to based on configuration in .agent-doc/components.toml.

Regular HTML comments (<!-- like this -->) remain a private scratchpad — they're stripped during diff and never trigger responses. Component markers look like comments but are structural and preserved.

See the Components guide for full details.

History rewriting

Delete anything from the document. On next run, the diff shows deletions and the agent sees the cleaned-up document as ground truth. This lets you:

• Remove irrelevant exchanges
• Consolidate scattered notes
• Restructure the conversation
• Correct earlier context