Deciduous

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

---

See It In Action

Browse the Live Decision Graph — 1,100+ decisions from building deciduous itself

Interactive Tutorial — Learn the workflow in 15 minutes

Watch the Demo — Full session walkthrough

---

The Problem

You're building software with AI assistance. The LLM generates complex code fast. But then:

• Sessions end. Context compacts. The LLM loses memory of what was tried.
• Decisions evaporate. Six months later, no one remembers why you chose approach A over B.
• PRs become incomprehensible. A 50-file diff tells you what changed, not why.
• Onboarding is archaeology. New teammates reverse-engineer decisions from code.

The code tells you what. But decisions tell you why.

The Solution

Deciduous creates a persistent, queryable graph of every decision made during development. Log decisions in real-time—as they happen—and they survive session boundaries, context compaction, and human memory.

1,174 nodes • 1,024 edges • Real development history from building this tool

Both you and your AI assistant can:

• Query past reasoning before making new decisions
• See what was tried and what was rejected
• Trace any outcome back to the goal that spawned it
• Recover context after sessions end or memory compacts

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

---

Installation

Homebrew (Recommended)

brew tap notactuallytreyanastasio/tap
brew install deciduous

Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

| Platform | Binary | |----------|--------| | Linux (x86_64) | deciduous-linux-amd64 | | Linux (ARM64) | deciduous-linux-arm64 | | macOS (Intel) | deciduous-darwin-amd64 | | macOS (Apple Silicon) | deciduous-darwin-arm64 | | Windows | deciduous-windows-amd64.exe |

# Example: Linux/macOS
curl -LO https://github.com/notactuallytreyanastasio/deciduous/releases/latest/download/deciduous-darwin-arm64
chmod +x deciduous-darwin-arm64
sudo mv deciduous-darwin-arm64 /usr/local/bin/deciduous

Via Cargo

cargo install deciduous

From Source

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

---

Quick Start

# Initialize in your project
cd your-project
deciduous init

# Start logging decisions
deciduous add goal "Add user authentication" -c 90
deciduous add option "JWT tokens" -c 80
deciduous add option "Session cookies" -c 75
deciduous link 1 2 -r "Possible approach"
deciduous link 1 3 -r "Possible approach"
deciduous add decision "Use JWT for API, sessions for web" -c 85
deciduous link 2 4 -r "Chosen approach"
deciduous link 3 4 -r "Also incorporated"

# View the graph
deciduous serve    # Web viewer at localhost:3000

That's it. Your first decision graph is live.

The Canonical Flow

Every decision follows this path through the graph:

goal → options → decision → actions → outcomes

• Goals lead to options (possible approaches to explore)
• Options lead to a decision (choosing which option to pursue)
• Decisions lead to actions (implementing the chosen approach)
• Actions lead to outcomes (results of the implementation)
• Observations attach anywhere relevant
• Revisits connect old approaches to new ones when you pivot

Multi-Assistant Support

Deciduous integrates with multiple AI coding assistants:

# Claude Code (default)
deciduous init

# OpenCode
deciduous init --opencode

# Windsurf (Codeium)
deciduous init --windsurf

# Multiple assistants
deciduous init --both              # Claude Code + OpenCode
deciduous init --windsurf          # + Windsurf (auto-creates .windsurf/)
deciduous init --both --windsurf   # All three

| Assistant | Flag | Integration Files | |-----------|------|-------------------| | Claude Code | --claude (default) | .claude/, CLAUDE.md | | OpenCode | --opencode | .opencode/, AGENTS.md | | Windsurf | --windsurf | .windsurf/hooks/, .windsurf/rules/ |

Auto-detection: deciduous update auto-detects which assistants are installed (.claude/, .opencode/, .windsurf/) and updates them all. Windsurf is also auto-detected during init if .windsurf/ already exists.

---

The Workflow

BEFORE you do something → Log what you're ABOUT to do
AFTER it succeeds/fails → Log the outcome
CONNECT immediately → Link every node to its parent

Example Session

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

