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. Tasks are configured with a prompt, a mode, delivery settings, and optional subtasks.

Creating a Task

From the TUI

Press n to open the task creation form. The form has seven fields, navigated with Tab:

Press Enter to create the task (status: pending). Press Esc to save as draft for later editing.

From the CLI

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

The CLI supports -d (description/prompt) and -m (mode). Other parameters (base, branch, push mode, review loop, subtasks) are only configurable from the TUI form.

Task Modes

Supervised (default)

• Claustre launches claude '<prompt>' directly in an embedded PTY
• The user drives the interaction — Claude responds, you review and guide
• One task at a time per session
• If the task has subtasks, Claude receives the first pending subtask's description as the prompt

Autonomous

• 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 in the same project
• Claude works through tasks sequentially without user intervention
• The prompt includes an autonomous suffix instructing Claude not to ask questions and to make its best judgment
• Rate limits are checked before starting each task

Exploration

• Launches claude interactively with no prompt
• Intended for open-ended research and investigation — no specific deliverable required
• The user interacts freely with Claude in the embedded terminal

Base and Branch

Base and Branch are independent parameters that control different aspects of the git workflow:

When to set Base: Use this for hotfix or release workflows where you need to branch from and PR against a non-default branch. For example, setting base to release/v2.0 creates the worktree from that release branch and tells Claude to target it for the PR.

When to set Branch: Use this to continue work on an existing branch or to use a specific naming convention. When left empty, claustre generates a branch name like task/add-user-auth-a1b2c3d4.

Example: A hotfix targeting a release branch:

• Base: release/v2.0 — worktree starts from this branch, PR targets it
• Branch: fix/urgent-bug — the new branch name
• Result: git worktree add -b fix/urgent-bug <path> origin/release/v2.0

Push Mode

Push mode controls how Claude delivers completed work:

Review Loop

When the Loop toggle is set to on, claustre automatically monitors and implements PR review comments after the task transitions to in_review:

1. A claustre review-loop process spawns in a new pane in the session tab
2. It polls the PR for new review comments at a configurable interval (default: 120s)
3. Claude evaluates each comment adversarially — accepting bug fixes, logic errors, security issues, and missing edge cases while rejecting nitpicks and style preferences
4. Implements accepted changes, commits, and pushes
5. Prints a summary table of accepted/rejected comments
6. Repeats until the task is marked done or rate limits are hit

Review Loop Configuration

Customize the review loop in ~/.claustre/config.toml:

[review_loop]
poll_interval_secs = 60       # default: 120
# prompt = "Custom prompt"    # replaces the built-in review prompt

Subtasks

Tasks can be broken into ordered subtasks. Subtasks let you structure complex work into discrete steps that Claude works through sequentially.

Managing Subtasks

Subtasks can be added during task creation (field 7 in the form) or managed later by pressing s on a selected task:

How Subtasks Affect Prompts

In autonomous mode, feed-next includes all subtasks as an ordered list in a single prompt:

# Task Title

Task description here...

## Steps

1. **Subtask 1 title**: Subtask 1 description
2. **Subtask 2 title**: Subtask 2 description
3. **Subtask 3 title**: Subtask 3 description

[autonomous instructions + completion instructions]

Claude works through all steps in a single session.

In supervised mode, claustre launches Claude with the first pending subtask's description. The user works through subtasks one at a time.

Task Status Lifecycle

draft ──[edit]──> pending ──[launch]──> working ──[PR detected]──> in_review ──[PR merged]──> done
                                          ↑↓            │              │
                                     interrupted       conflict / ci_failed
                                          ↑             │
                                          └──[user resumes]──┘

Task Completion Flow

PR mode (default)

1. Claude commits all changes and pushes the branch
2. Claude creates a pull request against the base branch using gh pr create
3. The Stop hook detects the PR and calls claustre session-update --pr-url <URL>
4. Claustre transitions the task to in_review and sends a notification
5. If review loop is enabled, a claustre review-loop process spawns to handle review comments
6. For autonomous tasks, feed-next auto-queues the next pending task

Push mode

1. Claude commits all changes and pushes the branch
2. feed-next detects that Claude has finished and marks the task done immediately
3. No PR is created and no review phase occurs

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

1. Setup — Install claustre, run claustre init, optionally add a global CLAUDE.md
2. Register a project — claustre add-project my-app /path/to/my-app or press a in the TUI
3. Launch dashboard — claustre
4. Create tasks — Press n, fill in the prompt, set the mode, and configure base/branch/push/loop as needed
5. Launch — Focus the task queue, select a pending task, press l
6. Monitor — The dashboard shows real-time status with indicators
7. Review — When a PR opens, press o to view it in the browser, r to mark the task done
8. Rate limits — The TUI pauses autonomous tasks when limits are hit and auto-resumes when the window clears
9. Kill / teardown — Press k to kill and reset a task, d to delete it
10. 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

Hotfix Workflow Example

# In the TUI, press 'n' to create a task:
#   Prompt: "Fix the null pointer in UserService.get()"
#   Mode:   autonomous
#   Base:   release/v2.0     ← PR targets the release branch
#   Branch: fix/null-pointer  ← specific branch name
#   Push:   pr
#   Loop:   on                ← auto-implement review comments