Agents

Agents are Claude Code sessions managed by ClaudeControl. Each agent has a role, a chat history, and configurable settings.

Spawning Agents

From the Sidebar

• Novo chat — spawns a generic chat agent
• Iniciar agentes — auto-discovers the project and creates specialist agents
• Role buttons — spawn a specific role (e.g., Arquiteto, Dev, QA)

Role Detection

ClaudeControl detects roles from .claude/commands/*.md files in your project directory. Each .md file becomes an available role. The first line of the file is used as the role description.

Agent Configuration

Each agent has settings that persist across page reloads:

Setting	Description
Model	Claude model (Haiku, Sonnet, Opus)
Effort	Response effort level (Low, Med, High)
Bypass	Skip tool permission prompts
Clean Mode	Show only user/agent messages, hide tool calls
Orchestrator	Can delegate tasks to other agents
Subagents	Can use the Agent tool to spawn sub-agents

All settings are saved to the backend via PATCH /api/agents/:id and survive F5 reload.

Agent Naming

• Default: role name capitalized (e.g., "Arquiteto")
• Description: first line of the .claude/commands/{role}.md file
• Custom name: double-click the name in the chat header to rename inline

Agent Lifecycle

Created → Working → Idle → (message) → Working → Idle → ...
                                    ↘ (stop) → Idle
                                    ↘ (error) → Error
                                    ↘ (session lost) → Recovery → Working

Stop

Click the stop button (always visible) to interrupt the agent. Multiple clicks are safe. The agent can receive new messages after stopping.

Delete

Removes the agent from the active list and moves it to history.

Reopen

Restore an agent from the history section in the sidebar.

Compact

Trigger SDK native context compaction. The agent compresses its conversation context using the model, preserving critical information without losing context.

Cost Tracking

Each agent tracks:

• Total cost in USD
• Total turns (conversation rounds)
• Input/output tokens

Cost appears in the chat header and the Settings → Cost dashboard.

Budget Auto-Stop

If maxBudgetUsd is configured in runtime settings, the agent automatically stops when its total cost exceeds the limit.

Cost Alerts

System warnings appear in the chat when an agent's cost crosses $1, $5, or $10 thresholds.