Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Deciduous

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

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.

What Deciduous Does

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.

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

The Canonical Flow

Every decision follows this path through the graph:

goal → options → decision → actions → outcomes
  • goal What you’re trying to achieve
  • option Possible approaches to explore
  • decision Choosing which option to pursue
  • action Implementing the chosen approach
  • outcome Results of the implementation
  • observation Attach anywhere relevant
  • revisit Connect old approaches to new ones when you pivot

See It In Action

Here’s what a real session looks like — Claude logging decisions as it works:

Claude Code — working on auth
You
Add JWT authentication with refresh token rotation
Claude
$ deciduous add goal "Add JWT auth with refresh token rotation" -c 90
Created node 42 (type: goal) [confidence: 90%] [branch: feature-auth]
Claude
$ deciduous add option "jsonwebtoken crate + custom refresh logic" -c 80
Created node 43 (type: option) [confidence: 80%] [branch: feature-auth]
$ deciduous add option "axum-jwt-auth with built-in rotation" -c 75
Created node 44 (type: option) [confidence: 75%] [branch: feature-auth]
$ deciduous link 42 43 -r "possible approach"
$ deciduous link 42 44 -r "possible approach"
Claude
I'll go with jsonwebtoken — it's more mature and gives us full control over the rotation logic.
$ deciduous add decision "Use jsonwebtoken crate for full control" -c 85
Created node 45 (type: decision) [confidence: 85%] [branch: feature-auth]
$ deciduous link 43 45 -r "chosen"
$ deciduous link 44 45 -r "rejected — less control over rotation timing"
Claude
$ deciduous add action "Implement JWT middleware + refresh endpoint" -c 85
Created node 46 (type: action) [confidence: 85%] [branch: feature-auth]
$ deciduous link 45 46 -r "implementing chosen approach"
Writing src/auth/jwt.rs and src/auth/refresh.rs...
Claude
$ deciduous add outcome "JWT auth working — 14 tests passing" -c 95
Created node 47 (type: outcome) [confidence: 95%] [branch: feature-auth]
$ deciduous link 46 47 -r "implementation result"

Three days later, a new session starts. Context is gone. You type /recover:

Claude Code — new session, /recover
You
/recover
Claude
$ deciduous nodes
6 nodes: ID TYPE STATUS TITLE 42 goal pending Add JWT auth with refresh token rotation 43 option pending jsonwebtoken crate + custom refresh logic 44 option pending axum-jwt-auth with built-in rotation 45 decision pending Use jsonwebtoken crate for full control 46 action pending Implement JWT middleware + refresh endpoint 47 outcome pending JWT auth working — 14 tests passing
Claude
$ deciduous edges
42 ─[possible approach]→ 43 42 ─[possible approach]→ 44 43 ─[chosen]→ 45 44 ─[rejected]→ 45 45 ─[implementing chosen approach]→ 46 46 ─[implementation result]→ 47
Claude
$ git status
On branch feature-auth nothing to commit, working tree clean
Claude
Recovered context from the decision graph. Here's where we left off:

You asked for JWT auth with refresh token rotation (goal #42). We evaluated two options — jsonwebtoken crate vs axum-jwt-auth — and chose jsonwebtoken for full control over rotation logic. The middleware and refresh endpoint are implemented (action #46) with 14 tests passing (outcome #47).

The goal is still pending — what’s next?

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