Decision graph tooling for AI-assisted development. Track every goal, decision, and outcome. Survive context loss. Query your reasoning.

Browse the Live Decision Graph — 340+ decisions from building deciduous itself

Watch the Demo — Full session: initialization, decision logging, graph visualization, context recovery

LLMs generate complex code fast. Reviewing it, understanding it, and maintaining it? That's on you.

The problem: Sessions end. Memory compacts. Decisions evaporate. Six months later, no one—human or AI—remembers why you chose approach A over approach B.

The solution: Deciduous creates a persistent, queryable graph of every decision made during development. Both you and your AI assistant can query past reasoning, see what was tried, understand what was rejected and why.

This isn't documentation written after the fact. It's a real-time record of how software gets built, captured as decisions happen—by whoever is making them.

1. Decisions are the unit of institutional knowledge. Code tells you what, but decisions tell you why. Six months from now, you won't remember why you chose Redis over Postgres for that cache. The graph will.

2. Structured thinking produces better outcomes. The act of logging a decision—naming it, assigning confidence, connecting it to goals—forces you to think it through. It's rubber duck debugging for architecture.

3. Real-time logging beats retroactive documentation. Capture reasoning in the moment, not reconstructed from memory. By the time you write the post-hoc docs, you've already forgotten the options you rejected.

4. Graphs beat documents. Decisions connect—goals spawn decisions, decisions spawn actions, actions produce outcomes. A graph captures these relationships. You can trace any outcome back to the goal that spawned it.

5. Complex PRs tell a story. A 50-file PR is incomprehensible as a diff. But as a decision graph? You can see the goal, the key decisions, the rejected approaches, and how each file change connects to the larger purpose. Reviewers can understand why, not just what.

6. Context loss is inevitable. Sessions end. Memory compacts. The graph survives. When you come back to a project after months away, the graph is your memory.

7. Humans and AI assistants both benefit. You can query the graph to remember your own reasoning. The LLM can query it to understand decisions made before its context window. Either of you can log decisions. The graph doesn't care who's typing—it just preserves the reasoning.

8. The graph is a shared workspace. When the LLM makes a choice, you can see it. When you make a choice, the LLM can query it. Decisions flow between sessions, between humans and AI, between teammates.

You, the developer:

• Think through decisions more carefully by structuring them
• Remember why you made choices months later
• Review complex PRs by understanding the decision flow, not just the diff
• Onboard to unfamiliar codebases by reading the decision history

Your AI assistant:

• Recover context after session boundaries or compaction
• Understand decisions made before its context window
• Build on previous reasoning instead of starting fresh
• Leave a queryable trail for future sessions

Your team:

• Share decision context across PRs via patch files
• Review PRs with full visibility into the reasoning
• Build institutional knowledge that survives employee turnover

cargo install deciduous

cd your-project
deciduous init           # For Claude Code (default)
deciduous init --windsurf # For Windsurf/Cascade

This creates:

• .deciduous/deciduous.db — SQLite database for the graph
• .claude/commands/ or .windsurf/rules/ — Editor-specific tooling
• docs/ — Static web viewer (deployable to GitHub Pages)
• CLAUDE.md or AGENTS.md — Project instructions with the logging workflow

# Log a decision
deciduous add goal "Add user authentication" -c 90

# Connect decisions
deciduous add decision "Choose auth method" -c 75
deciduous link 1 2 -r "Deciding implementation approach"

# View the graph
deciduous serve          # Local web viewer
deciduous tui            # Terminal UI
deciduous sync           # Export for GitHub Pages

git add docs/
git push

Enable Pages: Settings > Pages > Source > Deploy from branch > gh-pages

Your graph will be live at https://<user>.github.io/<repo>/

SESSION START
    |
Run /context → Query past decisions
    |
DO WORK → Log BEFORE each action
    |
AFTER CHANGES → Log outcomes, link nodes
    |
BEFORE PUSH → deciduous sync
    |
SESSION END → Graph survives

# Starting a new feature
deciduous add goal "Add rate limiting" -c 90 -p "User asked: add rate limiting"

