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 — 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 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)

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.

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

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

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]

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

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

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

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.

Install

Homebrew

$ brew tap notactuallytreyanastasio/tap

$ brew install deciduous

Cargo

$ cargo install deciduous

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,100+ 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.

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

Codex deciduous init --codex

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.

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

Install

Via Homebrew, Cargo, or pre-built binaries.

Terminal

$ brew tap notactuallytreyanastasio/tap

$ brew install deciduous

$ cargo install deciduous

Initialize in your project

Creates 9 slash commands, 3 skills, and project instructions.

Terminal

$ 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.

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.

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 →