Record how AI got there, not just what it built.
A structured journaling skill for Claude Code and opencode that captures the full reasoning process — investigations, hypotheses, failures, and decisions — as reviewable, reproducible documents.
When AI agents complete a task, you get the final result. But you lose:
- What was investigated and why
- Which hypotheses were formed
- What was tried and failed
- Why the final approach was chosen
tracecraft treats the work process itself as a deliverable, making it possible to review, reproduce, learn from, and audit AI-assisted work.
Each session generates a structured journal under .tracecraft/:
| File | Purpose |
|---|---|
worklog.md |
Chronological work log with steps, expectations, and actual results |
findings.md |
Investigation results — what was discovered and its impact |
troubleshooting.md |
Problem isolation, root cause analysis, and resolution |
decisions.md |
Key decisions with alternatives considered and trade-offs |
final-guide.md |
Reproducible step-by-step guide distilled from the work |
retrospective.md |
Lessons learned and reusable patterns |
Requires Python 3.6+ and Claude Code.
sh install.sh --global # all projects
sh install.sh --project # current project only
sh install.sh # interactiveThe installer:
- Copies the hook scripts to
.claude/hooks/ - Copies the skill definition to
.claude/skills/ - Registers the
UserPromptSubmitandPreCompacthooks in.claude/settings.json
Requires opencode.
sh install.sh --opencode --global # all projects (~/.config/opencode/)
sh install.sh --opencode --project # current project only (.opencode/)The installer:
- Copies the skill definition to
skills/tracecraft/SKILL.md - Copies the custom command to
commands/tracecraft.md - Installs templates to
.tracecraft/templates/
tracecraft works in two modes:
Once installed, the hook detects each new Claude Code session and automatically prompts journal initialization. Journals are updated in real-time as you work.
Run /tracecraft at the end of a session to generate all journal files at once from the conversation history. This is the default mode for opencode, which does not support hooks.
| Command | Description |
|---|---|
/tracecraft start [title] |
Start a new journal session |
/tracecraft step <name> |
Add a work step to the log |
/tracecraft finding <topic> |
Record an investigation result |
/tracecraft issue <name> |
Record a problem and its resolution |
/tracecraft decision <topic> |
Record a key decision |
/tracecraft finalize |
Generate the final guide and retrospective |
/tracecraft status |
Show current journal state |
sh uninstall.sh --global # Claude Code global
sh uninstall.sh --project # Claude Code project
sh uninstall.sh --opencode --global # opencode global
sh uninstall.sh --opencode --project # opencode project