# Considering options
deciduous add option "Redis-based distributed" -c 80
deciduous add option "In-memory sliding window" -c 70
deciduous link 1 2 -r "Possible approach"
deciduous link 1 3 -r "Possible approach"

# Attach the design spec to the goal
deciduous doc attach 1 docs/rate-limiting-spec.pdf -d "Rate limiting design spec"

# Making a choice
deciduous add decision "Use Redis rate limiter" -c 85
deciduous link 2 4 --edge-type chosen -r "Scales across instances"
deciduous link 3 4 --edge-type rejected -r "Doesn't scale horizontally"

# Implementing the chosen approach
deciduous add action "Implementing Redis rate limiter" -c 85
deciduous link 4 5 -r "Implementation"

# Attach the architecture diagram to the action
deciduous doc attach 5 docs/redis-arch.png --ai-describe

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

# Export the graph
deciduous sync

Document Attachments

Attach files to any decision node — architecture diagrams, specs, screenshots, PDFs.

# Attach a diagram to a goal
deciduous doc attach 1 docs/architecture.png -d "System architecture diagram"

# AI-generate a description
deciduous doc attach 1 screenshot.png --ai-describe

# List what's attached
deciduous doc list 1

# Open a document
deciduous doc open 3

# Soft-delete (recoverable)
deciduous doc detach 3

# Clean up orphaned files
deciduous doc gc

Documents are stored in .deciduous/documents/ with content-hash naming for deduplication. The web viewer displays attached documents in the node detail panel. Soft-delete with doc detach; garbage-collect orphaned files with doc gc --dry-run to preview.

Session Recovery

When context compacts or you start a new session:

deciduous nodes           # What decisions exist?
deciduous edges           # How are they connected?
deciduous commands        # What happened recently?

Or open the web viewer and ask a question in plain English:

"What was I working on before the session ended?" "What approach did we take for rate limiting and why?"

The graph remembers what you don't. The Q&A interface lets you ask it.

---

Skills: Archaeology, Decision-Graph, and Narratives

Deciduous ships with skills that give your AI assistant structured ways to understand and work with a codebase's decision history.

/decision-graph — Visiting and documenting the past

The /decision-graph skill builds a full decision graph from your repository's commit history — perfect for bootstrapping a graph on an existing project that wasn't using deciduous from the start. It works in four layers:

1. Commit analysis — Groups commits into logical narratives
2. Code structure — Identifies architectural decisions from the codebase
3. Narrative construction — Builds evolution stories with pivots and connections
4. PR context — Uses gh CLI to mine PR descriptions and review threads for decision rationale, alternatives considered, and trade-offs discussed

/archaeology — Revisit, correct, execute

Archaeology is for revisiting past decisions in the graph—finding what went wrong, correcting the record, and executing on a new direction. When you discover a past decision was flawed, archaeology gives you the workflow to trace it back, mark it superseded, and connect the new approach.

# Find the old decision and mark it
deciduous nodes --status active --type decision
deciduous add observation "Mobile Safari 4KB cookie limit breaking JWT auth"
deciduous link 1 2 -r "Discovered in production"

# Revisit: pivot from old approach to new
deciduous add revisit "Reconsidering auth token strategy"
deciduous link 2 3 -r "Cookie limits forced rethink"
deciduous status 1 superseded

# Execute the new direction
deciduous add decision "Hybrid: JWT for API, sessions for web"
deciduous link 3 4 -r "New approach"
deciduous add action "Implementing hybrid auth" -c 85
deciduous link 4 5 -r "Implementation"

After archaeology, you can query: "What did we try before?" (--status superseded), "What led to this decision?" (edges --to <id>), "What are the pivot points?" (--type revisit).

/narratives — Understand how the system evolved

Narratives are the conceptual stories—how a subsystem evolved over time, what pivots happened, and how different parts of the system connect.

## Authentication
> How users prove identity.

**Current state:** JWT for API, sessions for web.

**Evolution:**
1. Started with JWT everywhere
2. **PIVOT:** Mobile hit 4KB cookie limits
3. Added sessions for web, kept JWT for API

**Connects to:** "Rate Limiting"