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
| Flag | Short | Description |
|---|---|---|
--description <text> | -d | Optional description |
--confidence <0-100> | -c | Confidence level |
--commit <hash|HEAD> | Link to git commit (HEAD auto-resolves) | |
--prompt <text> | -p | Prompt that triggered this decision |
--prompt-stdin | Read prompt from stdin (for multi-line) | |
--files <paths> | -f | Associated files (comma-separated) |
--branch <name> | -b | Git branch (auto-detected if omitted) |
--no-branch | Skip auto-detection of git branch | |
--date <date> | Created date (RFC3339, YYYY-MM-DD, or YYYY-MM-DD HH:MM:SS) |
Basic usage
Terminal
$ deciduous add goal "Add JWT authentication" -c 90
Created node 42 (type: goal) [confidence: 90%] [branch: feature-auth]
$ deciduous add option "jsonwebtoken crate + custom refresh logic" -c 80
Created node 43 (type: option) [confidence: 80%] [branch: feature-auth]
$ deciduous add observation "Redis adds complexity" -d "Adding Redis for token storage introduces operational complexity -- need to manage another service in production."
Created node 44 (type: observation) [branch: feature-auth]
Created node 42 (type: goal) [confidence: 90%] [branch: feature-auth]
$ deciduous add option "jsonwebtoken crate + custom refresh logic" -c 80
Created node 43 (type: option) [confidence: 80%] [branch: feature-auth]
$ deciduous add observation "Redis adds complexity" -d "Adding Redis for token storage introduces operational complexity -- need to manage another service in production."
Created node 44 (type: observation) [branch: feature-auth]
With metadata flags
Terminal
$ deciduous add action "Implement JWT middleware" -c 85 --commit HEAD -f "src/auth/jwt.rs,src/auth/refresh.rs"
Created node 46 (type: action) [confidence: 85%] [commit: a1b2c3d] [branch: feature-auth]
Created node 46 (type: action) [confidence: 85%] [commit: a1b2c3d] [branch: feature-auth]
Multi-line prompts
Capture the full user request with --prompt-stdin:
Terminal
$ deciduous add goal "Add auth" -c 90 --prompt-stdin << 'EOF'
I need to add user authentication to the app. Users should be
able to sign up with email/password, and we need OAuth support
for Google and GitHub. Use JWT tokens with refresh rotation.
EOF
Created node 50 (type: goal) [confidence: 90%] [branch: main]
I need to add user authentication to the app. Users should be
able to sign up with email/password, and we need OAuth support
for Google and GitHub. Use JWT tokens with refresh rotation.
EOF
Created node 50 (type: goal) [confidence: 90%] [branch: main]
Backdating nodes (archaeology)
Terminal
$ deciduous add goal "Original API design" --date "2024-01-15" --no-branch
Created node 51 (type: goal) [date: 2024-01-15]
Created node 51 (type: goal) [date: 2024-01-15]
deciduous link <from> <to>
Add an edge between two nodes.
| Flag | Short | Description |
|---|---|---|
--rationale <text> | -r | Rationale for this connection |
--edge-type <type> | -t | Edge type (default: leads_to) |
Edge types: leads_to, requires, chosen, rejected, blocks, enables
Terminal
$ deciduous link 42 43 -r "possible approach"
Linked 42 -> 43 (leads_to)
$ deciduous link 43 45 -t chosen
Linked 43 -> 45 (chosen)
$ deciduous link 44 45 -t rejected -r "Less control over rotation timing"
Linked 44 -> 45 (rejected)
$ deciduous link 10 11 -t blocks -r "Can't deploy until migration runs"
Linked 10 -> 11 (blocks)
Linked 42 -> 43 (leads_to)
$ deciduous link 43 45 -t chosen
Linked 43 -> 45 (chosen)
$ deciduous link 44 45 -t rejected -r "Less control over rotation timing"
Linked 44 -> 45 (rejected)
$ deciduous link 10 11 -t blocks -r "Can't deploy until migration runs"
Linked 10 -> 11 (blocks)
deciduous unlink <from> <to>
Remove an edge between two nodes.
Terminal
$ deciduous unlink 44 45
Removed edge 44 -> 45
Removed edge 44 -> 45
deciduous delete <id>
Delete a node and all its connected edges.
| Flag | Description |
|---|---|
--dry-run | Show what would be deleted without deleting |
Terminal
$ deciduous delete 44 --dry-run
Would delete node 44: "axum-jwt-auth with built-in rotation" (option)
Would delete edge 42 -> 44 (leads_to)
Would delete edge 44 -> 45 (rejected)
$ deciduous delete 44
Deleted node 44 and 2 connected edges
Would delete node 44: "axum-jwt-auth with built-in rotation" (option)
Would delete edge 42 -> 44 (leads_to)
Would delete edge 44 -> 45 (rejected)
$ deciduous delete 44
Deleted node 44 and 2 connected edges
deciduous status <id> <status>
Update a node’s status.
Valid statuses: pending, active, completed, rejected, superseded, abandoned
Terminal
$ deciduous status 47 completed
Updated node 47 status: active -> completed
$ deciduous status 44 superseded
Updated node 44 status: active -> superseded
Updated node 47 status: active -> completed
$ deciduous status 44 superseded
Updated node 44 status: active -> superseded
deciduous prompt <id> [text]
Update or add a prompt to an existing node. Omit text to read from stdin.
Terminal
$ deciduous prompt 42 "Add JWT auth with refresh token rotation for the API"
Updated prompt for node 42
$ deciduous prompt 50 << 'EOF'
I need authentication with email/password signup,
OAuth for Google and GitHub, and JWT with refresh
token rotation.
EOF
Updated prompt for node 50
Updated prompt for node 42
$ deciduous prompt 50 << 'EOF'
I need authentication with email/password signup,
OAuth for Google and GitHub, and JWT with refresh
token rotation.
EOF
Updated prompt for node 50
deciduous show <id>
Show detailed information about a single node, including its connections, metadata, and prompt.
| Flag | Description |
|---|---|
--json | Output as JSON instead of formatted text |
Terminal
$ deciduous show 42
Node 42: Add JWT authentication
Type: goal
Status: active
Confidence: 90%
Branch: feature-auth
Created: 2025-05-09 14:20:01
Prompt:
Add JWT auth with refresh token rotation for the API
Outgoing edges:
42 -> 43 leads_to "jsonwebtoken crate + custom refresh logic" (option)
42 -> 44 leads_to "axum-jwt-auth with built-in rotation" (option)
Incoming edges:
(none)
Node 42: Add JWT authentication
Type: goal
Status: active
Confidence: 90%
Branch: feature-auth
Created: 2025-05-09 14:20:01
Prompt:
Add JWT auth with refresh token rotation for the API
Outgoing edges:
42 -> 43 leads_to "jsonwebtoken crate + custom refresh logic" (option)
42 -> 44 leads_to "axum-jwt-auth with built-in rotation" (option)
Incoming edges:
(none)
deciduous nodes
List all nodes in the graph. Use filters to narrow results.
| Flag | Short | Description |
|---|---|---|
--branch <name> | -b | Filter by git branch |
--node-type <type> | -t | Filter by node type (goal, decision, action, etc.) |
--theme <name> | Filter by theme name |
Terminal
$ deciduous nodes
42 goal active Add JWT authentication
43 option active jsonwebtoken crate + custom refresh logic
44 option active axum-jwt-auth with built-in rotation
45 decision active Use jsonwebtoken crate for full control
46 action active Implement JWT middleware + refresh endpoint
47 outcome completed JWT auth working -- 14 tests passing
42 goal active Add JWT authentication
43 option active jsonwebtoken crate + custom refresh logic
44 option active axum-jwt-auth with built-in rotation
45 decision active Use jsonwebtoken crate for full control
46 action active Implement JWT middleware + refresh endpoint
47 outcome completed JWT auth working -- 14 tests passing
Filtering by type
Terminal
$ deciduous nodes -t goal
42 goal active Add JWT authentication
50 goal active Add rate limiting
58 goal active Database migration tooling
42 goal active Add JWT authentication
50 goal active Add rate limiting
58 goal active Database migration tooling
Filtering by branch
Terminal
$ deciduous nodes -b feature-auth
42 goal active Add JWT authentication
43 option active jsonwebtoken crate + custom refresh logic
45 decision active Use jsonwebtoken crate for full control
46 action active Implement JWT middleware + refresh endpoint
47 outcome completed JWT auth working -- 14 tests passing
42 goal active Add JWT authentication
43 option active jsonwebtoken crate + custom refresh logic
45 decision active Use jsonwebtoken crate for full control
46 action active Implement JWT middleware + refresh endpoint
47 outcome completed JWT auth working -- 14 tests passing
Filtering by theme
Terminal
$ deciduous nodes --theme performance
55 observation active Redis adds 2ms latency per request
61 decision active Cache tokens in memory instead
55 observation active Redis adds 2ms latency per request
61 decision active Cache tokens in memory instead
deciduous edges
List all edges in the graph.
Terminal
$ deciduous edges
42 -> 43 leads_to "possible approach"
42 -> 44 leads_to "possible approach"
43 -> 45 chosen "more mature, full control"
44 -> 45 rejected "less control over rotation timing"
45 -> 46 leads_to "implementing chosen approach"
46 -> 47 leads_to "implementation result"
42 -> 43 leads_to "possible approach"
42 -> 44 leads_to "possible approach"
43 -> 45 chosen "more mature, full control"
44 -> 45 rejected "less control over rotation timing"
45 -> 46 leads_to "implementing chosen approach"
46 -> 47 leads_to "implementation result"
deciduous graph
Export the full graph as JSON to stdout. Useful for scripting or piping to other tools.
Terminal
$ deciduous graph > graph.json
$ deciduous graph | jq '.nodes | length'
47
$ deciduous graph | jq '.nodes | length'
47
Realistic Example: Full Decision Flow
Here is a complete example showing the canonical flow – goal, options, decision, action, outcome – with all connections:
Terminal -- building a feature end-to-end
# 1. Create the goal
$ deciduous add goal "Add rate limiting to API" -c 90 -p "We need rate limiting on all public endpoints"
Created node 1 (type: goal) [confidence: 90%] [branch: feature-ratelimit]
# 2. Explore options
$ deciduous add option "Token bucket in Redis" -c 80
Created node 2 (type: option) [confidence: 80%]
$ deciduous link 1 2 -r "possible approach"
Linked 1 -> 2 (leads_to)
$ deciduous add option "Sliding window in-memory" -c 75
Created node 3 (type: option) [confidence: 75%]
$ deciduous link 1 3 -r "simpler alternative"
Linked 1 -> 3 (leads_to)
# 3. Make a decision
$ deciduous add decision "Use token bucket in Redis for distributed limiting" -c 85
Created node 4 (type: decision) [confidence: 85%]
$ deciduous link 2 4 -t chosen -r "need distributed state across instances"
Linked 2 -> 4 (chosen)
$ deciduous link 3 4 -t rejected -r "won't work with multiple app servers"
Linked 3 -> 4 (rejected)
# 4. Implement
$ deciduous add action "Implement Redis rate limiter middleware" -c 85 --commit HEAD -f "src/middleware/ratelimit.rs"
Created node 5 (type: action) [confidence: 85%] [commit: f4e5d6a]
$ deciduous link 4 5 -r "implementing chosen approach"
Linked 4 -> 5 (leads_to)
# 5. Record outcome
$ deciduous add outcome "Rate limiting deployed -- 8 tests passing" -c 95
Created node 6 (type: outcome) [confidence: 95%]
$ deciduous link 5 6 -r "implementation result"
Linked 5 -> 6 (leads_to)
$ deciduous status 6 completed
Updated node 6 status: active -> completed
$ deciduous add goal "Add rate limiting to API" -c 90 -p "We need rate limiting on all public endpoints"
Created node 1 (type: goal) [confidence: 90%] [branch: feature-ratelimit]
# 2. Explore options
$ deciduous add option "Token bucket in Redis" -c 80
Created node 2 (type: option) [confidence: 80%]
$ deciduous link 1 2 -r "possible approach"
Linked 1 -> 2 (leads_to)
$ deciduous add option "Sliding window in-memory" -c 75
Created node 3 (type: option) [confidence: 75%]
$ deciduous link 1 3 -r "simpler alternative"
Linked 1 -> 3 (leads_to)
# 3. Make a decision
$ deciduous add decision "Use token bucket in Redis for distributed limiting" -c 85
Created node 4 (type: decision) [confidence: 85%]
$ deciduous link 2 4 -t chosen -r "need distributed state across instances"
Linked 2 -> 4 (chosen)
$ deciduous link 3 4 -t rejected -r "won't work with multiple app servers"
Linked 3 -> 4 (rejected)
# 4. Implement
$ deciduous add action "Implement Redis rate limiter middleware" -c 85 --commit HEAD -f "src/middleware/ratelimit.rs"
Created node 5 (type: action) [confidence: 85%] [commit: f4e5d6a]
$ deciduous link 4 5 -r "implementing chosen approach"
Linked 4 -> 5 (leads_to)
# 5. Record outcome
$ deciduous add outcome "Rate limiting deployed -- 8 tests passing" -c 95
Created node 6 (type: outcome) [confidence: 95%]
$ deciduous link 5 6 -r "implementation result"
Linked 5 -> 6 (leads_to)
$ deciduous status 6 completed
Updated node 6 status: active -> completed