<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.40.1">
<meta name="project" content="deciduex v0.14.0-beta.3">
<title>Deciduous — deciduex v0.14.0-beta.3</title>
<link rel="stylesheet" href="dist/html-elixir-YJO4MOOW.css" />
<script defer src="dist/sidebar_items-CC54D512.js"></script>
<script defer src="docs_config.js"></script>
<script defer src="dist/html-YU4BZFVS.js"></script>
</head>
<body>
<script>(()=>{var t="ex_doc:settings",e="dark";var o="dark",s="light";var E="sidebar_state",n="closed";var r="sidebar_width";var a="sidebar-open";var i=new URLSearchParams(window.location.search),S=i.get("theme")||JSON.parse(localStorage.getItem(t)||"{}").theme;(S===o||S!==s&&window.matchMedia("(prefers-color-scheme: dark)").matches)&&document.body.classList.add(e);var d=sessionStorage.getItem(E),A=d!==n&&!window.matchMedia(`screen and (max-width: ${768}px)`).matches;document.body.classList.toggle(a,A);var c=sessionStorage.getItem(r);c&&document.body.style.setProperty("--sidebarWidth",`${c}px`);var p=/(Macintosh|iPhone|iPad|iPod)/.test(window.navigator.userAgent);document.documentElement.classList.toggle("apple-os",p);})();
</script>
<div class="body-wrapper">
<button id="sidebar-menu" class="sidebar-button sidebar-toggle" aria-label="toggle sidebar" aria-controls="sidebar">
<i class="ri-menu-line ri-lg" title="Collapse/expand sidebar"></i>
</button>
<nav id="sidebar" class="sidebar">
<div class="sidebar-header">
<div class="sidebar-projectInfo">
<div>
<a href="https://notactuallytreyanastasio.github.io/deciduous/" class="sidebar-projectName" translate="no">
deciduex
</a>
<div class="sidebar-projectVersion" translate="no">
v0.14.0-beta.3
</div>
</div>
</div>
<ul id="sidebar-list-nav" class="sidebar-list-nav" role="tablist" data-extras="Pages"></ul>
</div>
</nav>
<output role="status" id="toast"></output>
<main class="content page-extra" id="main" data-type="extras">
<div id="content" class="content-inner">
<div class="top-search">
<div class="search-settings">
<form class="search-bar" action="search.html">
<label class="search-label">
<span class="sr-only">Search documentation of deciduex</span>
<div class="search-input-wrapper">
<input name="q" type="text" class="search-input" placeholder="Press / to search" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" />
<button type="button" tabindex="-1" class="search-close-button" aria-hidden="true">
<i class="ri-close-line ri-lg" title="Cancel search"></i>
</button>
</div>
</label>
</form>
<div class="autocomplete">
</div>
<div class="engine-selector" data-multiple="false">
<button type="button" class="engine-button" aria-label="Select search engine" aria-haspopup="true" aria-expanded="false">
<i class="ri-search-2-line" aria-hidden="true"></i>
<span class="engine-name">Default</span>
<i class="ri-arrow-down-s-line" aria-hidden="true"></i>
</button>
<div class="engine-dropdown" hidden role="menu">
<button type="button"
class="engine-option"
data-engine-url="search.html?q="
role="menuitemradio"
aria-checked="true">
<span class="name">Default</span>
<span class="help">In-browser search</span>
</button>
</div>
</div>
<button class="icon-settings display-settings">
<i class="ri-settings-3-line"></i>
<span class="sr-only">Settings</span>
</button>
</div>
</div>
<div id="top-content">
<div class="heading-with-actions top-heading">
<h1>Deciduous</h1>
<a href="readme.md" title="Copy Markdown (hold Ctrl/Cmd and click it to open as Markdown)" class="copy-markdown icon-action" rel="help">
<i class="ri-markdown-line" aria-hidden="true"></i>
<span class="sr-only">Copy Markdown</span>
</a>
<a href="https://github.com/notactuallytreyanastasio/deciduous/blob/main/README.md#L1" title="View Source" class="icon-action" rel="help">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
</div>
<p><strong>Decision graph tooling for AI-assisted development.</strong> Track every goal, decision, and outcome. Survive context loss. Query your reasoning.</p><p><a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache-2.0"/></a></p><hr class="thin"/><h2 id="see-it-in-action" class="section-heading"><a href="#see-it-in-action" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">See It In Action</span></h2><p><strong><a href="https://notactuallytreyanastasio.github.io/deciduous/demo/">Browse the Live Decision Graph</a></strong> — 1,100+ decisions from building deciduous itself</p><p><strong><a href="https://notactuallytreyanastasio.github.io/deciduous/tutorial/">Interactive Tutorial</a></strong> — Learn the workflow in 15 minutes</p><hr class="thin"/><h2 id="the-problem" class="section-heading"><a href="#the-problem" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">The Problem</span></h2><p>You're building software with AI assistance. The LLM generates complex code fast. But then:</p><ul><li><strong>Sessions end.</strong> Context compacts. The LLM loses memory of what was tried.</li><li><strong>Decisions evaporate.</strong> Six months later, no one remembers <em>why</em> you chose approach A over B.</li><li><strong>PRs become incomprehensible.</strong> A 50-file diff tells you <em>what</em> changed, not <em>why</em>.</li><li><strong>Onboarding is archaeology.</strong> New teammates reverse-engineer decisions from code.</li></ul><p>The code tells you <em>what</em>. But decisions tell you <em>why</em>.</p><h2 id="the-solution" class="section-heading"><a href="#the-solution" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">The Solution</span></h2><p>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.</p><pre><code class="makeup elixir" translate="no"><span class="mi">1</span><span class="p">,</span><span class="mi">174</span><span class="w"> </span><span class="n">nodes</span><span class="w"> </span><span class="err">•</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="mi">024</span><span class="w"> </span><span class="n">edges</span><span class="w"> </span><span class="err">•</span><span class="w"> </span><span class="nc">Real</span><span class="w"> </span><span class="n">development</span><span class="w"> </span><span class="n">history</span><span class="w"> </span><span class="n">from</span><span class="w"> </span><span class="n">building</span><span class="w"> </span><span class="n">this</span><span class="w"> </span><span class="n">tool</span></code></pre><p>Both you and your AI assistant can:</p><ul><li><strong>Query past reasoning</strong> before making new decisions</li><li><strong>See what was tried</strong> and what was rejected</li><li><strong>Trace any outcome</strong> back to the goal that spawned it</li><li><strong>Recover context</strong> after sessions end or memory compacts</li></ul><p>This isn't documentation written after the fact. It's a real-time record of <em>how</em> software gets built.</p><hr class="thin"/><h2 id="installation" class="section-heading"><a href="#installation" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Installation</span></h2><h3 id="homebrew-recommended" class="section-heading"><a href="#homebrew-recommended" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Homebrew (Recommended)</span></h3><pre><code class="makeup bash" translate="no"><span class="">brew tap notactuallytreyanastasio/tap
</span><span class="">brew install deciduous
</span></code></pre><h3 id="pre-built-binaries" class="section-heading"><a href="#pre-built-binaries" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Pre-built Binaries</span></h3><p>Download the latest release for your platform from <a href="https://github.com/notactuallytreyanastasio/deciduous/releases">GitHub Releases</a>:</p><table><thead><tr><th style="text-align: left;">Platform</th><th style="text-align: left;">Binary</th></tr></thead><tbody><tr><td style="text-align: left;">Linux (x86_64)</td><td style="text-align: left;"><code class="inline">deciduex-linux-amd64</code></td></tr><tr><td style="text-align: left;">macOS (Intel)</td><td style="text-align: left;"><code class="inline">deciduex-darwin-amd64</code></td></tr><tr><td style="text-align: left;">macOS (Apple Silicon)</td><td style="text-align: left;"><code class="inline">deciduex-darwin-arm64</code></td></tr></tbody></table><pre><code class="makeup bash" translate="no"><span class=""># Example: macOS Apple Silicon
</span><span class="">curl -LO https://github.com/notactuallytreyanastasio/deciduous/releases/latest/download/deciduex-darwin-arm64
</span><span class="">chmod +x deciduex-darwin-arm64
</span><span class="">sudo mv deciduex-darwin-arm64 /usr/local/bin/deciduous
</span></code></pre><h3 id="from-source" class="section-heading"><a href="#from-source" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">From Source</span></h3><p>Requires Elixir 1.19+ and Erlang/OTP 27+.</p><pre><code class="makeup bash" translate="no"><span class="">git clone https://github.com/notactuallytreyanastasio/deciduous.git
</span><span class="">cd deciduous
</span><span class="">mix deps.get
</span><span class="">mix release
</span><span class=""># Binary at _build/prod/rel/deciduex/bin/cli
</span></code></pre><hr class="thin"/><h2 id="quick-start" class="section-heading"><a href="#quick-start" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Quick Start</span></h2><pre><code class="makeup bash" translate="no"><span class=""># Initialize in your project
</span><span class="">cd your-project
</span><span class="">deciduous init
</span><span class="">
</span><span class=""># Start logging decisions
</span><span class="">deciduous add goal "Add user authentication" -c 90
</span><span class="">deciduous add option "JWT tokens" -c 80
</span><span class="">deciduous add option "Session cookies" -c 75
</span><span class="">deciduous link 1 2 -r "Possible approach"
</span><span class="">deciduous link 1 3 -r "Possible approach"
</span><span class="">deciduous add decision "Use JWT for API, sessions for web" -c 85
</span><span class="">deciduous link 2 4 -r "Chosen approach"
</span><span class="">deciduous link 3 4 -r "Also incorporated"
</span><span class="">
</span><span class=""># Export the graph
</span><span class="">deciduous sync # Export to docs/graph-data.json
</span></code></pre><p>That's it. Your first decision graph is ready.</p><h3 id="the-canonical-flow" class="section-heading"><a href="#the-canonical-flow" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">The Canonical Flow</span></h3><p>Every decision follows this path through the graph:</p><pre><code class="makeup elixir" translate="no"><span class="n">goal</span><span class="w"> </span><span class="err">→</span><span class="w"> </span><span class="n">options</span><span class="w"> </span><span class="err">→</span><span class="w"> </span><span class="n">decision</span><span class="w"> </span><span class="err">→</span><span class="w"> </span><span class="n">actions</span><span class="w"> </span><span class="err">→</span><span class="w"> </span><span class="n">outcomes</span></code></pre><ul><li><strong>Goals</strong> lead to <strong>options</strong> (possible approaches to explore)</li><li><strong>Options</strong> lead to a <strong>decision</strong> (choosing which option to pursue)</li><li><strong>Decisions</strong> lead to <strong>actions</strong> (implementing the chosen approach)</li><li><strong>Actions</strong> lead to <strong>outcomes</strong> (results of the implementation)</li><li><strong>Observations</strong> attach anywhere relevant</li><li><strong>Revisits</strong> connect old approaches to new ones when you pivot</li></ul><h3 id="multi-assistant-support" class="section-heading"><a href="#multi-assistant-support" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Multi-Assistant Support</span></h3><p>Deciduous integrates with multiple AI coding assistants:</p><pre><code class="makeup bash" translate="no"><span class=""># Claude Code (default)
</span><span class="">deciduous init
</span><span class="">
</span><span class=""># OpenCode
</span><span class="">deciduous init --opencode
</span><span class="">
</span><span class=""># Windsurf (Codeium)
</span><span class="">deciduous init --windsurf
</span><span class="">
</span><span class=""># Multiple assistants
</span><span class="">deciduous init --both # Claude Code + OpenCode
</span><span class="">deciduous init --windsurf # + Windsurf (auto-creates .windsurf/)
</span><span class="">deciduous init --both --windsurf # All three
</span></code></pre><table><thead><tr><th style="text-align: left;">Assistant</th><th style="text-align: left;">Flag</th><th style="text-align: left;">Integration Files</th></tr></thead><tbody><tr><td style="text-align: left;"><strong>Claude Code</strong></td><td style="text-align: left;"><code class="inline">--claude</code> (default)</td><td style="text-align: left;"><code class="inline">.claude/</code>, <code class="inline">CLAUDE.md</code></td></tr><tr><td style="text-align: left;"><strong>OpenCode</strong></td><td style="text-align: left;"><code class="inline">--opencode</code></td><td style="text-align: left;"><code class="inline">.opencode/</code>, <code class="inline">AGENTS.md</code></td></tr><tr><td style="text-align: left;"><strong>Windsurf</strong></td><td style="text-align: left;"><code class="inline">--windsurf</code></td><td style="text-align: left;"><code class="inline">.windsurf/hooks/</code>, <code class="inline">.windsurf/rules/</code></td></tr></tbody></table><p><strong>Auto-detection:</strong> <code class="inline">deciduous update</code> auto-detects which assistants are installed (<code class="inline">.claude/</code>, <code class="inline">.opencode/</code>, <code class="inline">.windsurf/</code>) and updates them all. Windsurf is also auto-detected during <code class="inline">init</code> if <code class="inline">.windsurf/</code> already exists.</p><hr class="thin"/><h2 id="the-workflow" class="section-heading"><a href="#the-workflow" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">The Workflow</span></h2><pre><code class="makeup elixir" translate="no"><span class="nc">BEFORE</span><span class="w"> </span><span class="n">you</span><span class="w"> </span><span class="k" data-group-id="9027716028-1">do</span><span class="w"> </span><span class="n">something</span><span class="w"> </span><span class="err">→</span><span class="w"> </span><span class="nc">Log</span><span class="w"> </span><span class="n">what</span><span class="w"> </span><span class="n">you</span><span class="err">'</span><span class="n">re</span><span class="w"> </span><span class="nc">ABOUT</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="k" data-group-id="9027716028-2">do</span><span class="w">
</span><span class="nc">AFTER</span><span class="w"> </span><span class="n">it</span><span class="w"> </span><span class="n">succeeds</span><span class="o">/</span><span class="n">fails</span><span class="w"> </span><span class="err">→</span><span class="w"> </span><span class="nc">Log</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">outcome</span><span class="w">
</span><span class="nc">CONNECT</span><span class="w"> </span><span class="n">immediately</span><span class="w"> </span><span class="err">→</span><span class="w"> </span><span class="nc">Link</span><span class="w"> </span><span class="n">every</span><span class="w"> </span><span class="n">node</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">its</span><span class="w"> </span><span class="n">parent</span></code></pre><h3 id="example-session" class="section-heading"><a href="#example-session" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Example Session</span></h3><pre><code class="makeup bash" translate="no"><span class=""># Starting a new feature
</span><span class="">deciduous add goal "Add rate limiting" -c 90 -p "User asked: add rate limiting to the API"
</span><span class="">
</span><span class=""># Considering options
</span><span class="">deciduous add option "Redis-based distributed" -c 80
</span><span class="">deciduous add option "In-memory sliding window" -c 70
</span><span class="">deciduous link 1 2 -r "Possible approach"
</span><span class="">deciduous link 1 3 -r "Possible approach"
</span><span class="">
</span><span class=""># Attach the design spec to the goal
</span><span class="">deciduous doc attach 1 docs/rate-limiting-spec.pdf -d "Rate limiting design spec"
</span><span class="">
</span><span class=""># Making a choice
</span><span class="">deciduous add decision "Use Redis rate limiter" -c 85
</span><span class="">deciduous link 2 4 --edge-type chosen -r "Scales across instances"
</span><span class="">deciduous link 3 4 --edge-type rejected -r "Doesn't scale horizontally"
</span><span class="">
</span><span class=""># Implementing the chosen approach
</span><span class="">deciduous add action "Implementing Redis rate limiter" -c 85
</span><span class="">deciduous link 4 5 -r "Implementation"
</span><span class="">
</span><span class=""># Attach the architecture diagram to the action
</span><span class="">deciduous doc attach 5 docs/redis-arch.png --ai-describe
</span><span class="">
</span><span class=""># Recording the outcome
</span><span class="">deciduous add outcome "Rate limiting working in prod" -c 95
</span><span class="">deciduous link 5 6 -r "Implementation complete"
</span><span class="">
</span><span class=""># Export the graph
</span><span class="">deciduous sync
</span></code></pre><h3 id="document-attachments" class="section-heading"><a href="#document-attachments" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Document Attachments</span></h3><p>Attach files to any decision node — architecture diagrams, specs, screenshots, PDFs.</p><pre><code class="makeup bash" translate="no"><span class=""># Attach a diagram to a goal
</span><span class="">deciduous doc attach 1 docs/architecture.png -d "System architecture diagram"
</span><span class="">
</span><span class=""># AI-generate a description
</span><span class="">deciduous doc attach 1 screenshot.png --ai-describe
</span><span class="">
</span><span class=""># List what's attached
</span><span class="">deciduous doc list 1
</span><span class="">
</span><span class=""># Open a document
</span><span class="">deciduous doc open 3
</span><span class="">
</span><span class=""># Soft-delete (recoverable)
</span><span class="">deciduous doc detach 3
</span><span class="">
</span><span class=""># Clean up orphaned files
</span><span class="">deciduous doc gc
</span></code></pre><p>Documents are stored in <code class="inline">.deciduous/documents/</code> with content-hash naming for deduplication. The web viewer displays attached documents in the node detail panel. Soft-delete with <code class="inline">doc detach</code>; garbage-collect orphaned files with <code class="inline">doc gc --dry-run</code> to preview.</p><h3 id="session-recovery" class="section-heading"><a href="#session-recovery" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Session Recovery</span></h3><p>When context compacts or you start a new session:</p><pre><code class="makeup bash" translate="no"><span class="">deciduous nodes # What decisions exist?
</span><span class="">deciduous edges # How are they connected?
</span><span class="">deciduous commands # What happened recently?
</span></code></pre><p>Or open the web viewer and ask a question in plain English:</p><blockquote><p><em>"What was I working on before the session ended?"</em>
<em>"What approach did we take for rate limiting and why?"</em></p></blockquote><p>The graph remembers what you don't. The Q&A interface lets you ask it.</p><hr class="thin"/><h2 id="skills-archaeology-decision-graph-and-narratives" class="section-heading"><a href="#skills-archaeology-decision-graph-and-narratives" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Skills: Archaeology, Decision-Graph, and Narratives</span></h2><p>Deciduous ships with skills that give your AI assistant structured ways to understand and work with a codebase's decision history.</p><h3 id="decision-graph-visiting-and-documenting-the-past" class="section-heading"><a href="#decision-graph-visiting-and-documenting-the-past" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">/decision-graph — Visiting and documenting the past</span></h3><p>The <code class="inline">/decision-graph</code> 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:</p><ol><li><strong>Commit analysis</strong> — Groups commits into logical narratives</li><li><strong>Code structure</strong> — Identifies architectural decisions from the codebase</li><li><strong>Narrative construction</strong> — Builds evolution stories with pivots and connections</li><li><strong>PR context</strong> — Uses <code class="inline">gh</code> CLI to mine PR descriptions and review threads for decision rationale, alternatives considered, and trade-offs discussed</li></ol><h3 id="archaeology-revisit-correct-execute" class="section-heading"><a href="#archaeology-revisit-correct-execute" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">/archaeology — Revisit, correct, execute</span></h3><p>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.</p><pre><code class="makeup bash" translate="no"><span class=""># Find the old decision and mark it
</span><span class="">deciduous nodes --status active --type decision
</span><span class="">deciduous add observation "Mobile Safari 4KB cookie limit breaking JWT auth"
</span><span class="">deciduous link 1 2 -r "Discovered in production"
</span><span class="">
</span><span class=""># Revisit: pivot from old approach to new
</span><span class="">deciduous add revisit "Reconsidering auth token strategy"
</span><span class="">deciduous link 2 3 -r "Cookie limits forced rethink"
</span><span class="">deciduous status 1 superseded
</span><span class="">
</span><span class=""># Execute the new direction
</span><span class="">deciduous add decision "Hybrid: JWT for API, sessions for web"
</span><span class="">deciduous link 3 4 -r "New approach"
</span><span class="">deciduous add action "Implementing hybrid auth" -c 85
</span><span class="">deciduous link 4 5 -r "Implementation"
</span></code></pre><p>After archaeology, you can query: "What did we try before?" (<code class="inline">--status superseded</code>), "What led to this decision?" (<code class="inline">edges --to <id></code>), "What are the pivot points?" (<code class="inline">--type revisit</code>).</p><h3 id="narratives-understand-how-the-system-evolved" class="section-heading"><a href="#narratives-understand-how-the-system-evolved" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">/narratives — Understand how the system evolved</span></h3><p>Narratives are the conceptual stories—how a subsystem evolved over time, what pivots happened, and how different parts of the system connect.</p><pre><code class="markdown">## 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"</code></pre><p>Output: <code class="inline">.deciduous/narratives.md</code> with evolution stories that archaeology can transform into graph structure.</p><h3 id="pulse-map-the-current-design" class="section-heading"><a href="#pulse-map-the-current-design" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">/pulse — Map the current design</span></h3><p>Pulse maps the current architecture as a decision tree — the design choices that make the system work today. Your agent reads the code, identifies the design questions that had to be answered, and logs them as nodes. Useful for understanding what decisions you might affect before making changes.</p><hr class="thin"/><h2 id="deep-q-a-interface" class="section-heading"><a href="#deep-q-a-interface" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Deep Q&A Interface</span></h2><p>The <a href="https://github.com/notactuallytreyanastasio/deciduous-viewer">deciduous-viewer</a> Phoenix app includes a built-in Q&A interface where you can ask questions about your decision graph and get answers grounded in your actual development history.</p><p>The Q&A system:</p><ul><li><strong>Sends your question + graph context to Claude</strong> — it sees the relevant nodes, edges, and narrative context</li><li><strong>Archaeology-aware</strong> — when asking from the archaeology view, the agent gets full narrative context including pivots, superseded approaches, and GitHub links</li><li><strong>Stores every interaction</strong> — questions and answers are saved with full-text search</li><li><strong>Searchable history</strong> — find past conversations about specific topics</li></ul><p>This turns the graph into a conversational interface. Instead of manually traversing nodes, ask: <em>"What was tried before the current approach?"</em> or <em>"What connects the auth system to rate limiting?"</em></p><hr class="thin"/><h2 id="viewing-the-graph" class="section-heading"><a href="#viewing-the-graph" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Viewing the Graph</span></h2><h3 id="web-viewer-separate-package" class="section-heading"><a href="#web-viewer-separate-package" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Web Viewer (Separate Package)</span></h3><p>The decision graph web viewer is available as a separate Phoenix application. See <a href="https://github.com/notactuallytreyanastasio/deciduous-viewer">deciduous-viewer</a> for installation and usage.</p><p>The viewer provides five views:</p><table><thead><tr><th style="text-align: left;">View</th><th style="text-align: left;">Purpose</th></tr></thead><tbody><tr><td style="text-align: left;"><strong>Chains</strong></td><td style="text-align: left;">Decision chains by session—see the story of a feature</td></tr><tr><td style="text-align: left;"><strong>Timeline</strong></td><td style="text-align: left;">Chronological view merged with git commits</td></tr><tr><td style="text-align: left;"><strong>Graph</strong></td><td style="text-align: left;">Force-directed interactive visualization</td></tr><tr><td style="text-align: left;"><strong>DAG</strong></td><td style="text-align: left;">Hierarchical goal→decision→outcome flow</td></tr><tr><td style="text-align: left;"><strong>Archaeology</strong></td><td style="text-align: left;">Narrative-driven exploration with Q&A</td></tr></tbody></table><h3 id="static-export" class="section-heading"><a href="#static-export" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Static Export</span></h3><p>Export your graph for hosting on GitHub Pages:</p><pre><code class="makeup bash" translate="no"><span class="">deciduous sync # Export to docs/graph-data.json
</span></code></pre><p>Then push to GitHub with Pages enabled for the <code class="inline">/docs</code> folder.</p><hr class="thin"/><h2 id="node-types" class="section-heading"><a href="#node-types" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Node Types</span></h2><table><thead><tr><th style="text-align: left;">Type</th><th style="text-align: left;">Purpose</th><th style="text-align: left;">Example</th></tr></thead><tbody><tr><td style="text-align: left;"><code class="inline">goal</code></td><td style="text-align: left;">High-level objective</td><td style="text-align: left;">"Add user authentication"</td></tr><tr><td style="text-align: left;"><code class="inline">option</code></td><td style="text-align: left;">Approach considered</td><td style="text-align: left;">"Use JWT tokens"</td></tr><tr><td style="text-align: left;"><code class="inline">decision</code></td><td style="text-align: left;">Choice point</td><td style="text-align: left;">"Choose auth method"</td></tr><tr><td style="text-align: left;"><code class="inline">action</code></td><td style="text-align: left;">Implementation step</td><td style="text-align: left;">"Added JWT middleware"</td></tr><tr><td style="text-align: left;"><code class="inline">outcome</code></td><td style="text-align: left;">Result</td><td style="text-align: left;">"Auth working in prod"</td></tr><tr><td style="text-align: left;"><code class="inline">observation</code></td><td style="text-align: left;">Discovery or insight</td><td style="text-align: left;">"JWT tokens too large for mobile"</td></tr><tr><td style="text-align: left;"><code class="inline">revisit</code></td><td style="text-align: left;">Pivot point—connects old approach to new</td><td style="text-align: left;">"Reconsidering token strategy"</td></tr></tbody></table><h2 id="node-status" class="section-heading"><a href="#node-status" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Node Status</span></h2><table><thead><tr><th style="text-align: left;">Status</th><th style="text-align: left;">Meaning</th></tr></thead><tbody><tr><td style="text-align: left;"><code class="inline">active</code></td><td style="text-align: left;">Current truth—how things work today</td></tr><tr><td style="text-align: left;"><code class="inline">superseded</code></td><td style="text-align: left;">Replaced by a newer approach</td></tr><tr><td style="text-align: left;"><code class="inline">abandoned</code></td><td style="text-align: left;">Tried and rejected—dead end</td></tr></tbody></table><pre><code class="makeup bash" translate="no"><span class="">deciduous status <node_id> superseded
</span><span class="">deciduous nodes --status active # Now mode
</span><span class="">deciduous nodes --status superseded # What was tried
</span></code></pre><h2 id="edge-types" class="section-heading"><a href="#edge-types" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Edge Types</span></h2><table><thead><tr><th style="text-align: left;">Type</th><th style="text-align: left;">Meaning</th></tr></thead><tbody><tr><td style="text-align: left;"><code class="inline">leads_to</code></td><td style="text-align: left;">Natural progression</td></tr><tr><td style="text-align: left;"><code class="inline">chosen</code></td><td style="text-align: left;">Selected this option</td></tr><tr><td style="text-align: left;"><code class="inline">rejected</code></td><td style="text-align: left;">Did not select (with reason)</td></tr><tr><td style="text-align: left;"><code class="inline">requires</code></td><td style="text-align: left;">Dependency</td></tr><tr><td style="text-align: left;"><code class="inline">blocks</code></td><td style="text-align: left;">Preventing progress</td></tr><tr><td style="text-align: left;"><code class="inline">enables</code></td><td style="text-align: left;">Makes possible</td></tr><tr><td style="text-align: left;"><code class="inline">supersedes</code></td><td style="text-align: left;">New approach replaces old (via revisit)</td></tr></tbody></table><hr class="thin"/><h2 id="graph-maintenance" class="section-heading"><a href="#graph-maintenance" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Graph Maintenance</span></h2><p>Made a mistake? Fix it:</p><pre><code class="makeup bash" translate="no"><span class=""># Remove an edge
</span><span class="">deciduous unlink 5 12
</span><span class="">
</span><span class=""># Delete a node (cascades to connected edges)
</span><span class="">deciduous delete 42
</span><span class="">
</span><span class=""># Preview before deleting
</span><span class="">deciduous delete 42 --dry-run
</span></code></pre><hr class="thin"/><h2 id="keeping-ai-integration-updated" class="section-heading"><a href="#keeping-ai-integration-updated" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Keeping AI Integration Updated</span></h2><p>When deciduous releases new features, your existing projects can get the latest integration files:</p><pre><code class="makeup bash" translate="no"><span class=""># Check if an update is needed
</span><span class="">deciduous check-update
</span><span class="">
</span><span class=""># Update integration files (auto-detects installed assistants)
</span><span class="">deciduous update
</span></code></pre><p>The <code class="inline">update</code> command auto-detects which assistants are installed and updates them:</p><h3 id="claude-code-claude" class="section-heading"><a href="#claude-code-claude" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Claude Code (<code class="inline">.claude/</code>)</span></h3><table><thead><tr><th style="text-align: left;">Files</th><th style="text-align: left;">What's Updated</th></tr></thead><tbody><tr><td style="text-align: left;"><code class="inline">.claude/commands/*.md</code></td><td style="text-align: left;">Slash commands (<code class="inline">/decision</code>, <code class="inline">/recover</code>, <code class="inline">/work</code>, <code class="inline">/document</code>, <code class="inline">/build-test</code>, <code class="inline">/serve-ui</code>, <code class="inline">/sync-graph</code>, <code class="inline">/decision-graph</code>, <code class="inline">/sync</code>)</td></tr><tr><td style="text-align: left;"><code class="inline">.claude/skills/*.md</code></td><td style="text-align: left;">Skills (<code class="inline">/pulse</code>, <code class="inline">/narratives</code>, <code class="inline">/archaeology</code>)</td></tr><tr><td style="text-align: left;"><code class="inline">.claude/hooks/*.sh</code></td><td style="text-align: left;">Enforcement hooks</td></tr><tr><td style="text-align: left;"><code class="inline">.claude/agents.toml</code></td><td style="text-align: left;">Subagent configurations</td></tr><tr><td style="text-align: left;"><code class="inline">CLAUDE.md</code></td><td style="text-align: left;">Decision Graph Workflow section (preserves custom content)</td></tr></tbody></table><h3 id="opencode-opencode" class="section-heading"><a href="#opencode-opencode" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">OpenCode (<code class="inline">.opencode/</code>)</span></h3><table><thead><tr><th style="text-align: left;">Files</th><th style="text-align: left;">What's Updated</th></tr></thead><tbody><tr><td style="text-align: left;"><code class="inline">.opencode/plugins/*.ts</code></td><td style="text-align: left;">TypeScript hooks (pre-edit, post-commit)</td></tr><tr><td style="text-align: left;"><code class="inline">.opencode/commands/*.md</code></td><td style="text-align: left;">Command templates</td></tr><tr><td style="text-align: left;"><code class="inline">.opencode/skills/*/SKILL.md</code></td><td style="text-align: left;">Skill definitions</td></tr><tr><td style="text-align: left;"><code class="inline">.opencode/agents/*.md</code></td><td style="text-align: left;">Custom deciduous agent</td></tr><tr><td style="text-align: left;"><code class="inline">.opencode/tools/*.ts</code></td><td style="text-align: left;">Custom deciduous tool</td></tr><tr><td style="text-align: left;"><code class="inline">.opencode/opencode.json</code></td><td style="text-align: left;">Plugin configuration</td></tr><tr><td style="text-align: left;"><code class="inline">AGENTS.md</code></td><td style="text-align: left;">Decision Graph Workflow section</td></tr></tbody></table><h3 id="windsurf-windsurf" class="section-heading"><a href="#windsurf-windsurf" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Windsurf (<code class="inline">.windsurf/</code>)</span></h3><table><thead><tr><th style="text-align: left;">Files</th><th style="text-align: left;">What's Updated</th></tr></thead><tbody><tr><td style="text-align: left;"><code class="inline">.windsurf/hooks.json</code></td><td style="text-align: left;">Cascade hooks configuration</td></tr><tr><td style="text-align: left;"><code class="inline">.windsurf/hooks/*.sh</code></td><td style="text-align: left;">Hook scripts (pre-write, post-command)</td></tr><tr><td style="text-align: left;"><code class="inline">.windsurf/rules/deciduous.md</code></td><td style="text-align: left;">Always-on rules for Cascade</td></tr></tbody></table><p><strong>Not touched:</strong> Settings files, <code class="inline">.deciduous/config.toml</code>, <code class="inline">docs/</code> - your configs stay intact.</p><h3 id="automatic-version-checking" class="section-heading"><a href="#automatic-version-checking" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Automatic Version Checking</span></h3><p>The <code class="inline">check-update</code> command compares <code class="inline">.deciduous/.version</code> with the binary version:</p><pre><code class="makeup bash" translate="no"><span class="gp unselectable">$ </span><span class="">deciduous check-update
</span><span class="">Update available: Integration files are v0.9.4, binary is v0.9.5. Run 'deciduous update'.
</span></code></pre><p>Add this to your session start routine to catch updates automatically.</p><hr class="thin"/><h2 id="the-premises" class="section-heading"><a href="#the-premises" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">The Premises</span></h2><ol><li><p><strong>Decisions are the unit of institutional knowledge.</strong> Code tells you <em>what</em>, but decisions tell you <em>why</em>. Six months from now, you won't remember why you chose Redis over Postgres for that cache. The graph will.</p></li><li><p><strong>Structured thinking produces better outcomes.</strong> The act of logging a decision—naming it, assigning confidence, connecting it to goals—forces you to think it through.</p></li><li><p><strong>Real-time logging beats retroactive documentation.</strong> Capture reasoning in the moment. By the time you write post-hoc docs, you've forgotten the options you rejected.</p></li><li><p><strong>Graphs beat documents.</strong> Goals spawn decisions, decisions spawn actions, actions produce outcomes. A graph captures these relationships. You can trace any outcome to its origin.</p></li><li><p><strong>Complex PRs tell a story.</strong> A 50-file diff is incomprehensible. A decision graph shows the goal, the key decisions, the rejected approaches, and how each change connects to purpose.</p></li><li><p><strong>Context loss is inevitable.</strong> Sessions end. Memory compacts. The graph survives.</p></li><li><p><strong>The graph is a shared workspace.</strong> Decisions flow between sessions, between humans and AI, between teammates. The graph doesn't care who's typing—it preserves the reasoning.</p></li></ol><hr class="thin"/><h2 id="commands-reference" class="section-heading"><a href="#commands-reference" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Commands Reference</span></h2><pre><code class="makeup bash" translate="no"><span class=""># Initialize
</span><span class="">deciduous init # Initialize with Claude Code (default)
</span><span class="">deciduous init --opencode # Initialize with OpenCode
</span><span class="">deciduous init --windsurf # Initialize with Windsurf
</span><span class="">deciduous init --both # Initialize with Claude Code + OpenCode
</span><span class="">deciduous init --both --windsurf # All three assistants
</span><span class="">deciduous update # Update tooling (auto-detects installed assistants)
</span><span class="">deciduous check-update # Check if update is needed
</span><span class="">
</span><span class=""># Add nodes
</span><span class="">deciduous add goal "Title" -c 90
</span><span class="">deciduous add decision "Title" -c 75
</span><span class="">deciduous add action "Title" -c 85 --commit HEAD # Link to git commit
</span><span class="">
</span><span class=""># Node options
</span><span class="">-c, --confidence <0-100> # Confidence level
</span><span class="">-p, --prompt "..." # User prompt that triggered this
</span><span class="">--prompt-stdin # Read prompt from stdin (multi-line)
</span><span class="">-f, --files "a.ex,b.ex" # Associated files
</span><span class="">--commit <hash|HEAD> # Link to git commit
</span><span class="">--date "YYYY-MM-DD" # Backdate node (for archaeology)
</span><span class="">
</span><span class=""># Connect and disconnect
</span><span class="">deciduous link <from> <to> -r "reason"
</span><span class="">deciduous unlink <from> <to>
</span><span class="">
</span><span class=""># Delete nodes
</span><span class="">deciduous delete <id>
</span><span class="">deciduous delete <id> --dry-run
</span><span class="">
</span><span class=""># Query
</span><span class="">deciduous nodes # List all nodes
</span><span class="">deciduous nodes -b main # Filter by branch
</span><span class="">deciduous nodes --status active
</span><span class="">deciduous nodes --type goal
</span><span class="">deciduous edges # List connections
</span><span class="">deciduous edges --to <id> # Edges pointing to a node
</span><span class="">deciduous edges --from <id> # Edges from a node
</span><span class="">deciduous graph # Full graph as JSON
</span><span class="">deciduous commands # Recent command log
</span><span class="">
</span><span class=""># Export
</span><span class="">deciduous sync # Export to docs/
</span><span class="">deciduous writeup -t "Title" # Generate PR writeup
</span><span class="">deciduous backup # Create database backup
</span><span class="">
</span><span class=""># Document attachments
</span><span class="">deciduous doc attach <node_id> <file> # Attach file to node
</span><span class="">deciduous doc attach <node_id> <file> -d "..." # With description
</span><span class="">deciduous doc attach <node_id> <file> --ai-describe # AI description
</span><span class="">deciduous doc list # List all documents
</span><span class="">deciduous doc list <node_id> # Documents for a node
</span><span class="">deciduous doc show <id> # Document details
</span><span class="">deciduous doc describe <id> "text" # Set description
</span><span class="">deciduous doc describe <id> --ai # AI-generate description
</span><span class="">deciduous doc open <id> # Open in default app
</span><span class="">deciduous doc detach <id> # Soft-delete
</span><span class="">deciduous doc gc # Clean orphaned files
</span><span class="">deciduous doc gc --dry-run # Preview cleanup
</span></code></pre><hr class="thin"/><h2 id="architecture" class="section-heading"><a href="#architecture" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Architecture</span></h2><p>Deciduous is built with Elixir/OTP for reliability and easy deployment as a single binary.</p><pre><code class="makeup elixir" translate="no"><span class="n">lib</span><span class="o">/</span><span class="w">
</span><span class="err">├</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">deciduex</span><span class="o">/</span><span class="w">
</span><span class="err">│</span><span class="w"> </span><span class="err">├</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">cli</span><span class="o">.</span><span class="n">ex</span><span class="w"> </span><span class="c1"># CLI entry point</span><span class="w">
</span><span class="err">│</span><span class="w"> </span><span class="err">├</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">commands</span><span class="o">/</span><span class="w"> </span><span class="c1"># Command implementations</span><span class="w">
</span><span class="err">│</span><span class="w"> </span><span class="err">├</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">queries</span><span class="o">.</span><span class="n">ex</span><span class="w"> </span><span class="c1"># Read operations</span><span class="w">
</span><span class="err">│</span><span class="w"> </span><span class="err">├</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">mutations</span><span class="o">.</span><span class="n">ex</span><span class="w"> </span><span class="c1"># Write operations</span><span class="w">
</span><span class="err">│</span><span class="w"> </span><span class="err">└</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">schema</span><span class="o">/</span><span class="w"> </span><span class="c1"># Ecto schemas</span><span class="w">
</span><span class="err">└</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">priv</span><span class="o">/</span><span class="w">
</span><span class="err">└</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">templates</span><span class="o">/</span><span class="w"> </span><span class="c1"># Integration file templates</span><span class="w">
</span><span class="o">.</span><span class="n">deciduous</span><span class="o">/</span><span class="w">
</span><span class="err">├</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">deciduous</span><span class="o">.</span><span class="n">db</span><span class="w"> </span><span class="c1"># SQLite database</span><span class="w">
</span><span class="err">├</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">documents</span><span class="o">/</span><span class="w"> </span><span class="c1"># Attached files</span><span class="w">
</span><span class="err">└</span><span class="err">─</span><span class="err">─</span><span class="w"> </span><span class="n">config</span><span class="o">.</span><span class="n">toml</span><span class="w"> </span><span class="c1"># Configuration</span></code></pre><p>The web viewer is a separate package: <a href="https://github.com/notactuallytreyanastasio/deciduous-viewer">deciduous-viewer</a>.</p><hr class="thin"/><h2 id="who-uses-deciduous" class="section-heading"><a href="#who-uses-deciduous" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Who Uses Deciduous</span></h2><p><strong>You, the developer:</strong></p><ul><li>Think through decisions by structuring them</li><li>Remember why you made choices months later</li><li>Review PRs by understanding the decision flow</li><li>Onboard to codebases by reading decision history</li><li>Ask questions about your own project's history and get grounded answers</li></ul><p><strong>Your AI assistant:</strong></p><ul><li>Recover context after compaction or session boundaries</li><li>Build on previous reasoning instead of starting fresh</li><li>Leave a queryable trail for future sessions</li><li>Use <code class="inline">/archaeology</code> to revisit and correct past decisions</li><li>Use <code class="inline">/decision-graph</code> to build decision graphs from commit history</li><li>Use <code class="inline">/document</code> to generate comprehensive docs with test examples</li><li>Ask deep questions via the Q&A interface grounded in actual graph data</li><li>Attach relevant documents (diagrams, screenshots, specs) to decision nodes</li></ul><p><strong>Your team:</strong></p><ul><li>Share decision context via patch files</li><li>Review PRs with full visibility into reasoning</li><li>Build institutional knowledge that survives turnover</li><li>Search past Q&A interactions to find answers that were already given</li></ul><hr class="thin"/><h2 id="why-deciduous" class="section-heading"><a href="#why-deciduous" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Why "deciduous"?</span></h2><p>It almost has the word "decision" in it, and they're trees.</p><hr class="thin"/><p><strong><a href="https://notactuallytreyanastasio.github.io/deciduous/tutorial/">Tutorial</a></strong> · <strong><a href="https://notactuallytreyanastasio.github.io/deciduous/demo/">Live Demo</a></strong> · <strong><a href="https://github.com/notactuallytreyanastasio/deciduous">GitHub</a></strong></p>
</div>
<div class="bottom-actions" id="bottom-actions">
<div class="bottom-actions-item">
</div>
<div class="bottom-actions-item">
<a href="changelog.html" class="bottom-actions-button" rel="next">
<span class="subheader">
Next Page →
</span>
<span class="title">
Changelog
</span>
</a>
</div>
</div>
<footer class="footer">
<p>
<span class="line">
<a href="https://hex.pm/packages/deciduex/0.14.0-beta.3">Hex Package</a>
<a href="https://preview.hex.pm/preview/deciduex/0.14.0-beta.3">Hex Preview</a>
(<a href="https://preview.hex.pm/preview/deciduex/0.14.0-beta.3/show/README.md">current file</a>)
</span>
<span class="line">
<button class="a-main footer-button display-quick-switch" title="Go to package docs">
Go to package docs
</button>
<a href="llms.txt" target="_blank">
View llms.txt
</a>
<a href="deciduex.epub">
Download ePub version
</a>
</span>
</p>
<p class="built-using">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener" translate="no">ExDoc</a> (v0.40.1) for the
<a href="https://elixir-lang.org" title="Elixir" target="_blank" translate="no">Elixir programming language</a>
</p>
</footer>
</div>
</main>
</div>
</body>
</html>