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 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:

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

Installation

Homebrew (Recommended)

brew tap notactuallytreyanastasio/tap
brew install deciduous

Pre-built Binaries

Download the latest release from GitHub Releases:

# Example: macOS Apple Silicon
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

Verify Installation

Quick Start

Get deciduous running in your project in under two minutes. By the end of this page, you’ll have a live decision graph with your first connected chain of nodes.

Initialize Your Project

Run deciduous init inside any git repository. This creates the .deciduous/ directory with a SQLite database and installs integration files for your AI assistant.

That’s it for setup. The database is ready and your AI assistant now has instructions to log decisions automatically.

The Canonical Flow

Every piece of work follows this path through the graph:

• goal What you’re trying to achieve
• option Possible approaches to consider
• decision Choosing which option to pursue
• action Implementing the chosen approach
• outcome Results of the implementation

This isn’t arbitrary structure. It forces you to record why you chose an approach, not just what you built. Six months later, when someone asks “why didn’t we use WebSockets instead?”, the graph has the answer.

Your First Decision Graph

Here’s a realistic scenario. You ask Claude to add API rate limiting to your project. Claude logs each step as it works:

You now have six connected nodes forming a complete decision chain. Every node is linked to what came before it, creating a traceable path from the original goal to the final outcome.

Viewing Your Graph

Start the web viewer to see your decision graph rendered as an interactive visualization:

Open http://localhost:3000 in your browser. You’ll see your nodes laid out as a directed graph, color-coded by type, with edges showing the reasoning chain.

You can also inspect the graph from the command line:

What You’ve Built

In under two minutes, you have:

1. A searchable record of what was decided and why
2. Rejected alternatives preserved for future reference (node 3 – governor crate)
3. Traceable reasoning from goal through to outcome
4. A live visualization in your browser

The next time someone opens this codebase and asks “why Redis instead of an in-memory solution?”, the graph has the answer: node 4, with the rationale right there in the edge labels.

Next, read the Workflow chapter to learn how to use deciduous throughout a full development session – including how to handle pivots when an approach fails.

The Workflow

Deciduous works because it captures decisions as they happen, not after the fact. This chapter covers the core workflow rules, what to log (and what not to), session recovery, the revisit pattern for pivots, and linking commits to the graph.

The Core Rule

Three things, every time:

1. BEFORE you do something – log what you’re about to do
2. AFTER it succeeds or fails – log the outcome
3. CONNECT immediately – link every node to its parent

If you skip the “before” step, you lose the reasoning. If you skip the “after” step, you lose the result. If you skip the connection, the graph is just a pile of disconnected notes.

What to Log

The decision graph records the project’s decisions, not the AI’s internal process. A good rule of thumb: if it would appear on a project timeline or in a PR description, log it.

Do log:

Do not log:

• Reading or exploring the codebase (“Analyzing project structure”)
• Your planning process (“Evaluating options internally”)
• Tool usage (“Running tests to check status”)
• Context gathering (“Reviewing the auth module”)
• Meta-commentary (“Starting work on this task”)

These are the AI’s internal process, not project decisions. They add noise without value.

A Full Development Session

Here’s a complete session showing the workflow in practice – including a pivot when the first approach fails.

So far, a straightforward flow: goal, options, decision, action. But then the first approach hits a wall:

The Revisit Pattern

When an approach fails, you don’t just start over. You create a revisit node that explicitly connects the failed approach to the new one. This preserves the why – future readers will see what was tried and why it was abandoned.

The graph now tells the full story: we tried synchronous image crate processing, it was too slow (4.2s), we discovered the root cause (no SIMD), and pivoted to async libvips (380ms). Anyone reading this later gets the complete reasoning, not just the final code.

Linking Commits

After committing code, link the commit to the decision graph with --commit HEAD. This connects your git history to the reasoning that produced it.

The --commit HEAD flag captures the commit hash and links it to the node. The web viewer will display commit messages, authors, and dates alongside the decision that produced them.

Session Recovery

Sessions end. Context compacts. But the graph survives. At the start of a new session, recover context by inspecting the existing graph:

The deciduous edges command is also valuable for understanding the connections between nodes:

