Get deciduous running in your project in under two minutes. By the end of this page, you’ll have a live decision graph with your first connected chain of nodes.
Run deciduous init inside any git repository. This creates the .deciduous/ directory with a SQLite database and installs integration files for your AI assistant.
Terminal
$ cd ~/projects/my-api
$ deciduous init
Initialized deciduous in /Users/dev/projects/my-api/.deciduous/
Created .claude/commands/decision.md
Created .claude/commands/recover.md
Created .claude/commands/work.md
Created CLAUDE.md with decision graph workflow
That’s it for setup. The database is ready and your AI assistant now has instructions to log decisions automatically.
Every piece of work follows this path through the graph:
goal → options → decision → actions → outcomes
goal What you’re trying to achieve
option Possible approaches to consider
decision Choosing which option to pursue
action Implementing the chosen approach
outcome Results of the implementation
This isn’t arbitrary structure. It forces you to record why you chose an approach, not just what you built. Six months later, when someone asks “why didn’t we use WebSockets instead?”, the graph has the answer.
Created node 3 (type: option, title: In-memory token bucket with governor crate) [confidence: 75%] [branch: main]
$ deciduous link 1 2 -r "possible approach"
$ deciduous link 1 3 -r "possible approach"
Claude
Redis gives us distributed rate limiting across multiple instances and persistence across restarts. The governor crate is simpler but only works per-process. Since we're deploying to multiple pods, Redis is the better fit.
$ deciduous add decision "Use Redis sliding window — need distributed limiting across pods" -c 85
Created node 4 (type: decision, title: Use Redis sliding window — need distributed limiting across pods) [confidence: 85%] [branch: main]
$ deciduous link 2 4 -r "chosen — distributed across pods"
$ deciduous link 3 4 -r "rejected — single-process only"
Created node 6 (type: outcome, title: Rate limiting working — 8 tests passing, free=100/hr paid=1000/hr) [confidence: 95%] [branch: main]
$ deciduous link 5 6 -r "implementation result"
You now have six connected nodes forming a complete decision chain. Every node is linked to what came before it, creating a traceable path from the original goal to the final outcome.
Start the web viewer to see your decision graph rendered as an interactive visualization:
Terminal
$ deciduous serve
Serving decision graph at http://localhost:3000
Auto-refresh every 30s
Open http://localhost:3000 in your browser. You’ll see your nodes laid out as a directed graph, color-coded by type, with edges showing the reasoning chain.
You can also inspect the graph from the command line:
Terminal — inspecting the graph
$ deciduous nodes
ID Type Status Conf Title
────────────────────────────────────────────────────────────────
1 goal active 90% Add per-user API rate limiting with tiered limits
2 option active 80% Redis-backed sliding window with sorted sets
3 option active 75% In-memory token bucket with governor crate
4 decision active 85% Use Redis sliding window — need distributed limiting across pods
5 action active 85% Implement Redis rate limiter middleware with tier config
6 outcome active 95% Rate limiting working — 8 tests passing, free=100/hr paid=1000/hr
$ deciduous edges
From To Reason
──────────────────────────────────────────────────────
1 2 possible approach
1 3 possible approach
2 4 chosen — distributed across pods
3 4 rejected — single-process only
4 5 implementing chosen approach
5 6 implementation result
The next time someone opens this codebase and asks “why Redis instead of an in-memory solution?”, the graph has the answer: node 4, with the rationale right there in the edge labels.
Next, read the Workflow chapter to learn how to use deciduous throughout a full development session – including how to handle pivots when an approach fails.