Tasks

Tasks are the core unit of work in claustre. Each task represents a piece of work that Claude will execute in an isolated session.

Task Modes

Supervised mode (default)

claustre launches claude '<prompt>' directly in an embedded PTY
The user drives the interaction
One task at a time

Autonomous mode

claustre launches claustre feed-next --session-id X in an embedded PTY
feed-next runs Claude as a blocking subprocess, then loops to chain the next pending autonomous task
Claude works through tasks sequentially without user intervention
Rate limits are checked before starting each task

Task Status Lifecycle

pending ──[launch]──> working ──[PR detected]──> in_review ──[PR merged]──> done
                         ↑                            │
                         └───[user resumes]───────────┘

Transition	Trigger	Where
pending → working	User presses `l` (launch), or `feed-next` picks up next task	`session::create_session()`, `main::run_feed_next()`
working → in_review	Stop hook detects a PR via `gh pr view`	`main.rs` SessionUpdate handler
in_review → working	UserPromptSubmit hook detects user activity	`main.rs` SessionUpdate handler
in_review → done	PR merge poller detects merge (auto), or user presses `r` (manual)	`tui/app.rs`
working → error	External/manual (no automatic trigger yet)	—

Creating Tasks

From the TUI

Press n to open the task creation panel:

Title — Short description (e.g., "Add user authentication")
Description — Full prompt that Claude will receive
Mode — supervised or autonomous
Use Tab to cycle fields, Enter to create, Esc to cancel

From the CLI

claustre add-task my-app "Add login endpoint" \
  -d "Create a POST /login endpoint with JWT auth" \
  -m autonomous

Subtasks

Tasks can be broken into ordered subtasks. When a task has subtasks, feed-next builds a prompt that includes all subtasks as an ordered list. Claude works through them sequentially in a single session.

Managing subtasks in the TUI: press s on a selected task to open the subtask panel.

Task Completion Flow

Claude commits all changes and pushes the branch
Claude creates a pull request against main using gh pr create
The Stop hook detects the PR and calls claustre session-update --pr-url <URL>
Claustre transitions the task to in_review and sends a notification
For autonomous tasks, feed-next auto-queues the next pending task

PR Merge Auto-Completion

Every 15 seconds, the TUI checks all in_review tasks with a pr_url. When a merge is detected via gh pr view, the session is torn down and the task marked done.

End-to-End Usage Guide

Setup — Install claustre, run claustre init, optionally add a global CLAUDE.md
Register a project — claustre add-project my-app /path/to/my-app or press a in the TUI
Launch dashboard — claustre
Create tasks — Press n in the TUI, fill in title, description, and mode
Launch — Focus the task queue, select a pending task, press l
Monitor — The dashboard shows real-time status with indicators
Review — When a PR opens, press o to view it in the browser, r to mark the task done
Rate limits — The TUI pauses autonomous tasks when limits are hit and auto-resumes when the window clears
Kill / teardown — Press k to kill and reset a task, d to delete it
History and stats — claustre stats <project> or claustre export <project>

Autonomous Workflow Example

# Add a batch of autonomous tasks
claustre add-task my-app "Add user model" -d "Create User struct with..." -m autonomous
claustre add-task my-app "Add auth middleware" -d "Create JWT middleware..." -m autonomous
claustre add-task my-app "Add login endpoint" -d "Create POST /login..." -m autonomous

# Launch the first task from the TUI (press 'l')
# Claude will work through them sequentially, opening a PR for each
# You get a notification when each completes
# Press 'o' to review each PR, then 'r' to mark done