# Making a choice
deciduous add decision "Choose rate limiter approach" -c 75
deciduous link 1 2 -r "Deciding implementation"
deciduous add option "Redis-based" -c 80
deciduous add option "In-memory sliding window" -c 70

# Implementing
deciduous add action "Implementing Redis rate limiter" -c 85
deciduous link 2 5 --edge-type chosen -r "Scales across instances"

# Recording outcome
deciduous add outcome "Rate limiting working in prod" -c 95
deciduous link 5 6 -r "Implementation complete"

Two full-featured interfaces for browsing the graph—use whichever fits your workflow.

deciduous serve --port 3000

A browser-based interface with four visualization modes, branch filtering, and auto-refresh. Deploy to GitHub Pages for shareable, always-up-to-date graphs.

Features: branch dropdown filter, node search, stats bar with counts, click-to-expand details, recency sorting, responsive layout.

deciduous tui

A rich terminal interface for when you're already in the shell. Vim-style navigation, syntax-highlighted file previews, and integrated git diffs.

Features: auto-refresh on database changes, file browser panel, commit detail modal, syntax highlighting via the same engine as bat.

Share decisions across teammates working on the same codebase.

Each node has both a local ID and a globally unique change_id (UUID). Export patches to share:

# Export your branch's decisions
deciduous diff export --branch feature-x -o .deciduous/patches/my-feature.json

# Apply patches from teammates (idempotent—safe to re-apply)
deciduous diff apply .deciduous/patches/*.json

# Preview before applying
deciduous diff apply --dry-run .deciduous/patches/teammate.json

1. Create nodes while working
2. Export: deciduous diff export --branch my-feature -o .deciduous/patches/my-feature.json
3. Commit the patch file (not the database)
4. Open PR with patch file included
5. Teammates apply after pulling

# Initialize
deciduous init               # Claude Code
deciduous init --windsurf    # Windsurf/Cascade
deciduous update             # Update tooling to latest version

# Add nodes
deciduous add goal "Title" -c 90
deciduous add decision "Title" -c 75
deciduous add option "Title" -c 80
deciduous add action "Title" -c 85
deciduous add outcome "Title" -c 95
deciduous add observation "Title" -c 70

# Node metadata
-c, --confidence <0-100>     # Confidence level
-p, --prompt "..."           # User prompt that triggered this
-f, --files "a.rs,b.rs"      # Associated files
-b, --branch <name>          # Git branch (auto-detected)
--commit <hash|HEAD>         # Link to git commit

# Connect nodes
deciduous link <from> <to> -r "reason"
deciduous link 1 2 --edge-type chosen -r "Selected this approach"

# Query
deciduous nodes              # List all nodes
deciduous nodes -b main      # Filter by branch
deciduous edges              # List connections
deciduous graph              # Full graph as JSON
deciduous commands           # Recent command history

# Visualize
deciduous serve              # Web viewer
deciduous tui                # Terminal UI
deciduous dot --png          # Generate PNG (requires graphviz)
deciduous dot --auto         # Branch-specific filename

# Export
deciduous sync               # Export to docs/graph-data.json
deciduous writeup -t "Title" # Generate PR writeup
deciduous backup             # Create database backup

# Multi-user sync
deciduous diff export -o patch.json
deciduous diff apply patches/*.json
deciduous diff status
deciduous migrate            # Add change_id columns

Nodes are automatically tagged with the current git branch.

Configuration (.deciduous/config.toml):

[branch]
main_branches = ["main", "master"]
auto_detect = true

deciduous nodes --branch main        # Filter by branch
deciduous add goal "Work" -b other   # Override auto-detection
deciduous add goal "Note" --no-branch # No branch tag

deciduous init creates GitHub workflows that:

1. Deploy your graph viewer to GitHub Pages on push to main
2. Clean up branch-specific PNGs after PR merge

Enable Pages: Settings > Pages > Source > Deploy from branch > gh-pages

git clone https://github.com/notactuallytreyanastasio/deciduous.git
cd deciduous
cargo build --release
./target/release/deciduous --help

Optional: graphviz for PNG export

brew install graphviz    # macOS
apt install graphviz     # Ubuntu/Debian

It almost has the word "decision" in it, and they're trees.