Every edge tells you why two nodes are connected. The graph is not just a list of things that happened – it’s a map of the reasoning that produced them.

Connection Rules

The graph’s value is in its connections, not just its nodes. Every node type has a clear parent:

Root goal nodes are the only valid orphans. Everything else must be connected.

Decision Graph Concepts

A decision graph is a directed acyclic graph (DAG) where nodes represent things that happened and edges represent relationships between them. This chapter covers the building blocks.

Node Types

Every node has a type that describes its role in the decision-making process.

When to use each type

• Goal: When the user asks for something new or a high-level objective is identified.
• Option: When exploring possible approaches before choosing one. Options always come from a goal.
• Decision: When an option is actually chosen. Decisions come after options, not before.
• Action: When you are about to write or change code. Log it before the work.
• Outcome: When work is complete. Link it back to the action that produced it.
• Observation: When you notice something interesting — a constraint, a codebase pattern, a risk. Use the -d flag for a detailed description.
• Revisit: When a previous approach is being abandoned and replaced. Links old decisions to new ones.

The Canonical Flow

Every decision follows this path through the graph:

• goal leads to option nodes (possible approaches)
• option nodes lead to a decision (choosing which to pursue)
• decision leads to action nodes (implementing the choice)
• action nodes lead to outcome nodes (results)
• observation attaches anywhere relevant
• revisit connects old approaches to new ones during pivots

Goals do not lead directly to decisions. There must be options first. Options do not come after decisions. Decision nodes should only be created when an option is actually chosen.

Edge Types

Edges describe the relationship between two nodes.

Note: A supersedes edge type is auto-created by the revisit/archaeology system (e.g., deciduous archaeology pivot). It is not a valid parameter for deciduous link.

Node Status

Every node has a status that tracks its lifecycle.

Confidence Levels

Every node carries a confidence value from 0 to 100, reflecting how certain you are about it.

Confidence helps future sessions prioritize which decisions to revisit. A low-confidence decision is a natural candidate for re-evaluation.

The Revisit Pattern

When a design approach is abandoned and replaced, a revisit node captures the pivot:

1. An observation identifies why the old approach failed
2. A revisit node links to that observation
3. The revisit leads to the new decision
4. The old decision is marked superseded

This captures why you changed direction, not just what changed.

Sessions and Chains

Sessions group nodes by time proximity. Nodes created within 4 hours of each other belong to the same session. A gap longer than 4 hours starts a new session.

Chains are connected components of the graph. Starting from root nodes (goals or nodes with no incoming edges), BFS traverses all connected nodes. Chains group related decisions together — “show me everything related to authentication.”

Both concepts are used by the web viewer to organize and display your decision history.

Working with Nodes

This chapter covers the core workflow: adding nodes, linking them, updating status, and maintaining the graph.

Adding Nodes

Create nodes with deciduous add <type> "title". The type must be one of: goal, option, decision, action, outcome, observation, or revisit.

All Flags

Capturing Verbatim Prompts

For goal nodes, capture the user’s exact request — not a summary. This enables full context recovery in future sessions.

You can also update the prompt on an existing node:

Linking Nodes

Create edges between nodes with deciduous link <from> <to>. Always link immediately after creating a node.

Connection Rules

Root goal nodes are the only valid orphans. Every other node type must be linked immediately:

Updating Status

Change a node’s status with deciduous status <id> <status>.

Valid status values: pending, active, completed, rejected, superseded, abandoned.

Showing Node Details

Use deciduous show <id> to view a node’s full details, including connections.

Querying Nodes and Edges

Deleting and Unlinking

Remove edges with deciduous unlink and nodes with deciduous delete.

Use --dry-run to preview what would be removed before committing to a deletion.

Linking Commits

After every git commit, link it to the decision graph with --commit HEAD:

The web viewer displays commit messages, authors, and dates for linked nodes.

The Core Pattern

The golden rule for working with nodes:

1. Before you write code – log what you are about to do (action)
2. After it works – log the result (outcome)
3. Always – link every node to its parent immediately

Visualization & Export

Deciduous provides multiple ways to view and share your decision graph: a live web viewer, DOT/PNG export, PR writeups, and GitHub Pages deployment.

