TUI Guide
The claustre dashboard is a terminal UI built with ratatui. It shows a project sidebar, task queue, and embedded terminal sessions.
Dashboard Layout
The dashboard is split into two panels with usage bars at the bottom:
| Area | Content |
|---|---|
| Left sidebar | Projects with task counts and status icons |
| Right panel | Task queue (pending / working / in_review) |
| Usage bars | 5h and 7d rate limit window utilization |
The left sidebar lists all registered projects. Each project entry shows counts of tasks by status so you can see at a glance how many tasks are pending, in progress, or awaiting review. Selecting a project updates the right panel to show that project's task queue with real-time status updates driven by the Stop hook and SQLite polling.
The right panel displays the task queue for the currently selected project.
Tasks are shown in their sort_order with status indicators,
mode badges, and PR links. Only active tasks (pending, working, in_review,
interrupted) appear in the Active view. Completed tasks move to the History
view.
Session Tabs
When you launch a task (press l), a new tab appears with
embedded terminal panes. The default layout is a shell pane on the left
alongside a Claude pane on the right. You can:
- Split panes horizontally or vertically to add more shells
- Navigate between panes with keyboard shortcuts
- Close extra shell panes when you no longer need them
- Switch between the dashboard tab and session tabs
Tab navigation uses Ctrl+K (previous tab) and
Ctrl+J (next tab). Press Ctrl+D to detach from a
session tab and return to the dashboard.
Keybindings
Dashboard (Normal Mode)
| Key | Action |
|---|---|
q | Quit |
Ctrl+C | Quit |
Ctrl+P | Open command palette |
Ctrl+K | Previous tab |
Ctrl+J | Next tab |
1 / h | Focus Projects panel |
2 / l | Focus Tasks panel |
? | Show help overlay |
/ | Filter tasks |
j / Down | Move down |
k / Up | Move up |
J / K | Reorder tasks (move down / up) |
Enter | Go to session tab (tasks) / refresh (projects) |
Task Actions
| Key | Action |
|---|---|
n | Create new task (floating panel) |
e | Edit task (pending/draft tasks only) |
l | Launch pending task (auto-creates session) |
s | Open subtask panel for selected task |
r | Mark task as done (working / in_review / interrupted) |
k | Kill session (tears down session, resets task to pending) |
o | Open PR in browser (tasks with a PR URL) |
d | Delete (with confirmation) |
Other Actions
| Key | Action |
|---|---|
a | Add project |
i | Open skills panel |
Session Tab Keybindings
When viewing a session tab, keystrokes are forwarded to the focused PTY pane. The following control sequences are intercepted by claustre:
| Key | Action |
|---|---|
Ctrl+H | Focus previous pane |
Ctrl+L | Focus next pane |
Ctrl+B | Split right (new shell beside focused) |
Ctrl+N | Split down (new shell below focused) |
Ctrl+W | Close focused pane |
Ctrl+D | Detach (back to dashboard) |
Skills Panel
Press i from the dashboard to open the skills panel. From
there, the following keys are available:
| Key | Action |
|---|---|
f | Find / search skills |
a | Add skill (manual package input) |
x | Remove selected skill |
u | Update all skills |
g | Toggle scope (global / project) |
Usage Bars
The bottom of the dashboard displays two usage bars that visualize your
current Anthropic API rate limit consumption. The TUI polls the Anthropic
OAuth API in a background thread and caches the results in
~/.claude/statusline-cache.json.
The two bars represent the 5-hour window and the 7-day window utilization. Each bar is color-coded based on the current usage percentage:
| Color | Threshold |
|---|---|
| Green | < 70% usage |
| Yellow | 70% – 90% usage |
| Red | > 90% usage |
When a rate limit is hit, autonomous task feeding pauses globally across all sessions. A rate limit banner appears in the dashboard showing when the limit expires. Once the limit window resets, feeding automatically resumes and the banner disappears.
Status Indicators
Tasks in the queue display a status symbol to the left of their title:
| Symbol | Meaning |
|---|---|
| • | Working — Claude is actively coding |
| ◔ | In review — PR opened, waiting for review |
| ✓ | Done — task complete |
| ✗ | Error — something went wrong |
Paused Detection
In addition to the database-driven statuses above, the TUI performs real-time detection of Claude Code's permission prompts. On every tick, each session's PTY screen is scanned for the tool approval pattern (e.g., "Allow <ToolName>" with yes/no options). When this pattern is detected and the session has a working task, the displayed status is overridden to paused (⏸, yellow).
This override is purely in-memory — the database still shows
working. The paused indicator clears automatically as soon as
the PTY screen no longer contains the permission prompt, for example after
the user approves the action.