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.
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 — 3 bug reports in March" --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
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.
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
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)
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
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.
New in v0.13
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.
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
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.
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
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
=== 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]
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
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
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.
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
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.
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
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
Claude
deciduous narratives pivots
1 pivot chain found:
#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.
Explore Your Graph
Deploy to GitHub Pages with deciduous sync or run locally with deciduous serve.
Works With Your Editor
One command creates slash commands, skills, and project instructions that teach your AI assistant the workflow.
Claude Code deciduous init
Windsurf deciduous init --windsurf
OpenCode deciduous init --opencode
Seven Node Types
A vocabulary for how software actually gets built: goal → options → decision → actions → outcomes. Observations attach anywhere. Revisits connect old approaches to new.
Option
Approaches considered
Observation
Insight captured
Get Started in 60 Seconds
$ brew tap notactuallytreyanastasio/tap
$ brew install deciduous
or
$ cargo install deciduous
$ cd my-project && deciduous init
Created .deciduous/deciduous.db
Created .claude/commands/ (9 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.
All Commands & Skills
Everything deciduous init installs. Commands are slash commands (/recover). Skills are contextual guides Claude follows.
| Name | Type | What It Does |
|---|---|---|
/decision-graph |
command | Build a decision graph from an existing repo's commit history. Analyzes commits, traces narratives, creates backdated nodes grounded in real evidence. |
/recover |
command | Recover context at session start. Queries nodes, edges, documents, commands, and git state. Audits for disconnected nodes. Reports what's active and what's next. |
/work |
command | Start a work transaction. Creates goal node with verbatim prompt before any code is written. Tracks actions and outcomes through to commit. |
/decision |
command | Full decision graph management. Add nodes, link edges, manage documents, sync with teammates, export DOT/PNG, generate PR writeups. |
/document |
command | Generate comprehensive documentation for a file or directory. Shakes the tree — traces callers, finds tests, maps dependencies. |
/sync |
command | Multi-user sync. Pull teammate events, rebuild local DB, push your changes. Event-based, append-only, git-mergeable. |
/serve-ui |
command | Start the web viewer at localhost:3000. Auto-refreshes. DAG, timeline, chains, archaeology, and Q&A views. |
/sync-graph |
command | Export graph to docs/graph-data.json for GitHub Pages deployment. |
/build-test |
command | Build the project and run the test suite. |
pulse |
skill | Map the current state as decisions. Pick a scope, read the code, ask "what decisions define this?", build goal → options → decisions. deciduous pulse shows the summary. |
narratives |
skill | Maintain .deciduous/narratives.md — evolution stories for each subsystem. Identify pivots, track current state vs history, find evidence in commits. |
archaeology |
skill | Transform narratives into graph structure. Create backdated goals, use archaeology pivot to atomically create pivot chains, mark superseded paths, review timeline. |
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,100+ decisions tracking its own development. Read the full story →