Web Viewer

Start the interactive web viewer with deciduous serve.

The viewer provides five browsing modes:

Q&A Chat

Every view includes a built-in Q&A chat panel. Ask questions about your decision graph in natural language — the chat searches across all nodes, traces chains, and returns grounded answers with node references. Conversations are stored in the database and persist across sessions. A copy-to-markdown button makes it easy to pull answers into PRs or docs.

Other Features

Branch filtering, full-text search with type filters, resizable panels, deep linking, click-to-expand node details, keyboard navigation (j/k/g/G/Space), and auto-refresh every 30 seconds.

DOT Export

Generate DOT format graphs with deciduous dot. Add --png to render a PNG image (requires graphviz installed).

DOT Options

The --auto flag generates filenames like docs/decision-graph-feature-auth.png based on the current branch, which prevents merge conflicts when multiple PRs each have their own graph.

PR Writeups

Generate markdown writeups for pull requests with deciduous writeup.

Writeup Options

Recommended PR Workflow

Sync for GitHub Pages

Export your graph to static JSON files for GitHub Pages hosting with deciduous sync.

This creates two files in docs/:

Deploying to GitHub Pages

1. Run deciduous sync to export
2. Commit and push the docs/ directory
3. In GitHub Settings → Pages → Deploy from branch → select /docs folder

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

Full JSON Export

For programmatic access, export the entire graph as JSON:

Multi-User Sync

The deciduous database (.deciduous/deciduous.db) is local and gitignored. When teams need to share decisions, the events system provides append-only sync via git.

How It Works

Each user writes to their own event log file at .deciduous/sync/events/<username>.jsonl. These files are git-tracked and merge cleanly because each user writes to a separate file. When a teammate pulls, they rebuild their local database from all event logs.

The model:

1. Every add, link, and status command emits an event to your personal log
2. Events are identified by change_id (UUID), not local integer IDs
3. Rebuilding replays all events from all users, deduplicating by change_id
4. Checkpoints snapshot the current state so old events can be cleared

Initializing Sync

Set up the sync directory with deciduous events init.

After initializing, events are automatically emitted whenever you create nodes, link edges, or update status.

Checking Status

View the current state of sync with deciduous events status.

Rebuilding from Events

After pulling changes from teammates, rebuild your local database.

You can preview what would change without modifying the database:

Checkpointing

As event logs grow, create a checkpoint to snapshot the current state. This speeds up future rebuilds.

Use --clear-events to remove old event log files after checkpointing. The checkpoint contains everything needed for a full rebuild.

Emitting Events Manually

If you created nodes before sync was initialized, emit them manually:

PR Workflow for Sharing Decisions

The recommended team workflow:

Since each user writes to their own .jsonl file, git merges happen automatically with no conflicts.

The Dual-ID Model

Every node has two identifiers:

Event logs and patches reference nodes by change_id, so they work correctly even when local id values differ between machines.

If your database predates the sync system, run deciduous migrate to add change_id columns.

Themes & Organization

Themes let you organize decision nodes into cross-cutting categories. A node about “JWT middleware” might belong to both an “auth” theme and a “security” theme. Themes work independently of the graph structure — they are tags, not edges.

Creating Themes

Define a theme with deciduous themes create. Each theme has a name, a color, and an optional description.

Theme names are lowercase and dash-separated. Colors help distinguish themes visually in the web viewer.

Listing Themes

View all defined themes with deciduous themes list.

Deleting Themes

Remove a theme and all its node associations with deciduous themes delete.

Tagging Nodes

Apply themes to nodes with deciduous tag add. A node can have multiple themes.

Removing Tags

Listing Tags on a Node

Auto-Suggestions

Deciduous can analyze node titles and suggest theme assignments with deciduous tag suggest. This scans nodes for keyword matches against existing theme names and descriptions.

Apply all suggestions at once with --apply:

Suggestions are tagged with source "suggested" rather than "manual", so you can distinguish them later.

Confirming Suggestions

Review and confirm auto-suggested tags with deciduous tag confirm. This upgrades a suggestion from "suggested" to "manual" status.

Filtering by Theme

