The Terminal UI (TUI)
The TUI is a rich, vim-style interface for exploring your decision graph without leaving the terminal.
$ deciduous tui
┌─ Timeline ─────────────────────────┬─ Details ───────────────────────────┐ │ │ │ │ #47 goal Add rate limiting │ goal #47 │ │ #48 decision Choose strategy │ ───────────────────────── │ │ #49 option Redis sliding window│ Add rate limiting to API │ │ #50 option In-memory token │ │ │▸ #51 action Implementing Redis │ Confidence: 90% │ │ #52 outcome Rate limiting working│ Branch: feature/rate-limiting │ │ │ Commit: abc1234 │ │ │ │ │ │ Prompt: │ │ │ "Add rate limiting to the API" │ │ │ │ │ │ Incoming: │ │ │ #48 → here (chosen) │ │ │ Outgoing: │ │ │ → #52 (leads_to) │ └────────────────────────────────────┴─────────────────────────────────────┘ j/k: navigate Enter: detail Tab: DAG view f: filter /: search q: quit
Layout
The TUI has two main areas:
- Left: Timeline list of nodes
- Right: Detail panel for the selected node
Press Enter to toggle the detail panel open/closed.
Navigation
| Key | Action |
|---|---|
| j / k | Move down / up |
| gg | Jump to top |
| G | Jump to bottom |
| Ctrl+d / Ctrl+u | Page down / up |
| Enter | Toggle detail panel |
| Tab | Toggle between Timeline and DAG view |
| q | Quit |
Timeline vs DAG View
The TUI has two main views you can toggle between with Tab:
- Timeline View: Chronological list of all nodes, most recent first
- DAG View: Hierarchical view showing goal chains with their connected decisions, actions, and outcomes
The DAG view is particularly useful for understanding the structure of your decision graph—you can see how goals branch into decisions, which spawn actions and outcomes.
Filtering & Search
| Key | Action |
|---|---|
| / | Search by title |
| f | Cycle through type filters (goal, decision, action...) |
| b | Cycle through branch filters |
| B | Fuzzy branch search |
| R | Toggle sort order (newest/oldest first) |
| Ctrl+c | Clear all filters |
Example: press / then type "auth" to filter nodes:
┌─ Timeline (filtered: "auth") ──────┬─ Details ───────────────────────────┐ │ │ │ │ #1 goal Implement auth │ │ │ #2 decision Choose auth method │ │ │ #12 action Auth middleware │ │ │ │ │ └────────────────────────────────────┴─────────────────────────────────────┘ Search: auth█ (Esc to clear)
File Operations
The TUI can jump directly to files associated with nodes:
| Key | Action |
|---|---|
| o | Open associated files in $EDITOR |
| O | View commit details (if node has linked commit) |
| F | Toggle file browser in detail panel |
| n / N | Next / previous file (when in file browser) |
| p | Preview file with syntax highlighting |
| d | Show file diff with syntax highlighting |
Press o on a node with associated files to open them in your $EDITOR.
The Detail Panel
When you press Enter on a node, the detail panel shows:
- Node type and confidence score (color-coded)
- Full title and description
- User prompt (if captured with
-p) - Associated files
- Linked git commit
- Incoming and outgoing edges with rationales
┌─ Details ──────────────────────────────────────────┐
│ │
│ decision #48 │
│ ──────────────────────────────── │
│ Choose rate limiting strategy │
│ │
│ Confidence: 75% │
│ Branch: feature/rate-limiting │
│ │
│ Incoming: │
│ #47 → here (leads_to) │
│ "Deciding implementation approach" │
│ │
│ Outgoing: │
│ → #49 (leads_to) "Scales across instances" │
│ → #50 (leads_to) "Simpler, single-instance" │
│ → #51 (chosen) "Redis already in stack" │
│ │
└────────────────────────────────────────────────────┘
Other Commands
| Key | Action |
|---|---|
| s | Show goal story (hierarchy from root) |
| r | Refresh graph from database |
| ? | Show help |
Auto-Refresh
The TUI watches the database file and auto-refreshes when it changes. If you add nodes in another terminal, they'll appear automatically.
Specifying Database Path
By default, the TUI auto-discovers the database. To specify a different path:
$ deciduous tui -d /path/to/.deciduous/deciduous.db