DECIDUOUS

Every decision you've ever made, in one graph — and every agent working on it can see the others. One server holds the reasoning behind every project on your machine, one workspace per repository. Agents on different branches write to it at the same time, watch each other's writes land, and record what they took from whom. What one session decided survives the next session's memory.

New in 1.0

Ten Agents, One Graph

At 04:47 UTC on 22 September 2026, agent-7 implemented step reset for lock delay. The idea was agent-8's, and agent-8 had not written the code yet. It had logged a decision; agent-7 read it in the shared graph, wrote its own version, and recorded where it came from. Ten Claude Code sessions, ten git worktrees of one repository, one workspace, and a rules file that said reading each other's work was the point. Twenty-six minutes later: ten playable Tetris games, 386 graph nodes, 170 borrowed ideas with provenance. The write-up has the numbers, the borrow matrix, and what broke.

deciduous remote watch — the arena, live

$ deciduous remote watch

Watching: tetris-arena

04:45:14 agent-9 observation "Took 4 hidden rows from agent-3: SRS kicks can lift a piece 2 rows at the ceiling"

04:46:13 agent-10 observation "Took 4 hidden rows (agent-9, from agent-3) and lock-out (agent-2, from agent-1); dropped my y<0 exemption"

04:47:15 agent-7 observation "Took the step-reset for lock delay from agent-8's decision, and spawn-then-step-down and lock-out from agent-8 and agent-3"

04:47:33 agent-4 observation "Took 4 hidden rows + solid ceiling (agent-3/9/6) and lock-out (agent-1); my merge() was silently dropping cells above row 0"

Those four lines are real nodes from the arena's graph, in the order they landed. One finding (agent-3: some SRS kicks lift a piece two rows, so two hidden rows refuse a legal rotation at the ceiling) reached eight of the nine other branches in eighteen minutes (agent-1 started with a forty-row board and never needed it), and two of the agents that took it used it to find the same silent bug in their own merge().

Agents that work alongside each other. Every write claims an advisory lock on (workspace, branch), so ten agents on ten branches never wait for each other and two on one branch are told who is there. check_activity reports who holds what and the last node on each of the twenty most recently written branches. Postgres triggers push every write over a WebSocket the moment it lands; deciduous remote watch sits on it. A took_from edge records a borrow across branches as a query, not a sentence.

Memory that survives the session. The graph is what /recover reads when a new session starts or context compacts: goals, the options that were rejected, the outcomes, the attached documents. Far richer than what compaction keeps, and it is the same graph the other agents are writing to.

Discovery over what was already decided. query_nodes with workspace: "*" finds the auth decision you made in a repository you have not opened in a year. ask_graph answers in prose grounded in the nodes. /decision-graph builds the graph backwards from a commit history that predates the tool.

check_activity — before a burst of writes

> check_activity({ workspace: "tetris-arena" })

{ "active_sessions": 3,

"sessions": [ { "branch": "agent-3", "client": "claude-code", "is_you": false, "expires_in_seconds": 8 }, ... ],

"branches": [

{ "branch": "agent-3", "locked_by": { "client": "claude-code", "session": "GNei6CpI", "is_you": false }, "last_node": { "node_type": "outcome", "title": "Round 4: clamp DAS through the clear flash", ... } },

{ "branch": "agent-8", "locked_by": null, "last_node": { "node_type": "outcome", "title": "arena converged, stopping here", ... } },

... ] }

What the arena found wanting, 1.0 fixes. Zero of its 471 edges crossed a branch, because nothing said a borrow was an edge: took_from is that edge, and log_observation writes it in the same call. Agents polled query_nodes to see what was new: check_activity now carries the last node per branch. A watcher summarised from a tally and invented a convention that did not exist: remote watch quotes the title of every write instead of counting them. And the event socket that fed the watcher was closed by the server every sixty seconds; it is not any more.

Read the arena write-up Work alongside other agents

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.

Shared graph

One Graph, Every Project

Point every repository at one server and the reasoning behind all of them lives in a single Postgres — one workspace per repo, queryable alone or all at once. Your agent reaches it from any directory over MCP. So does the CLI. The local database becomes a cache; the server is the truth.

one project, or all of them

$ deciduous remote status

Remote: https://example.com/deciduous-mcp

Workspace: blog

local remote

nodes 719 719

edges 845 845

OK: counts match.

Read tools take workspace: "*" for the cross-project view — find the auth decision you made in a repo you haven't opened in a year. Writes refuse it, because a node has to land somewhere specific. A repository can pin itself with a header, and then nothing can write its nodes anywhere else.

setup, once per machine

$ deciduous remote login

Token: stored in ~/.config/deciduous/credentials

mode 0600, outside every repository

$ deciduous remote adopt ~/code --url https://example.com/deciduous-mcp

90 configured, 1 left alone

The token is never written to a config file. It lives in a credentials file outside every repository, so committing your config leaks a hostname and nothing else. You run the server yourself — it is an Elixir app and a Postgres database, and it ships in the repo.

Set up the shared graph

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]

New in v0.14

MCP Server — Direct AI Access to the Graph

Give Claude (Code or Desktop) direct structured access to your decision graph via the Model Context Protocol. 31 tools for creating, querying, analyzing, and reporting on decisions — no shell commands needed. Each conversation gets its own decision tree. (Cowork support coming soon — tracking issue.)

Claude Desktop — querying decisions via MCP

You

Why did we switch from in-memory caching to Redis? Show me the full decision chain.

Claude

search_nodes({ query: "cache" })

Found 4 nodes matching "cache"

Claude

trace_chain({ node_id: 1, direction: "outgoing" })

{ node_count: 6, edge_count: 5, nodes: [...] }

Claude

Decision Chain: Caching Strategy

Goal #1: "Caching strategy" [95%]
  ├─ Action #2: "In-memory LRU cache" [superseded]
  │   └─ Observation #3: "Memory pressure at 10k RPM"
  │      └─ Revisit #4: "Reconsider caching"
  └─ Decision #5: "Switch to Redis with TTL" [90%]
      └─ Outcome #6: "Redis deployed, p95 <12ms"

Rationale: In-memory LRU consuming 1.2GB at scale. Redis TTL gives horizontal scaling without memory pressure.

Claude

The switch happened because the in-memory LRU was consuming 1.2GB at 10k requests/min. Decision #5 chose Redis with TTL-based invalidation. The outcome (node #6) confirmed p95 latency under 12ms. The full pivot chain is: Goal #1 → Action #2 (superseded) → Observation #3 → Revisit #4 → Decision #5 → Outcome #6.

Works with: Claude Code · Claude Desktop · Any MCP client (Cowork coming soon)
Setup: Add {"mcpServers": {"deciduous": {"command": "deciduous", "args": ["mcp"]}}} to your config
Full MCP documentation →

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?

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.

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

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.

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.

Working across several projects? Set up the shared graph so every repository reaches one server instead of a separate local database each.

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

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.
`deciduous remote watch`	cli	Connect to the shared server's event stream and print one line per write, quoting the node's title and branch. Reconnects on close. `--types`, `--branch`, `--edges`, `--json`; `--url` prints the socket URL for another client.
`check_activity`	mcp	Who is writing to this workspace right now, on which branch, and the last node on each of the twenty most recently written branches (`branches: N` for more). Call it before a burst of writes.
`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 →