Use the --theme flag on deciduous nodes to filter nodes by theme.

Themes combine with other filters like --status, --type, and --branch for precise queries across the graph.

Setup

The Model Context Protocol (MCP) is an open standard that lets AI assistants call tools hosted by external servers. Deciduous ships with a built-in MCP server that exposes 31 tools for reading, writing, and analyzing your decision graph. When connected, Claude can search decisions, trace chains, and log new nodes directly – no copy-pasting CLI output.

Claude Code

One command, project-level config:

That’s it. Restart Claude Code and the tools appear as mcp__deciduous__*. The command writes to .claude/settings.local.json in your project directory, which is gitignored by default – each developer gets their own config.

Claude Desktop

Claude Desktop needs absolute paths because it doesn’t inherit your shell PATH:

The command auto-detects your binary path and the .deciduous/deciduous.db location in the current directory. It writes to the platform-specific Claude Desktop config file:

If other MCP servers are already configured, deciduous merges its entry without disturbing them. You must restart Claude Desktop after running this command.

Manual Setup

If you prefer to inspect the config before writing it, use --print:

Copy the relevant parts into your config file manually.

User-Level vs Project-Level Config

Claude Code uses project-level config. Each project has its own .deciduous/deciduous.db, and the MCP server automatically finds it from the working directory.

Claude Desktop uses user-level config. You point DECIDUOUS_DB_PATH at a specific database file, and every conversation in Claude Desktop reads and writes to that same database. This is the foundation of the Master Memory pattern.

Generated Config

For Claude Code, the generated JSON is minimal – no absolute paths needed:

{
  "mcpServers": {
    "deciduous": {
      "command": "deciduous",
      "args": ["mcp", "serve"]
    }
  }
}

For Claude Desktop, absolute paths and the database env var are included:

{
  "mcpServers": {
    "deciduous": {
      "command": "/Users/you/.cargo/bin/deciduous",
      "args": ["mcp", "serve"],
      "env": {
        "DECIDUOUS_DB_PATH": "/Users/you/project/.deciduous/deciduous.db"
      }
    }
  }
}

Troubleshooting

Binary not found

Claude Desktop does not inherit your shell PATH. If you see errors about the command not being found, verify the absolute path:

which deciduous
# /Users/you/.cargo/bin/deciduous

Use that full path in the config’s command field.

Database not found

If deciduous mcp setup claude-desktop warns that .deciduous/deciduous.db was not found, run deciduous init in your project directory first. The MCP server will create the database on first use if it doesn’t exist, but init also sets up Claude integration files.

DECIDUOUS_DB_PATH

The DECIDUOUS_DB_PATH environment variable tells the MCP server which SQLite database to use. This is only needed for Claude Desktop (where there is no working directory context). Claude Code runs in your project directory and finds the database automatically.

You can override it to point at any database:

"env": {
  "DECIDUOUS_DB_PATH": "/Users/you/other-project/.deciduous/deciduous.db"
}

Server not connecting

1. Verify the binary path exists and is executable
2. Test the server manually: deciduous mcp serve (it reads JSON-RPC from stdin)
3. Check that deciduous init has been run in the target project
4. Restart Claude Desktop / Claude Code after config changes

Conversational Memory

Every conversation with Claude gets its own decision tree. When a session starts, a root goal node is created. Every node added during that conversation is automatically associated with the session – no manual bookkeeping. When the conversation ends, an optional summary captures what was accomplished.

The result: each conversation produces a self-contained, queryable record of what was discussed, decided, and built.

Session Lifecycle

A session has three phases:

1. Start – start_session creates a root goal node and returns a session ID
2. Work – all add_node calls auto-associate with the active session
3. End – end_session marks the session complete with an optional summary

Resuming Sessions

Pick up where you left off. Use list_sessions to find previous conversations, then resume_session to reconnect. New nodes continue building on the same decision tree.

Persistence Across Restarts

The active session ID is written to .deciduous/active_session on disk. When the MCP server starts (or restarts – Claude Desktop and Claude Code may kill and re-spawn the server process), it reads this file and automatically resumes the active session. No manual intervention needed.

