Session logs

An agent's session is seen only by the people in it. When it ends, its transcript is gone from view, and with it every wrong turn, confusing doc and wasted step. A session log keeps what only the session knew, so the project can learn from work nobody watched.

Know agent session logs already? Skip to In Terrarium.

In Terrarium

Each session writes a session logOne agent session's own record of its work, kept in the Journal. The agent writes its goal, outcome and every Friction; the timings, tools and files it touched come from the transcript.GLOSSARY.md into the Journal, the Tenant where Terrarium documents itself. When its work reaches a coherent state, such as a PR opened or a question answered, the agent runs the close-session Skill, which calls log-session. The agent writes the judgement half into a scratch file: its goal, a status, an outcome, a summary, why the docs and Skills it names mattered, and every FrictionOne thing that went wrong in a session or cost it needless effort, which its agent records in the session log with a possible fix and a severity.GLOSSARY.md. The schema in shared/schemas/session.ts makes the list of Frictions required, even when it is empty:

132    // List EVERY friction — not just one or two. No `tag`: the Friction Ledger
133    // groups frictions by cause instead (GLOSSARY.md).
134    frictions: z.array(
135      z.object({
136        description: z.string(), // ~20 words — honest description
137        solution: z.string(), // possible fix / what would have helped
138        severity: z.enum(['nit', 'minor', 'moderate', 'major', 'blocker']),
139      }),
140    ),

The log-session Skill defines each severity grade.

At the end of that turn, a Stop hook in .claude/settings.json runs scripts/session/log-session.ts. It derives the mechanical half from the transcript with scripts/session/transcript-trace.ts, adding the files the session edited from its own commits so an edit made through a shell command counts, joins the two, checks the result against the schema, and commits that one file to main without a PR. Fallback hooks at session end and on resume land a log the Stop hook missed. If the work continues, say the PR merges, the session logs again and replaces its earlier log. No other session ever edits it.

Later sessions read the logs. One SkillA folder of instructions for one repeatable job, committed with the code, that a session runs when the job comes up.GLOSSARY.md groups Frictions by root cause in the Friction LedgerThe Journal's list of Friction causes, one entry per root cause with every session that hit it and every PR meant to fix it, so a problem that keeps coming back is counted across weeks.GLOSSARY.md, with every session that hit each cause and every PR meant to fix it, and turns the ones worth fixing into PRs or issues. Another reads which Skills sessions used, and a Prune TrialAn instruction cut back to its goal and left that way for a while, so the problems later sessions report decide whether it comes back.GLOSSARY.md takes the Frictions logged while it stands as its verdict. Logs from outside agents are marked external, and both Skills skip them.

Where next

• LessonCLAUDE.md
• LessonPull requests
• LessonSelf-improvement loop
• LessonScheduled tasks
• JournalFriction Ledger