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.

Terminal

$ deciduous serve
Serving decision graph at http://localhost:3000
Press Ctrl+C to stop

$ deciduous serve --port 8080
Serving decision graph at http://localhost:8080

The viewer provides five browsing modes:

View	Purpose
Chains	Decision chains grouped by session — the story of a feature
Timeline	Chronological view merged with git commits
Graph	Force-directed interactive visualization
DAG	Hierarchical goal → decision → outcome flow
Archaeology	Narrative-driven exploration with Q&A

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).

Terminal

$ deciduous dot
digraph deciduous {
rankdir=TB;
node [shape=box, style=rounded];
1 [label="Add user auth" fillcolor="#d1f7d6"];
...
}

$ deciduous dot --png -o docs/decision-graph.dot
Written DOT to docs/decision-graph.dot
Generated PNG: docs/decision-graph.png

$ deciduous dot --png --auto --nodes 1-15
Written DOT to docs/decision-graph-feature-auth.dot
Generated PNG: docs/decision-graph-feature-auth.png

DOT Options

Flag	Description
`-o, --output <FILE>`	Output file (default: stdout)
`-r, --roots <IDS>`	Root node IDs for BFS traversal (comma-separated)
`-n, --nodes <SPEC>`	Specific node IDs or ranges (e.g., `1-11` or `1,3,5-10`)
`-t, --title <TITLE>`	Graph title
`--rankdir <DIR>`	Graph direction: `TB` (top-bottom) or `LR` (left-right)
`--png`	Generate PNG file (requires graphviz)
`--auto`	Use branch-specific filenames to avoid merge conflicts

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.

Terminal

$ deciduous writeup -t "Add JWT Authentication" --nodes 1-11
## Add JWT Authentication

### Decision Flow
- Goal: Add user authentication (confidence: 90%)
- Decision: Use JWT for API auth (chosen over session cookies)
- Actions: 3 implementation steps, all completed
...

$ deciduous writeup --auto -t "JWT Auth" --nodes 1-11 -o PR-WRITEUP.md
Written writeup to PR-WRITEUP.md

Writeup Options

Flag	Description
`-t, --title <TITLE>`	PR title
`-r, --roots <IDS>`	Root node IDs (traverses children)
`-n, --nodes <SPEC>`	Specific node IDs or ranges
`-o, --output <FILE>`	Output file (default: stdout)
`--png <FILENAME>`	PNG to embed (auto-detects GitHub repo/branch for URL)
`--auto`	Auto-detect PNG from branch-specific filename
`--no-dot`	Skip DOT graph section
`--no-test-plan`	Skip test plan section

Recommended PR Workflow

Terminal

$ deciduous dot --auto --nodes 1-11 --png
Written DOT to docs/decision-graph-feature-auth.dot
Generated PNG: docs/decision-graph-feature-auth.png

$ git add docs/decision-graph-feature-auth.dot docs/decision-graph-feature-auth.png
$ git commit -m "docs: add decision graph for auth PR"
$ git push

$ gh pr edit 42 --body "$(deciduous writeup --auto -t 'Add JWT Auth' --nodes 1-11)"
https://github.com/user/repo/pull/42

Sync for GitHub Pages

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

Terminal

$ deciduous sync
Exported graph to docs/graph-data.json (42 nodes, 38 edges)
Exported git history to docs/git-history.json (12 linked commits)

This creates two files in docs/:

File	Contents
`docs/graph-data.json`	Decision graph (nodes + edges)
`docs/git-history.json`	Commit info for linked nodes

Deploying to GitHub Pages

Run deciduous sync to export
Commit and push the docs/ directory
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:

Terminal

$ deciduous graph > graph.json

Keyboard shortcuts

Deciduous