If the session was already ended, the stale file is cleaned up automatically.

Master Memory

Claude Desktop users get a persistent decision graph across every conversation. The MCP config points DECIDUOUS_DB_PATH at a single .deciduous/deciduous.db file. Every conversation – whether it runs for five minutes or five hours – writes to the same database.

This means you can ask Claude in a new conversation about decisions made in previous ones. The graph is the memory layer that outlasts any single chat.

Conversation 1 (Jan)  --> .deciduous/deciduous.db  <-- Session #1 (14 nodes)
Conversation 2 (Feb)  --> .deciduous/deciduous.db  <-- Session #2 (8 nodes)
Conversation 3 (Mar)  --> .deciduous/deciduous.db  <-- Session #3 (11 nodes)

In a brand new conversation, you can query the entire history:

The database is the single source of truth. Sessions organize it by conversation. Search and trace work across all of them.

Multi-Session Workflow Example

Here is a realistic workflow spanning two sessions days apart, showing how memory persists:

The decision tree now contains the full story: what was tried, what worked, what needed a second pass, and why. Any future session can query this history without having been part of either conversation.

API Reference

All 31 MCP tools exposed by the deciduous server, organized by category. Tools marked CLI have a direct CLI equivalent. Tools marked MCP-only are exclusive to the MCP server.

Graph CRUD

Tools for creating, connecting, and modifying nodes and edges.

add_node

Add a new node to the decision graph. CLI: deciduous add

link_nodes

Create an edge between two nodes. CLI: deciduous link

unlink_nodes

Remove an edge between two nodes. CLI: deciduous unlink

delete_node

Delete a node and all its connected edges. CLI: deciduous delete

update_status

Change the status of a node. CLI: deciduous status

update_prompt

Add or update the verbatim user prompt stored on a node. CLI: deciduous prompt

Querying

Tools for listing, searching, and inspecting graph data.

list_nodes

List all nodes with optional filters. CLI: deciduous nodes

list_edges

List all edges in the decision graph. CLI: deciduous edges

No parameters.

show_node

Show detailed information about a single node including connections, themes, and documents. CLI: deciduous show

get_graph

Export the full decision graph as JSON (all nodes and edges). CLI: deciduous graph

No parameters.

search_nodes

Full-text search across titles, descriptions, and prompts. MCP-only

Analysis

Tools for traversing, tracing, and understanding the graph structure.

trace_chain

BFS traversal from a starting node. Returns the connected subgraph with depth. MCP-only

get_node_context

Get a node’s full neighborhood: the node itself, parents, children, siblings, themes, and documents. MCP-only

get_timeline

Chronological view of nodes, newest first. CLI: deciduous archaeology timeline

get_pulse

Graph health check: summary statistics, active goals, recent activity, orphans, and connection gaps. CLI: deciduous pulse

find_orphans

Find nodes that violate connection rules (outcomes without parent actions, actions without parent decisions, etc.). Root goals are excluded since they are valid orphans. MCP-only

No parameters.

get_branch_summary

Summary of all decisions and activity on a specific git branch. MCP-only

Sessions

Tools for managing conversation-scoped decision trees. All session tools are MCP-only.

start_session

Begin a new conversation session. Creates a root goal node; all subsequent add_node calls auto-associate.

end_session

Close the active session with an optional summary.

get_session

View a session’s details and all its nodes.

resume_session

Reconnect to a previous session by ID. Use after breaks or server restarts.

list_sessions

List all conversation sessions.

Documents & Themes

Tools for attaching files and organizing nodes with tags.

attach_document

Attach a file to a decision graph node. CLI: deciduous doc attach

list_documents

List documents attached to a node, or all documents. CLI: deciduous doc list

create_theme

Create a new theme for tagging nodes. CLI: deciduous themes create

list_themes

List all defined themes. CLI: deciduous themes list

No parameters.

tag_node

Add a theme tag to a node. CLI: deciduous tag add

untag_node

Remove a theme tag from a node. CLI: deciduous tag remove

Export

Tools for generating visualizations, writeups, and sync status.

export_dot

Export the decision graph as DOT format for Graphviz visualization. CLI: deciduous dot

generate_writeup

