$ brew tap notactuallytreyanastasio/tap
$ brew install deciduous
DECIDUOUS
A living decision graph for your codebase. Build one retroactively from git history. Keep it alive as you work. Recover full context when sessions end. Ask it questions. Attach evidence. Share it with your team.
Claude Code — entering an existing project
You
/decision-graph ../snowflex
Claude
Building a decision graph from the snowflex commit history. Let me analyze the repo...
Claude
git -C ../snowflex log --oneline --after="2024-01-01" | wc -l
347 commits found
Claude
I see 347 commits across 8 months. Let me trace the major narratives — I'll collect commits into stories before building the graph...
Claude
deciduous add goal "Query engine evolution" -c 95 --date "2024-01-15"
Created node 1 (type: goal) [confidence: 95%] [branch: main]
Claude
deciduous add action "Initial SQL parser with hand-rolled tokenizer" --date "2024-01-20" --commit a3f8c12
Created node 2 (type: action) [commit: a3f8c12]
Claude
deciduous add observation "Hand-rolled parser can't handle nested subqueries" -d "3 bug reports in March all traced to parser limitations with nested subqueries" --date "2024-03-10"
Created node 3 (type: observation)
Claude
deciduous archaeology pivot 2 "Parser can't handle nested subqueries" "Switch to sqlparser-rs crate" -c 90 -r "Hand-rolled parser too fragile"
Created observation #4, revisit #5, decision #6
Linked: 2 → 4 → 5 → 6
Marked node 2 as superseded
Linked: 2 → 4 → 5 → 6
Marked node 2 as superseded
Claude
deciduous status 2 superseded
Updated node 2 status: pending → superseded
Claude
Built graph from 347 commits: 28 nodes, 31 edges, 3 pivot points.
Key narratives discovered:
1. Query engine evolution (8 nodes, 2 pivots)
2. Connection pooling strategy (6 nodes, 1 pivot)
3. Auth middleware redesign (5 nodes)
Run deciduous serve to explore, or deciduous pulse to see the summary.
Key narratives discovered:
1. Query engine evolution (8 nodes, 2 pivots)
2. Connection pooling strategy (6 nodes, 1 pivot)
3. Auth middleware redesign (5 nodes)
Run deciduous serve to explore, or deciduous pulse to see the summary.
Breakout Feature
/decision-graph — Build a Graph from Git History
Point it at any repository. Claude reads every commit, traces the narratives — what got built, what got replaced, where the pivots happened — and builds a connected decision graph. Grounded entirely in what's in the repo. No speculation.
Claude Code — analyzing 14 months of commits
You
/decision-graph
Claude
I'll analyze the commit history and build narratives first, then construct the graph. Let me start with the full log...
Claude
git log --oneline --after="2024-01-01" -- src/
Reading 847 commits... tracing key identifiers across their full lifecycle...
Claude
Found 4 major narratives. Writing to narratives.md before building the graph:
Claude
## Cache Strategy
Concepts: cache, LRUCache, cacheTimeout, invalidate
Lifecycle:
- cache: introduced (a1b2c3d), changed (e4f5g6h), renamed to LRUCache (x1y2z3)
- cacheTimeout: introduced (e4f5g6h), removed (i7j8k9l) ← switch to Redis TTL
PIVOT: In-memory LRU → Redis (memory pressure at scale)
Concepts: cache, LRUCache, cacheTimeout, invalidate
Lifecycle:
- cache: introduced (a1b2c3d), changed (e4f5g6h), renamed to LRUCache (x1y2z3)
- cacheTimeout: introduced (e4f5g6h), removed (i7j8k9l) ← switch to Redis TTL
PIVOT: In-memory LRU → Redis (memory pressure at scale)
Claude
deciduous add goal "Caching strategy" -c 95 --date "2024-02-01"
Created node 1 (type: goal) [backdated: 2024-02-01]
Claude
deciduous add action "In-memory LRU cache" -d "Initial cache. Sources: a1b2c3d 'Add in-memory cache for hot queries'" --date "2024-02-15" --commit a1b2c3d
Created node 2 (type: action) [commit: a1b2c3d]
Claude
deciduous archaeology pivot 2 "Memory pressure at 10k RPM — LRU consuming 1.2GB" "Switch to Redis with TTL-based invalidation" -c 90 -r "In-memory cache doesn't scale"
Created observation #3, revisit #4, decision #5
Linked: 2 → 3 → 4 → 5
Marked node 2 as superseded
Linked: 2 → 3 → 4 → 5
Marked node 2 as superseded
Claude
Graph built. Every action cites a real commit SHA. Every observation comes from commit messages or code.
Run deciduous pulse to see the summary, or deciduous serve to explore visually.
Run deciduous pulse to see the summary, or deciduous serve to explore visually.
Attach Evidence & Ask Your Graph Questions
Attach screenshots, PDFs, and architecture diagrams to decision nodes. Then ask questions — the built-in Q&A interface grounds answers in your actual decision history with full-text search across all stored interactions.
Claude Code Session
You
Here's the architecture diagram for the new caching layer
[Attached: cache-architecture.png]
Claude
I'll attach that to the caching goal node with an AI-generated description.
Claude
deciduous doc attach 1 /tmp/cache-architecture.png --ai-describe
Attached document 1 to node 1 (goal: Caching strategy)
Claude
AI Description: Architecture diagram showing Redis cache layer between API gateway and PostgreSQL, with TTL-based invalidation and write-through strategy for user profiles. Hot path latency annotated as <12ms p95.
Claude
Attached and described. Now future sessions can see this diagram when recovering context. The description makes it searchable via the Q&A interface too.
You
Why did we switch from in-memory caching to Redis?
Claude
deciduous nodes --type revisit
Claude
Revisit #4: Reconsider caching strategy
Reason: "In-memory cache doesn't scale"
Observation #3: "Memory pressure at 10k RPM — LRU consuming 1.2GB"
New decision #5: "Switch to Redis with TTL-based invalidation"
Document: cache-architecture.png attached to Goal #1
Grounded in: commit a1b2c3d, commit i7j8k9l
Reason: "In-memory cache doesn't scale"
Observation #3: "Memory pressure at 10k RPM — LRU consuming 1.2GB"
New decision #5: "Switch to Redis with TTL-based invalidation"
Document: cache-architecture.png attached to Goal #1
Grounded in: commit a1b2c3d, commit i7j8k9l
Claude
The in-memory LRU cache was consuming 1.2GB at 10k requests/minute. The pivot to Redis with TTL invalidation is captured in revisit node #4, with the architecture diagram attached to the caching goal.
Skill: pulse
Keep the Pulse — Log Decisions as You Work
The pulse skill is what makes deciduous a living document. As you work, Claude logs goals before implementing, tracks which options you considered, records what you chose and why, and links outcomes to commits. Run deciduous pulse anytime to see the health of your graph.
Claude Code — normal development session
You
Add rate limiting to the API endpoints
Claude
I'll add rate limiting. Let me log this goal first and map the options.
Claude
deciduous add goal "Add API rate limiting" -c 90 --prompt-stdin << 'EOF'
Add rate limiting to the API endpoints
EOF
Created node 42 (type: goal) [confidence: 90%] [branch: main]
Claude
deciduous add option "Token bucket per user" -c 85
deciduous add option "Sliding window counter" -c 75
deciduous link 42 43 -r "possible_approach"
deciduous link 42 44 -r "possible_approach"
Created nodes 43, 44 (options)
Created edges 42 → 43, 42 → 44
Created edges 42 → 43, 42 → 44
Claude
Token bucket is simpler and battle-tested. Going with that.
Claude
deciduous add decision "Token bucket — simpler, proven at scale" -c 90
deciduous link 43 45 -r "chosen"
Created node 45 (type: decision)
Claude
deciduous add action "Implement token bucket middleware" -c 85 -f "src/middleware/rate_limit.rs"
deciduous link 45 46 -r "implementation"
Created node 46 (type: action) [files: src/middleware/rate_limit.rs]
Claude
Implementing rate limit middleware...
Writing: src/middleware/rate_limit.rs
Claude
deciduous add outcome "Rate limiting working — 100 req/min per user" -c 95 --commit HEAD
deciduous link 46 47 -r "implementation complete"
Created node 47 (type: outcome) [commit: c8d3e2f]
Claude
deciduous pulse
Claude
=== PULSE ===
Summary:
Nodes: 47 | Edges: 52
Types: goal(6) option(8) decision(5) action(14) outcome(10) observation(4)
Active Goals:
#42 [goal] Add API rate limiting [90%]
├── #43 [option] Token bucket per user (chosen)
├── #44 [option] Sliding window counter
├── #45 [decision] Token bucket — simpler, proven
└── #47 [outcome] Rate limiting working [commit: c8d3e2f]
Summary:
Nodes: 47 | Edges: 52
Types: goal(6) option(8) decision(5) action(14) outcome(10) observation(4)
Active Goals:
#42 [goal] Add API rate limiting [90%]
├── #43 [option] Token bucket per user (chosen)
├── #44 [option] Sliding window counter
├── #45 [decision] Token bucket — simpler, proven
└── #47 [outcome] Rate limiting working [commit: c8d3e2f]
Command
/recover — Pick Up Where You Left Off
New session? Context compacted? /recover reads the decision graph, checks attached documents, audits for disconnected nodes, and gives Claude full context — far richer than what compaction preserves.
Claude Code — new session, context was compacted
You
/recover
Claude
Recovering context from decision graph...
Claude
deciduous nodes --branch main
deciduous edges
deciduous commands
deciduous doc list
git log --oneline -10
Claude
Branch: main
Active Goals:
#42 [goal] Add API rate limiting [90%] ✓ completed
#48 [goal] Add WebSocket support [85%] in progress
↳ #49 [decision] Use tokio-tungstenite [90%]
↳ #50 [action] Implementing WS handler [85%]
Attached documents (1):
cache-architecture.png on Goal #1 (Caching strategy)
Last 3 commits:
c8d3e2f feat: add rate limiting middleware
a1b7f3c feat: websocket connection handler (WIP)
e9d4c2a test: rate limit integration tests
Active Goals:
#42 [goal] Add API rate limiting [90%] ✓ completed
#48 [goal] Add WebSocket support [85%] in progress
↳ #49 [decision] Use tokio-tungstenite [90%]
↳ #50 [action] Implementing WS handler [85%]
Attached documents (1):
cache-architecture.png on Goal #1 (Caching strategy)
Last 3 commits:
c8d3e2f feat: add rate limiting middleware
a1b7f3c feat: websocket connection handler (WIP)
e9d4c2a test: rate limit integration tests
Claude
Rate limiting is done (commit c8d3e2f). You're mid-implementation on WebSocket support —
the WS handler exists but isn't complete (node 50). You chose tokio-tungstenite for the implementation.
Want me to continue the WebSocket work?
Command
/work — Start a Work Transaction
Before any implementation, /work creates the goal node with your verbatim request, then tracks actions and outcomes as Claude writes code. Commits get linked to the graph automatically.
Claude Code Session
You
/work Add email verification to the signup flow
Claude
deciduous add goal "Add email verification to signup" -c 90 --prompt-stdin << 'EOF'
Add email verification to the signup flow
EOF
Created node 51 (type: goal) [confidence: 90%]
Claude
Goal #51 created. I'll implement email verification and track each step.
Claude
deciduous add action "Implement verification token generation and email sending" -c 85 -f "src/auth/verify.rs,src/email/templates.rs"
deciduous link 51 52 -r "implementation step"
Created node 52 (type: action) [files: src/auth/verify.rs, src/email/templates.rs]
Claude
Implementing...
Writing: src/auth/verify.rs, src/email/templates.rs, src/routes/verify.rs
Claude
deciduous add outcome "Email verification working" -c 95 --commit HEAD
deciduous link 52 53 -r "implementation complete"
deciduous sync
Created node 53 (type: outcome) [commit: f2a8b1c]
Exported graph: 53 nodes, 58 edges
Exported graph: 53 nodes, 58 edges
Skills
Narratives & Archaeology — Maintain the Story
The narratives skill helps maintain a living document (.deciduous/narratives.md) tracking how each subsystem evolved and where it pivoted.
The archaeology skill transforms those narratives into queryable graph structure — creating revisit nodes, superseding old approaches, and connecting the timeline.
Claude Code — maintaining decision history
You
The auth system has changed a lot. Can you trace the narrative and structure it in the graph?
Claude
deciduous narratives init
Created .deciduous/narratives.md with 6 active goal titles
Claude
I'll read the code and fill in the auth narrative. Looking for signs of pivots — two approaches coexisting, comments about "we used to do X", deprecation warnings...
Claude
## Auth Strategy
> How users authenticate with the API
Current state: JWT with refresh rotation, httpOnly cookies
Evolution:
1. Session-based auth (Jan 2024) — simple, worked for monolith
2. PIVOT: Sessions don't scale across microservices (Jun 2024)
3. JWT with refresh rotation (Jun 2024) — stateless, horizontal scaling
Evidence: commits abc1234, def5678
Status: active
> How users authenticate with the API
Current state: JWT with refresh rotation, httpOnly cookies
Evolution:
1. Session-based auth (Jan 2024) — simple, worked for monolith
2. PIVOT: Sessions don't scale across microservices (Jun 2024)
3. JWT with refresh rotation (Jun 2024) — stateless, horizontal scaling
Evidence: commits abc1234, def5678
Status: active
Claude
Now I'll structure this in the graph using archaeology commands...
Claude
deciduous archaeology pivot 12 "Sessions don't scale across microservices" "JWT with refresh rotation" -c 90 -r "Monolith to microservices"
Created observation #14, revisit #15, decision #16
Linked: 12 → 14 → 15 → 16
Marked node 12 as superseded
Linked: 12 → 14 → 15 → 16
Marked node 12 as superseded
Claude
deciduous narratives pivots
1 pivot chain found:
#12 (session auth) → #14 (scaling issues) → #15 (revisit) → #16 (JWT)
#12 (session auth) → #14 (scaling issues) → #15 (revisit) → #16 (JWT)
Claude
Auth narrative is structured. The pivot from sessions to JWT is captured with the observation that drove it. Run deciduous archaeology timeline to see everything chronologically.
MCP Server — Direct AI Access to the Graph
Give Claude (Code or Desktop) direct structured access to your decision graph via the Model Context Protocol. 31 tools for creating, querying, analyzing, and reporting on decisions — no shell commands needed. Each conversation gets its own decision tree.
Claude Desktop — querying decisions via MCP
You
Why did we switch from in-memory caching to Redis? Show me the full decision chain.
Claude
search_nodes({ query: "cache" })
Found 4 nodes matching "cache"
Claude
trace_chain({ node_id: 1, direction: "outgoing" })
{ node_count: 6, edge_count: 5, nodes: [...] }
Claude
Decision Chain: Caching Strategy
Goal #1: "Caching strategy" [95%]
├─ Action #2: "In-memory LRU cache" [superseded]
│ └─ Observation #3: "Memory pressure at 10k RPM"
│ └─ Revisit #4: "Reconsider caching"
└─ Decision #5: "Switch to Redis with TTL" [90%]
└─ Outcome #6: "Redis deployed, p95 <12ms"
Rationale: In-memory LRU consuming 1.2GB at scale. Redis TTL gives horizontal scaling without memory pressure.
Goal #1: "Caching strategy" [95%]
├─ Action #2: "In-memory LRU cache" [superseded]
│ └─ Observation #3: "Memory pressure at 10k RPM"
│ └─ Revisit #4: "Reconsider caching"
└─ Decision #5: "Switch to Redis with TTL" [90%]
└─ Outcome #6: "Redis deployed, p95 <12ms"
Rationale: In-memory LRU consuming 1.2GB at scale. Redis TTL gives horizontal scaling without memory pressure.
Claude
The switch happened because the in-memory LRU was consuming 1.2GB at 10k requests/min.
Decision #5 chose Redis with TTL-based invalidation. The outcome (node #6) confirmed p95 latency under 12ms.
The full pivot chain is: Goal #1 → Action #2 (superseded) → Observation #3 → Revisit #4 → Decision #5 → Outcome #6.
Works with: Claude Code · Claude Desktop
Setup:
Full MCP documentation →
Setup:
deciduous mcp setup claude-code or deciduous mcp setup claude-desktopFull MCP documentation →
Install
Or download pre-built binaries for macOS, Linux, and Windows.
Explore Your Graph
Deploy to GitHub Pages with deciduous sync or run locally with deciduous serve.
Live Graph
Browse the actual graph from building deciduous — 1,300+ nodes across DAG, timeline, and archaeology views.
Q&A Interface
Ask questions in plain English via POST /api/ask. Answers grounded in your graph. Full-text search with FTS5.
Archaeology View
Navigate narratives as card stacks. Keyboard navigation (j/k/g/G/Space). See pivots and superseded approaches.
Built for Claude
Deciduous is built for Claude Code and Claude Desktop. One command sets up slash commands, skills, hooks, and MCP server integration.
Claude Code
deciduous initClaude Desktop
deciduous mcp setup claude-desktopSeven Node Types
A vocabulary for how software actually gets built: goal → options → decision → actions → outcomes. Observations attach anywhere. Revisits connect old approaches to new.
Goal
What to achieve
Option
Approaches considered
Decision
Choice made
Action
Work implemented
Outcome
Result observed
Observation
Insight captured
Revisit
Pivot point
Get Started in 60 Seconds
1
Install
Via Homebrew, Cargo, or pre-built binaries.
Terminal
$ brew tap notactuallytreyanastasio/tap
$ brew install deciduous
or
$ cargo install deciduous
2
Initialize in your project
Creates 10 slash commands, 3 skills, and project instructions.
Terminal
$ cd my-project && deciduous init
Created .deciduous/deciduous.db
Created .claude/commands/ (10 slash commands)
Created .claude/skills/ (pulse, narratives, archaeology)
Created CLAUDE.md (project instructions)
Ready! Run /decision-graph to graph existing history, or just start working.
3
Graph your history, then keep going
Use /decision-graph to build from existing commits.
Then just work normally — Claude logs decisions as you go.
Use /recover at the start of every new session.
New to deciduous? The tutorial walks through building a real decision graph from scratch, with live examples. Start the tutorial →
Deciduous was built with itself — 1,300+ decisions tracking its own development. Read the full story →