Modes

The Cosine CLI operates in one of four modes that control how the AI agent behaves — specifically, how it handles tool execution, code changes, and task delegation. The active mode is always visible in the footer bar at the bottom of the TUI.

Switching Modes

Press Shift+Tab to cycle through modes in this order:

Normal → Auto → Plan → Swarm → Normal

You can also switch modes through the commands menu by pressing / or Ctrl+P and selecting Change Mode.

Mode Overview

Mode	Icon	Color	Behavior
Normal	◆	Gray	Asks for confirmation before mutating actions
Auto	●	Green	Executes all actions without confirmation
Plan	○	Purple	Read-only planning — no file modifications
Swarm	◈	Blue	Multi-agent orchestration with subagents

Normal Mode

Normal mode is the default when you start a session. The agent can read files, search your codebase, and run analysis freely, but will ask for your explicit approval before performing any action that modifies your project.

What requires confirmation

Code edits and file creation
File deletion and renaming
Terminal commands
MCP tool calls

What runs automatically

Reading files
Searching and navigating the codebase
LSP operations (go-to-definition, find references)
Web searches and URL fetching

Normal mode is a good default for most workflows. You stay in control of every change while still getting the speed of automated read-only operations.

Auto Mode

In Auto mode, the agent executes all tool calls — including code edits, terminal commands, and file operations — without asking for confirmation.

This is useful when you trust the agent’s judgment and want it to work through a task end-to-end without interruption. It is particularly effective after reviewing a plan (see Plan Mode below), since you already know what changes the agent intends to make.

When to use Auto mode

Implementing well-defined features or bug fixes
After approving a plan
Running through repetitive changes across multiple files
When you want to watch the agent work without pausing

Staying safe in Auto mode

You can press Ctrl+C at any time to interrupt the agent mid-run. You can also review all changes in the Changes panel (Ctrl+4 / Alt+4) and undo them with git.

Plan Mode

Plan mode puts the agent into a read-only state. It can explore your codebase and ask you questions, but it cannot create, modify, or delete any files. Instead, it produces a structured implementation plan saved to disk.

How planning works

Switch to Plan mode with Shift+Tab or have the agent enter it automatically when it decides planning would help.
Describe what you want to build or fix.
The agent explores relevant code, may ask clarifying questions, and writes a step-by-step plan.
When the plan is ready, you are presented with options for how to proceed.

Plan approval options

Once the agent finishes the plan, a confirmation dialog appears with these choices:

Option	What it does
Yes, clear context and auto-accept edits	Clears the conversation history, keeps the plan, and switches to Auto mode for implementation
Yes, auto-accept edits	Keeps the full conversation and switches to Auto mode
Yes, manually approve edits	Keeps the conversation and switches to Normal mode so you approve each change
Yes, accept and enable Swarm mode	Hands the plan to a swarm of subagents for parallel execution
Type feedback	Provide feedback on the plan so the agent can revise it
Reject, and exit plan mode	Discards the plan and returns to the previous mode

When to use Plan mode

Large or ambiguous features where you want to align on approach before writing code
Exploring trade-offs between different implementation strategies
When you want a written record of the intended changes before they happen

Swarm Mode

Swarm mode enables multi-agent orchestration. The primary agent acts as an orchestrator that can delegate work to subagents running in parallel, each working on a portion of the task.

Starting a Swarm session

When you first send a prompt in Swarm mode, a confirmation dialog asks how you want the swarm to run:

Option	Description
Run in foreground (shared filesystem)	Subagents share the current workspace and you can watch them work in real time
Run in background (uses worktree)	Creates a git worktree on a new branch, clears the primary timeline, and runs the task in the background

How it works

The orchestrator reads your prompt and decides how to split the work across subagents.
Subagents can run synchronously (one at a time) or in parallel depending on whether their tasks are independent.
Each subagent has access to the full set of tools (code editing, terminal, search, etc.).
Progress is visible in the Agents panel (Ctrl+3 / Alt+3).

When to use Swarm mode

Large tasks that naturally decompose into independent subtasks
Refactors that span many files or modules
Research-heavy tasks where multiple areas need to be explored simultaneously

CLI Flags for Modes

You can also set mode-related behavior at startup:

Flag	Effect
`--auto-accept`	Start the session in Auto mode, bypassing all confirmations
`--auto-accept-plans`	Automatically approve plan mode transitions without a confirmation dialog