Generate a PR writeup from the decision graph. Returns markdown. CLI: deciduous writeup

events_status

Show the status of event-based multi-user sync. CLI: deciduous events status

No parameters.

Tool Count by Category

Core Commands

Setup, server, and maintenance commands that manage your deciduous installation.

deciduous init

Initialize deciduous in the current directory. Creates the .deciduous/ database directory and sets up AI assistant integration files.

Default (no flags): sets up Claude Code only.

deciduous update

Update AI assistant integration files to the latest version. Auto-detects installed integration files (.claude/) and updates them.

Does not touch: settings files, .deciduous/config.toml, or docs/.

deciduous check-update

Compare .deciduous/.version with the current binary version. Exits with code 0 if up to date, code 1 if an update is needed.

When an update is available:

deciduous serve

Start the web graph viewer. Opens an interactive browser-based visualization of your decision graph.

Use a custom port:

deciduous backup

Create a backup of the SQLite database. Always back up before any destructive operations.

Specify a custom path:

deciduous commands

Show the recent command log – every deciduous command that modified the graph.

deciduous auto-update <on|off>

Deprecated. Version checking is now always-on (checks crates.io once per 24h). This command exists for backward compatibility but has no effect.

Graph Management

The heart of deciduous – commands for building and querying your decision graph. These are the commands you will use most.

deciduous add <type> <title>

Add a new node to the decision graph.

Node types: goal, decision, option, action, outcome, observation, revisit

Basic usage

With metadata flags

Multi-line prompts

Capture the full user request with --prompt-stdin:

Backdating nodes (archaeology)

deciduous link <from> <to>

Add an edge between two nodes.

Edge types: leads_to, requires, chosen, rejected, blocks, enables

deciduous unlink <from> <to>

Remove an edge between two nodes.

deciduous delete <id>

Delete a node and all its connected edges.

deciduous status <id> <status>

Update a node’s status.

Valid statuses: pending, active, completed, rejected, superseded, abandoned

deciduous prompt <id> [text]

Update or add a prompt to an existing node. Omit text to read from stdin.

deciduous show <id>

Show detailed information about a single node, including its connections, metadata, and prompt.

deciduous nodes

List all nodes in the graph. Use filters to narrow results.

Filtering by type

Filtering by branch

Filtering by theme

deciduous edges

List all edges in the graph.

deciduous graph

Export the full graph as JSON to stdout. Useful for scripting or piping to other tools.

Realistic Example: Full Decision Flow

Here is a complete example showing the canonical flow – goal, options, decision, action, outcome – with all connections:

Visualization & Export

Commands for generating DOT graphs, PR writeups, and exporting your decision graph for GitHub Pages.

deciduous dot

Export the graph as DOT format for Graphviz visualization.

Basic DOT export

Generate PNG directly

Requires Graphviz installed (brew install graphviz / apt install graphviz).

Filter by node range

Auto-naming for PRs

The --auto flag generates branch-specific filenames (e.g., docs/decision-graph-feature-auth.dot), which prevents merge conflicts when multiple PRs each have their own graph.

deciduous writeup

Generate a PR writeup from the decision graph. Includes a decision summary, the graph in DOT format, and a test plan section.

Basic writeup

Auto-detect PNG for embedding

When you have already generated a PNG with deciduous dot --auto --png, use --auto on writeup to find and embed it:

Update a PR body directly

deciduous sync

Export graph data to JSON files for GitHub Pages deployment. Creates the files needed for a static version of the web viewer.

The PR Workflow

The recommended workflow for including decision graphs in pull requests:

GitHub Pages Deployment

To make your decision graph publicly viewable:

1. Run deciduous sync to export
2. Push the docs/ folder to GitHub
3. Go to Settings > Pages > Deploy from branch > select /docs folder
4. Your graph will be live at https://<user>.github.io/<repo>/

Multi-User Sync

Commands for synchronizing decision graphs across multiple users. Uses an append-only event log model – each user emits events to their own JSONL file, and git handles merging.

How Event-Based Sync Works

The problem: each user has a local .deciduous/deciduous.db (gitignored). How do you share decisions?

The solution: an append-only event log.

