// using astra

Agent modes

Astra runs as a single agent by default, or as an orchestrator that supervises specialized workers — sequentially (boss) or in parallel (multi-agent).

Build and Plan

Mode	Toggle	Behavior
Build (default)	`Tab` / `/build`	Full tool access — edit files, run shell, verify.
Plan	`Tab` / `/plan`	Read-only — explore code, research, write plans to `.astra/plans/*.md`.

The current mode is shown in the prompt footer (Build or Plan).
Plan mode blocks write, edit, bash, verify, database, and MCP; git write actions are denied.
Switch Plan → Build before implementing — the agent gets a reminder to execute the plan.

Boss orchestrator (opt-in)

Boss mode adds a hierarchical orchestrator on top of the normal agent loop. A boss agent plans work, delegates to specialized workers, monitors progress, and synthesizes a final answer. Enable with --boss or /boss. The footer shows BOSS when active.

User → Boss (plan + delegate)
         ├─ explore worker   (read-only research)
         ├─ implement worker (code changes)
         ├─ shell worker     (commands & tests)
         └─ plan worker      (architecture docs)

Worker	Role	Tools
`explore`	Read-only codebase research	read, grep, git, docs, browser
`implement`	Focused code changes	read, write, edit, diff, grep, verify
`shell`	Commands and tests	bash, exec, verify
`plan`	Planning documents	plan, read, grep

The boss only has plan and delegate tools — it never edits files or runs shell commands directly.
Worker activity is streamed in the TUI and logged to ~/.astra/traces/<sessionId>/<runId>.jsonl. Use /trace to find the latest log.
Boss mode uses the model selected in /model; workers run in isolated contexts.

Multi-agent orchestrator (opt-in, parallel)

Multi mode dispatches several specialized agents that run in parallel on the same codebase, each working on disjoint file scopes, then merges the results. Enable with --multi or /multi.

spawn_agents assigns each agent a non-overlapping set of files to avoid edit conflicts.
ask_user lets the coordinating agent pause to interview you for clarifications.
Cap concurrency with multiAgent.maxParallel in settings.json.