The /taskplane-settings command opens an interactive TUI for viewing and editing
all Taskplane configuration. This page documents every available setting.
Tip: You don't need to memorize this page. The TUI shows descriptions inline when you highlight each setting. Use this as a deeper reference for understanding what each setting does and when to change it.
Settings are organized into sections that match the TUI navigation. Taskplane resolves effective values using layered precedence:
- Schema defaults (internal)
- Global preferences (
~/.pi/agent/taskplane/preferences.json) - Project overrides (
.pi/taskplane-config.json)
The settings TUI writes to two user-visible layers:
| Layer | Stored in | Shared? | Typical use |
|---|---|---|---|
| Global preferences | ~/.pi/agent/taskplane/preferences.json |
❌ Personal | Your baseline defaults across all projects |
| Project overrides | .pi/taskplane-config.json |
✅ Team-wide | Project-specific exceptions to your global baseline |
When editing a setting:
- The default save target is Global preferences.
- You can explicitly choose Save to project override when needed.
- If a project override already exists, you can choose Remove project override to fall back to global preferences.
Source indicators in the TUI show where each value comes from:
(project)— set in project config(global)— inherited from your global preferences (or internal defaults if no explicit global value exists)
Settings that control how /orch runs parallel task batches.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Max Lanes | number | 3 |
Any positive integer | Maximum parallel execution lanes (worktrees). Each lane runs one task at a time. More lanes = more parallelism but more disk/memory usage. |
| Worktree Location | enum | subdirectory |
subdirectory, sibling |
Where lane worktree directories are created. subdirectory = .worktrees/{prefix}-{N} inside the repo. sibling = ../{prefix}-{N} next to the repo (useful when the project root isn't a git repo, e.g., polyrepo workspaces). |
| Worktree Prefix | string | taskplane-wt |
Any string | Prefix for worktree directory names. Combined with operator ID and lane number: {prefix}-{opId}-{N}. |
| Batch ID Format | enum | timestamp |
timestamp, sequential |
Format for batch identifiers used in branch names and logs. timestamp = 20260317T140000. sequential = incrementing number. |
| Tmux Prefix | string | orch |
Any string | Prefix for orchestrator tmux session names. Sessions are named {prefix}-{opId}-lane-{N}. Change if you run multiple taskplane instances and need distinct session names. (L1+L2) |
| Operator ID | string | (auto-detect) | Any string | Identifier for this operator. Auto-detected from OS username if empty. Used in session names, worktree paths, and branch names for collision resistance when multiple people run batches on the same repo. (L1+L2) |
| Integration | enum | manual |
manual, supervised, auto |
How completed batches are integrated into your working branch. manual = you run /orch-integrate after the batch completes (gives you full control over timing and integration mode). supervised = the supervisor proposes an integration plan, asks for your confirmation, then executes it. auto = the supervisor executes integration automatically without asking, pausing only if issues arise (conflicts, CI failures). Both supervised and auto detect branch protection and default to PR mode when the target branch is protected. See /orch-integrate for details on the manual integration flow. |
Settings that control how task dependencies are discovered for wave scheduling.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Dep Source | enum | prompt |
prompt, agent |
How dependencies are extracted. prompt = parsed from the ## Dependencies section of PROMPT.md. agent = an AI agent analyzes tasks for implicit dependencies. |
| Dep Cache | boolean | true |
true, false |
Cache dependency analysis results between runs. Speeds up repeated /orch calls on the same task set. Disable if tasks change frequently between runs. |
Settings that control how tasks are distributed across lanes.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Strategy | enum | affinity-first |
affinity-first, round-robin, load-balanced |
How tasks within a wave are assigned to lanes. affinity-first = tasks with overlapping file scope go to the same lane (reduces merge conflicts). round-robin = even distribution. load-balanced = assigns based on task size weights. |
Note: Size weights (
S:1,M:2,L:4) are used by the load-balanced strategy but are not editable in the TUI. Edit them in.pi/taskplane-config.jsondirectly.
Settings for pre-warming lane worktrees before task execution.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Auto-Detect | boolean | false |
true, false |
Automatically detect pre-warm commands from project config (e.g., npm install). When enabled, the orchestrator runs setup commands in each worktree before task execution. |
Note: Named pre-warm commands and the
alwayslist are not editable in the TUI. Configure them in.pi/taskplane-config.jsonunderorchestrator.preWarm.
Settings that control how completed lanes are merged back into the base branch.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Merge Model | string | (inherit) | Any model ID | Model for the merge agent. Empty = inherits the active session's model. Set explicitly if you want a specific model for merges (e.g., a faster model for simple merges). (L1+L2) |
| Merge Tools | string | read,write,edit,bash,grep,find,ls |
Comma-separated tool names | Tools available to the merge agent. Restrict if you want to limit what the merge agent can do. |
| Merge Thinking | picker | (inherit) | inherit (use session thinking), off, minimal, low, medium, high, xhigh |
Thinking mode for merge agent. inherit uses active session default; level values force an explicit mode. Legacy on is normalized to high. (L1+L2) |
| Merge Order | enum | fewest-files-first |
fewest-files-first, sequential |
Order in which completed lanes are merged. fewest-files-first = lanes with fewer changed files merge first (reduces conflict complexity). sequential = merge in lane number order. |
| Merge Timeout (minutes) | number | 10 |
Any positive number | Maximum time for the merge agent to complete. If exceeded, the merge session is killed and the batch pauses. Increase for large batches with many files (e.g., 15-20 min for 50+ file diffs). |
Note: Verification commands (
merge.verify) are not editable in the TUI. Configure them in.pi/taskplane-config.jsonunderorchestrator.merge.verify.
Settings that control what happens when things go wrong during a batch.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| On Task Failure | enum | skip-dependents |
skip-dependents, stop-wave, stop-all |
What happens when a task fails. skip-dependents = skip tasks that depend on the failed task, continue others. stop-wave = stop the current wave, skip remaining waves. stop-all = immediately stop everything. |
| On Merge Failure | enum | pause |
pause, abort |
What happens when a merge fails. pause = pause the batch so you can inspect and resume. abort = terminate the batch entirely. |
| Stall Timeout (min) | number | 30 |
Any positive number | Minutes of no progress before a task is considered stalled. The monitor checks STATUS.md for changes — if no checkboxes are checked for this duration, the task is killed. |
| Max Worker Min | number | 30 |
Any positive number | Maximum wall-clock minutes a worker can run per task in orchestrated mode. Prevents runaway tasks from blocking the batch indefinitely. |
| Abort Grace (sec) | number | 60 |
Any positive number | Seconds to wait after sending an abort signal before force-killing a session. Gives workers time to commit their current work. |
Settings for the orchestrator's monitoring loop.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Poll Interval (sec) | number | 5 |
Any positive number | How often (in seconds) the orchestrator checks lane/task status. Lower = more responsive dashboard updates but more filesystem reads. Higher = less overhead. |
Settings for the supervisor agent that monitors batches and handles failures.
The supervisor activates automatically when /orch starts a batch. It shares the operator's pi session, monitoring engine events and providing proactive status updates.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Supervisor Model | string | (inherit) | Any model ID | Model for the supervisor agent. Empty = inherits the active session's model. Set explicitly if you want a different model for supervision (e.g., a model with stronger reasoning for failure recovery). (L1+L2) |
| Autonomy Level | enum | supervised |
interactive, supervised, autonomous |
Controls how much the supervisor does automatically vs. asking the operator. interactive = ask before any recovery action. supervised = known recovery patterns auto, novel recovery asks. autonomous = handle everything, pause only when stuck. |
| Classification | Interactive | Supervised | Autonomous |
|---|---|---|---|
| Diagnostic (reading state, running tests) | ✅ Auto | ✅ Auto | ✅ Auto |
| Tier 0 Known (session restart, worktree cleanup, merge retry) | ❓ Ask | ✅ Auto | ✅ Auto |
| Destructive (state edits, git operations, session kills) | ❓ Ask | ❓ Ask | ✅ Auto |
In all modes, the supervisor logs every recovery action to .pi/supervisor/actions.jsonl for audit trail purposes.
Settings that control how /task spawns and manages worker agents.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Worker Model | string | (inherit) | Any model ID | Model for worker agents. Empty = inherits the active session's model. Format: provider/model-id (e.g., anthropic/claude-sonnet-4-20250514). (L1+L2) |
| Worker Tools | string | read,write,edit,bash,grep,find,ls |
Comma-separated tool names | User-facing tools available to worker agents. The default set covers all standard operations. Engine-internal coordination tools (review_step, notify_supervisor, escalate_to_supervisor, request_segment_expansion) are always appended automatically and cannot be disabled via this config — they are required for plan/code/test reviews, supervisor steering replies, blocker escalation, and multi-repo segment expansion to work. See issue #530 for context. |
| Worker Thinking | picker | (inherit) | inherit (use session thinking), off, minimal, low, medium, high, xhigh |
Thinking mode for workers. inherit uses active session default; level values force an explicit mode. Legacy on is normalized to high. |
| Spawn Mode | enum | subprocess |
subprocess |
Runtime mode for /task worker/reviewer subprocesses. Runtime V2 supports subprocess only. |
Tip: When you change Worker/Reviewer/Merge model to one that advertises thinking capability, the TUI suggests setting the corresponding Thinking picker to
high.If a model reports
thinking=no, Taskplane still lets you set any thinking level and shows an informational note. Unsupported models ignore the setting at runtime.
Settings that control reviewer agents (cross-model review).
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Reviewer Model | string | (inherit) | Any model ID | Model for reviewer agents. Empty = inherits session model. Best practice: use a different model than the worker for independent review (e.g., worker on Claude, reviewer on GPT). (L1+L2) |
| Reviewer Tools | string | read,write,bash,grep,find,ls |
Comma-separated tool names | Tools available to reviewer agents. Note: reviewers don't get edit by default — they review but don't modify code. |
| Reviewer Thinking | picker | high |
inherit (use session thinking), off, minimal, low, medium, high, xhigh |
Thinking mode for reviewers. inherit uses active session default; level values force an explicit mode. Legacy on is normalized to high. |
Settings that control worker iteration limits and context window management.
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Context Window | number | 200000 |
Any positive number | Worker context window size in tokens. Workers track their context usage against this limit. When usage exceeds the kill threshold, the iteration is terminated to prevent context overflow. |
| Warn % | number | 70 |
1-100 | Context utilization percentage that triggers a warning. The worker is notified it's approaching the limit and should wrap up soon. |
| Kill % | number | 85 |
1-100 | Context utilization percentage that force-terminates the worker iteration. The worker's current work is lost for that iteration, but STATUS.md checkpoints are preserved. |
| Max Iterations | number | 20 |
Any positive number | Maximum worker iterations per step. Each iteration is a fresh-context agent invocation. If the worker hasn't completed the step after this many iterations, execution stops. |
| Max Review Cycles | number | 2 |
Any positive number | Maximum REVISE loops per review stage. If the reviewer keeps returning REVISE after this many cycles, the task moves forward anyway. Prevents infinite review loops. |
| No Progress Limit | number | 3 |
Any positive number | Maximum consecutive iterations with no checkbox progress before the task is marked as stalled. Prevents workers from spinning without making progress. |
| Max Worker Min (ctx) | number | (not set) | Any positive number or empty | Per-worker wall-clock cap in minutes. Unlike the orchestrator's Max Worker Min (which applies per-task in /orch), this applies per-worker-iteration. Empty = no cap. |
Personal baseline settings that affect your local environment across projects.
On first use, taskplane init bootstraps ~/.pi/agent/taskplane/preferences.json if it is missing/empty/corrupt. The bootstrap seeds:
initAgentDefaults.workerThinking = "high"initAgentDefaults.reviewerThinking = "high"initAgentDefaults.mergeThinking = "high"
During first interactive init, Taskplane also saves your chosen worker/reviewer/merger model+thinking defaults globally. If pi --list-models reports 2+ providers, init recommends selecting reviewer/merger from a different provider than worker (cross-provider review guidance).
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Dashboard Port | number | (not set) | Any valid port number | Port for taskplane dashboard. Default is 8099 if not set. Change if that port is in use on your machine. |
The TUI's Advanced section shows fields that exist in the config schema but aren't directly editable through the TUI — typically collections, arrays, and record types. These include:
| Field | Type | Description |
|---|---|---|
taskRunner.taskAreas |
Record | Task area definitions (paths, prefixes, CONTEXT.md) |
taskRunner.referenceDocs |
Record | Named reference documents available to tasks |
taskRunner.standards |
Object | Project coding standards (docs, rules) |
taskRunner.testing |
Object | Test commands (testing.commands.test, etc.) |
taskRunner.neverLoad |
Array | Docs excluded from task execution context |
taskRunner.selfDocTargets |
Record | Where agents log discoveries |
taskRunner.protectedDocs |
Array | Docs requiring user approval to modify |
orchestrator.preWarm.commands |
Record | Named pre-warm commands |
orchestrator.preWarm.always |
Array | Commands always run before wave execution |
orchestrator.assignment.sizeWeights |
Record | Size weights for load-balanced assignment |
orchestrator.merge.verify |
Array | Post-merge verification commands |
To edit these, modify .pi/taskplane-config.json directly.
- Commands Reference —
/taskplane-settingscommand syntax - task-runner.yaml Reference — legacy YAML format (still supported)
- task-orchestrator.yaml Reference — legacy YAML format (still supported)