1. Every add, link, or status command emits an event to .deciduous/sync/events/<user>.jsonl
2. Event files are git-tracked, so git pull brings in teammate events
3. deciduous events rebuild replays all events to reconstruct the database
4. Checkpoints capture full state snapshots to avoid replaying the entire history

Each node has two IDs:

• id (integer) – local database primary key, different per machine
• change_id (UUID) – globally unique, stable across all databases

deciduous events init

Initialize event-based sync in the repository. Creates the .deciduous/sync/ directory structure and configures gitignore to track sync files while ignoring the local database.

deciduous events status

Show sync status – pending events, last checkpoint, and whether a rebuild is needed.

deciduous events rebuild

Rebuild the local database from event logs and the latest checkpoint. Loads the checkpoint (if one exists), then replays all events after the checkpoint timestamp.

deciduous events checkpoint

Create a checkpoint snapshot of the current graph state. Checkpoints allow future rebuilds to skip replaying old events.

deciduous events emit <node_id>

Emit an event for a specific node. Primarily for testing or manual sync scenarios.

deciduous migrate

Add change_id columns to the database for multi-user sync support. Run this once on existing databases before using the events system.

Typical Team Workflow

AI Integration

Commands for connecting deciduous to AI assistants – MCP server, Claude Code hooks, and shell completions.

deciduous mcp

MCP (Model Context Protocol) server and setup. Running deciduous mcp with no subcommand starts the server (backward-compatible with deciduous mcp serve).

deciduous mcp serve

Start the MCP server on stdin/stdout. Exposes the full deciduous API as MCP tools for AI assistants.

Configure in your MCP client:

{"command": "deciduous", "args": ["mcp", "serve"]}

deciduous mcp setup

Set up MCP configuration for Claude Code or Claude Desktop.

Subcommands:

• deciduous mcp setup claude-code – Configure MCP for Claude Code (writes .claude/settings.local.json)
• deciduous mcp setup claude-desktop – Configure MCP for Claude Desktop (platform-specific config file)

deciduous hooks

Manage Claude Code hooks – pre-edit blocks, post-commit reminders, and other automation configured in .deciduous/config.toml.

deciduous hooks install

Install Claude Code hooks from config. Generates shell scripts in .claude/hooks/ and updates settings.json.

deciduous hooks status

Show status of configured and installed hooks.

deciduous hooks uninstall

Remove hooks and clear hook configuration from settings.

deciduous integration

Show Claude Code integration status – which hooks, commands, and skills are installed and active.

deciduous completion <shell>

Generate shell completions for tab completion of commands and flags.

Supported shells: bash, zsh, fish, powershell, elvish

Advanced

Graph health, archaeology, narratives, roadmap management, document attachments, and theming.

deciduous audit

Audit and maintain graph data quality. Can associate git commits with nodes by matching titles to commit messages.

deciduous pulse

Show the pulse of the decision graph – active state, gaps, and health. A quick overview of where things stand.

Summary only:

deciduous narratives

Manage evolution narratives in .deciduous/narratives.md. Narratives capture how the system evolved over time – the story behind the decisions.

deciduous narratives init

Initialize narratives.md with active goal titles as section headings.

deciduous narratives show

Display the contents of narratives.md.

deciduous narratives pivots

List all pivot points (revisit nodes) with their full chains – showing what changed and why.

deciduous archaeology

Retroactive graph building – atomic operations for common archaeology patterns. Useful when reconstructing decision history from an existing codebase.

deciduous archaeology pivot <from_id> <observation> <new_approach>

Create a full pivot chain atomically (replaces 7 manual commands). Creates: observation -> revisit -> new decision, and marks the old node as superseded.

deciduous archaeology timeline

Show all nodes sorted chronologically.

deciduous archaeology supersede <id>

Mark a node as superseded, optionally cascading to all descendant nodes.

deciduous roadmap

Manage ROADMAP.md sync with GitHub Issues. Parse your roadmap file, sync items to GitHub Issues, and track completion.

deciduous roadmap init

Initialize roadmap sync – parses ROADMAP.md and adds metadata.

deciduous roadmap refresh

Re-parse ROADMAP.md, preserving existing decision graph links.

