Per-role agents

Tallpine has two session roles:

• A worker implements a focused task in an isolated workspace and may own pull requests.
• An orchestrator supervises a project, monitors sessions, and delegates implementation to workers.

Tallpine can also run a dedicated reviewer against a worker's pull request. Reviewers run separately from worker and orchestrator sessions. See the review loop to choose a reviewer, start a run, and send findings to the worker.

Role and interface are separate choices. Either role can start in structured Chat or Terminal UI when its harness supports that interface.

Configure roles

Open Project Settings in the desktop app and choose a coding agent for each role. The CLI can set these agents while registering a project:

tallpine project add --path /absolute/path/to/repo \
  --worker-agent codex \
  --orchestrator-agent claude-code

For a full configuration replacement, the stored JSON shape is:

{
  "worker": {
    "agent": "codex",
    "agentConfig": {
      "model": "gpt-5.4",
      "permissions": "bypass-permissions"
    }
  },
  "orchestrator": {
    "agent": "claude-code",
    "agentConfig": {
      "model": "claude-opus-4"
    }
  }
}

This example uses bypass-permissions, which lets provider tools act without their normal approval prompts. Use it only when intended; available permission modes depend on the provider.

The --config-json flag takes a JSON string, not a file, and --config-json replaces the whole project configuration (focused flags such as --worker-agent merge instead). Preserve existing setup, rules, reviewers, and intake settings. See Projects: update from the CLI for CLI limitations and safer alternatives.

Choose which models a harness offers

Open Settings → Harnesses, choose a harness, and open Models. Turn a model's switch off to hide it from the model pickers for new tasks, project settings, reviewers, agent switching, and chat. Enable all and Disable all change every listed model at once; at least one model stays on. With every model on, the pickers offer the harness's full catalog, including models it reports later.

The choice belongs to the selected computer. A model a project, task, or session already uses stays listed even when it is switched off. Cloud VM tasks use their own catalog.

The Models tab also shows each model's context window in tokens when the harness catalog reports it.

Start an orchestrator or worker

The desktop provides dedicated new-session and orchestrator flows. From the CLI:

tallpine spawn --project my-project --kind orchestrator \
  --name supervisor --mode chat

tallpine spawn --project my-project --kind worker \
  --name issue-42 --issue 42 --mode tui

--name is required and limited to 100 characters. Use --harness to choose a different agent for one spawn.

Choose Chat or Terminal UI

• Use Chat for structured messages, provider activity, approvals, plans, changed files, usage, compaction, and rollback. Chat support depends on the harness and installed version; see the agent capability catalog.
• Use Terminal UI when you want the agent's native interface or a harness without native Chat support.

Compatible Claude Code and Codex sessions expose Switch to chat UI or Switch to terminal UI. Idle sessions switch directly. When work is active, Tallpine asks whether to finish and drain it or stop and interrupt it before switching controllers.

The default interface comes from Settings → General. Project agentConfig.mode does not set Chat or Terminal UI. A choice made for a task or with the CLI takes precedence.

Model, reasoning effort, permissions, and provider execution modes depend on the selected agent. Chat support and the ability to switch interfaces are separate capabilities, so use the switch action offered for that session.

Switch agents mid-session

A local session can move to a different agent without losing its conversation. The new agent starts with a handoff of the session so far and keeps working in the same worktree.

• Chat: open the agent, model, and reasoning effort picker in the composer, choose Agent, and pick another agent and its model. The switch happens when you send your next message.
• Terminal UI: open Session actions (the … button on the session tab), choose Agent, pick the agent and model, then click Switch.

Only agents that are installed and ready on that computer are offered, and Chat offers only agents with Chat support. Switch while the agent is idle; Tallpine refuses a switch while the agent is working or waiting on an approval or question. Cloud sessions cannot switch agents.

Project rules

Use agentRules and agentRulesFile for worker instructions. Use orchestratorRules for supervision-specific guidance. These are stored in the typed project config and injected into the appropriate session role.