Deciduous

Decision graph tooling for Claude Code. Track every goal, decision, and outcome. Survive context loss. Generate PR writeups automatically.

cargo install deciduous
cd your-project
deciduous init

How It Works With Claude

Deciduous gives Claude a persistent memory that survives context loss. As Claude works, it logs decisions to a graph. When a session ends or context compacts, the graph remains - queryable by the next session.

The Workflow

1. Session starts → Claude runs /context to see past decisions
2. Claude works → Logs goals, decisions, actions as it goes
3. Session ends → Graph survives for next time
4. PR time → Generate writeup + visualization from the graph

What Claude Logs

Every step is captured in real-time:

Goal: "Compile rwc to WASM"
  └─> Decision: "Use wasm-bindgen + wasm-pack"
        └─> Action: "Add wasm-bindgen config"
              └─> Action: "Add lib.rs exports"
                    └─> Observation: "Homebrew lacks wasm32 target"
                          └─> Decision: "Install rustup"
                                └─> Outcome: "WASM build successful"

PR Generation

Generate a full PR writeup with decision graph visualization:

deciduous dot --auto --nodes 12-24      # Branch-specific PNG
git add docs/decision-graph-*.png && git push
deciduous writeup --auto -t "WASM Support" --nodes 12-24

The writeup includes goals, decisions, actions, outcomes, and an embedded graph:

Interactive Web Viewer

View the full decision graph with deciduous serve:

Quick Start

1. Install

cargo install deciduous

Requirements:

• Rust toolchain (for cargo install)
• Optional: graphviz (for --png flag to generate PNG images)

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

The deciduous binary is self-contained - no runtime dependencies for core functionality.

2. Initialize in your project

cd your-project
deciduous init

This creates:

• .deciduous/ - SQLite database
• .claude/commands/decision.md - /decision slash command
• .claude/commands/context.md - /context slash command
• docs/ - Static viewer for GitHub Pages
• .github/workflows/deploy-pages.yml - Auto-deploy to GitHub Pages
• .github/workflows/cleanup-decision-graphs.yml - Auto-cleanup PNGs after PR merge
• CLAUDE.md - Project instructions with workflow

3. Start tracking

# Claude logs decisions as it works
deciduous add goal "Build feature X" -c 90
deciduous add action "Implementing feature X" -c 85
deciduous link 1 2 -r "Goal leads to action"

# View the graph
deciduous serve

Commands

# Core workflow
deciduous init                           # Set up in current directory
deciduous add <type> "<title>" -c 85     # Add node (goal/decision/action/outcome/observation)
deciduous link <from> <to> -r "reason"   # Connect nodes
deciduous nodes                          # List all nodes
deciduous serve                          # Start web viewer

# PR workflow (recommended: use --auto for branch-specific filenames)
deciduous dot --auto --nodes 1-11        # Generate docs/decision-graph-{branch}.png
deciduous writeup --auto -t "Title" --nodes 1-11   # Generate PR writeup with PNG

# Export
deciduous sync                           # Export to JSON
deciduous graph                          # Full JSON to stdout

Node Types

Confidence Weights

Every node can have a confidence score (0-100):

GitHub Pages

Deciduous can deploy your decision graph to GitHub Pages for public viewing.

Setup

1. Run deciduous init (creates docs/ and workflow)
2. Export your graph: deciduous sync
3. Commit and push: git add docs/ .github/ && git push
4. Enable Pages in repo settings: Settings → Pages → Source: Deploy from branch → gh-pages

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

Live Example

See a real decision graph: deciduous_example

The viewer includes:

• Chains view - Decision chains with flow visualization
• Timeline view - Chronological node timeline
• Graph view - Force-directed interactive graph
• DAG view - Hierarchical directed acyclic graph

Why Deciduous?

Claude loses context. Sessions end, memory compacts, decisions evaporate. Six months later, no one remembers why you chose approach A over approach B.

Deciduous fixes this. Every decision is tracked in a queryable graph that persists forever. When Claude starts a new session, it can query the graph to understand past decisions - even from sessions it never saw.

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

Building from Source

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

License

MIT