deciduous roadmap sync

Sync ROADMAP.md with GitHub Issues. Dry-run by default – use --execute to apply.

deciduous roadmap list

List roadmap items with status.

deciduous roadmap link <item> <outcome_id>

Link a roadmap item to a decision graph outcome node. <item> is a change_id or title (partial match).

deciduous roadmap unlink <item>

Remove outcome link from a roadmap item.

deciduous roadmap conflicts

Show sync conflicts.

deciduous roadmap status

Show sync status summary.

deciduous roadmap check

Audit completion status of roadmap items.

deciduous doc

Manage document attachments on decision nodes. Attach images, PDFs, diagrams, specs, and other files to nodes for rich context.

deciduous doc attach <node_id> <file>

Attach a file to a decision graph node. Files are stored in .deciduous/documents/ with content-hash naming for deduplication.

deciduous doc list [node_id]

List documents. Omit node_id to list all documents.

deciduous doc show <doc_id>

Show details of a specific document.

deciduous doc describe <doc_id> [text]

Set or update the description of a document. Omit text to read from stdin.

deciduous doc open <doc_id>

Open the attached file in the default application.

deciduous doc detach <doc_id>

Soft-delete (detach) a document from its node. The file remains on disk until garbage collected.

deciduous doc gc

Garbage-collect orphaned files from disk – files that no active document records reference.

deciduous themes

Manage theme definitions for organizing nodes by cross-cutting concerns (e.g., “performance”, “security”, “tech-debt”).

deciduous themes create <name>

Create a new theme.

deciduous themes list

List all themes.

deciduous themes delete <name>

Delete a theme and remove all node associations.

deciduous tag

Tag or untag nodes with themes.

deciduous tag add <node_id> <theme>

Add a theme to a node.

deciduous tag remove <node_id> <theme>

Remove a theme from a node.

deciduous tag list <node_id>

List themes for a node.

deciduous tag suggest [node_id]

Auto-suggest themes for a node based on keyword matching. Omit node_id to suggest for all untagged nodes.

deciduous tag confirm <node_id> <theme>

Confirm a suggested theme – changes it from “suggested” to “manual” status.

Claude Code

Claude Code is the default assistant integration. Running deciduous init with no flags sets up everything Claude Code needs to track decisions automatically.

Setup

What Gets Created

Slash Commands

These appear in Claude Code as /command-name and are stored in .claude/commands/:

Skills

Skills are higher-level workflows stored in .claude/skills/:

Hooks

Enforcement hooks in .claude/hooks/ run automatically to keep the decision graph consistent:

• require-action-node.sh – Blocks file edits unless an action node exists in the graph. Prevents coding without logging what you are about to do.
• post-commit-reminder.sh – After every git commit, reminds Claude to link the commit to the decision graph with --commit HEAD.
• version-check.sh – Checks whether integration files are out of date and suggests running deciduous update.

Hook configuration lives in .claude/settings.json.

Other Files

• .claude/agents.toml – Subagent configurations for scoping work to specific parts of the codebase (rust-core, web, tooling, docs, ci).
• CLAUDE.md – A “Decision Graph Workflow” section is appended to your project’s CLAUDE.md (or created if it does not exist). This section teaches Claude the node flow rule, behavioral triggers, and connection patterns. Your existing CLAUDE.md content is preserved.

MCP Server

The MCP server gives Claude direct tool access to the decision graph instead of shelling out to the CLI. Add the following to .claude/settings.local.json:

{
  "mcpServers": {
    "deciduous": {
      "command": "deciduous",
      "args": ["mcp"]
    }
  }
}

This exposes 31 tools organized into five groups:

Keeping Integration Files Current

When you upgrade deciduous, run deciduous update to refresh all integration files to the latest version. It overwrites slash commands, hooks, skills, and the CLAUDE.md section while preserving your custom content.

To check whether an update is needed without applying it:

deciduous check-update

The version-check.sh hook runs this automatically at the start of each Claude Code session (checked every 24 hours). If your integration files are out of date, Claude will suggest running deciduous update.

Using Slash Commands

Once initialized, start a Claude Code session and use slash commands directly: