Build history of your codebase. Inquire.
Track decisions as you go further with an expert that feels like it was in the room when the decisions were made.
Archaeology
Understand how existing code evolved. Map the decisions, pivots, and reasoning behind any codebase.
/decision-graph path/to/code
Pulse
Keep track of ongoing decisions. Log goals, actions, and outcomes in real-time as you work.
/recover
You
I just joined this project. Help me understand how the auth system evolved.
Claude
I'll use archaeology mode to trace the auth system's evolution. Let me examine the commit history and map the decision points.
Claude
deciduous add goal "Understand auth system evolution" -c 90 --date "2024-01-15"
Created node 1 (type: goal) [backdated: 2024-01-15]
Claude
Found the initial auth implementation in commit history. Session-based auth was the first approach.
Claude
deciduous add decision "Initial auth approach" -c 85 --date "2024-01-20"
Created node 2 (type: decision)
Claude
deciduous add action "Implemented session-based auth" --commit abc123 --date "2024-02-01"
Created node 3 (type: action) [commit: abc123]
Claude
I found a pivot point. Three months later, they switched to JWT. Let me capture why.
Claude
deciduous add observation "Sessions didn't scale across services" -c 90 --date "2024-04-15"
Created node 4 (type: observation)
Claude
deciduous add revisit "Reconsidering auth strategy for microservices" --date "2024-04-20"
Created node 5 (type: revisit)
Claude
deciduous link 4 5 -r "Session scaling issues forced rethink"
Created edge (4 -> 5 via leads_to)
Claude
deciduous add action "Migrated to JWT with refresh tokens" --commit def456 --date "2024-05-01"
Created node 6 (type: action) [commit: def456]
Claude
deciduous serve
Starting web viewer at http://localhost:3000
Claude
Auth System Evolution:
1 [goal] Understand auth system evolution
-> 2 [decision] Initial auth approach
-> 3 [action] Implemented session-based auth [commit: abc123]
PIVOT DETECTED:
-> 4 [observation] Sessions didn't scale across services
-> 5 [revisit] Reconsidering auth strategy for microservices
-> 6 [action] Migrated to JWT with refresh tokens [commit: def456]
Key insight: The microservices migration in Q2 2024 forced the auth pivot.
Claude
The auth system started with sessions, but pivoted to JWT when the team moved to microservices. The decision graph shows the exact reasoning and commits. You can explore it visually at localhost:3000 or ask about any specific decision.
Archaeology mode is for understanding existing codebases. When you join a project or need to understand "why is this like this?", archaeology helps you reconstruct the decision trail from commit history, PRs, and code patterns.
Pulse mode is for ongoing work. As you build, log decisions in real-time. When sessions end or teammates need context, the graph survives.
Both modes produce the same graph. Archaeology reconstructs history; pulse captures it live. Either way, you end up with queryable institutional memory.
Archaeology: Understand Any Codebase
Drop into an existing project and build a decision graph from its history. Perfect for onboarding, code review, or understanding legacy systems.
Reconstruct Evolution
Trace how code got to its current state. Map pivots where the approach changed. Link decisions to commits.
Find the Pivots
The revisit node type captures moments when the team changed direction. Understand why approach A was abandoned for B.
Backdate Nodes
Use --date "YYYY-MM-DD" to place decisions at their historical timestamps. Build accurate timelines.
Ask Claude
The web viewer's "Ask About This Code" feature lets you query narrative chains. Get explanations of complex evolution patterns.
Pulse: Track Ongoing Decisions
Log decisions in real-time as you work. When sessions end, context survives. When PRs need writeups, generate them from the graph.
Log Before You Act
Create goal and decision nodes before writing code. Forces clearer thinking and captures the reasoning.
Link Commits
Use --commit HEAD to link outcomes to git commits. Every commit becomes traceable to its goals.
Recover Context
New session? Use /recover to pick up where you left off. The graph remembers what you were working on.
Make Informed Decisions
Inquire about the code and your plans as if Claude was in the room when those plans were made and executed.
Claude Code Integration
Deciduous integrates deeply with Claude Code through skills, hooks, and commands. Run deciduous init to set up everything.
Claude Code deciduous init
Terminal Utilities
A full CLI for querying and managing your decision graph.
Node Types
A simple vocabulary for capturing how software evolves. Click any type to see an example.
Goal
What you're achieving
Option
Approaches considered
Action
What you implemented
Outcome
Results of actions
Observation
Insights discovered
Works With Any Claude Workflow
Deciduous is flexible. Use it however fits your style.
Full Integration
Use all the skills and hooks. Let Claude log decisions automatically as it works. Maximum context recovery.
Manual Logging
Run deciduous add yourself. Keep the graph updated without automated hooks.
Archaeology Only
Skip pulse mode entirely. Use deciduous just to understand existing codebases and document history.
PR Documentation
Use deciduous writeup to generate PR descriptions. Great even without the full workflow.
Quickstart
Get deciduous running in under a minute.
$ cargo install deciduous
Downloading deciduous v0.10.x
Installed deciduous to ~/.cargo/bin/deciduous
$ cd my-project && deciduous init
Created .deciduous/deciduous.db
Created .claude/commands/recover.md
Created .claude/commands/work.md
Ready! Use /recover to start a session.
Claude
Recovering context from decision graph...
deciduous nodes -n 5
No nodes yet. Fresh project. Ready to start!
Built With Itself
Deciduous was built using deciduous to track its own development. The graph you see at demo/ is the real decision trail from building this tool.
Self-Bootstrapped
From day one, every goal, decision, and outcome was logged. The tool proved itself by building itself.
Context Recovery Works
Multiple sessions lost context. Each time, /recover brought developers back up to speed.