Documentation Index
Fetch the complete documentation index at: https://docs.mains.dev/llms.txt
Use this file to discover all available pages before exploring further.
A run is a single agent execution within a workspace. When you type a goal and press Enter, Mains creates a run, launches the agent, and tracks everything that happens — tool calls, file changes, token usage, and costs.
Run Lifecycle
Each run progresses through a series of statuses:
| Status | Description |
|---|
| Queued | Run is created and waiting to start |
| Running | Agent is actively executing |
| Succeeded | Agent completed the task successfully |
| Failed | Agent encountered an error and stopped |
| Canceled | Run was manually aborted by the user |
Turns
A run is composed of one or more turns. Each turn represents a single interaction cycle — the agent receives input, reasons about it, calls tools, and produces output. Mains tracks per-turn metrics:
| Metric | Description |
|---|
| Input tokens | Tokens sent to the model |
| Output tokens | Tokens generated by the model |
| Cache read | Tokens served from prompt cache |
| Cache write | Tokens written to prompt cache |
| Duration | Time taken for the turn |
- Tool name and arguments
- Execution result
- Duration and status (success/failure)
- Nested tool calls (e.g., subagent tools)
Tool calls are visible in the workspace events timeline, giving you full visibility into what the agent did and why.
Some tools require explicit approval before execution. Pre-approved tools run automatically:
| Pre-approved tools |
|---|
| Bash, Read, Write, Edit, Glob, Grep, MCP tools |
Context
Before starting a run, you can attach context to help the agent understand the task:
| Context type | Description |
|---|
| Files | Selected files from the file explorer |
| Diffs | Git diffs from previous runs |
| Selections | Code selections highlighted in the editor |
| Notes | Free-text notes added manually |
| Linked tasks | Issues from connected services |
| Signals | Sentry errors with stack traces, affected users, and regression info |
Artifacts
Runs can produce artifacts — outputs that are stored and accessible after completion:
| Artifact type | Description |
|---|
| Patches | Code patches generated by the agent |
| Files | Files created or modified |
| Logs | Execution logs |
| Reports | Structured output (e.g., review findings) |
Session Resumption
Runs are tracked with a session ID. You can:
- Continue a previous session to pick up where you left off
- Fork a session to branch off from a specific point
- Resume after the app restarts using the
/resume command
Session resumption preserves the full conversation history and context from the original run.
Cost Tracking
Mains tracks the estimated cost of each run in microdollars (USD * 1,000,000) to avoid floating-point precision issues. Costs are broken down by:
- Model — which LLM was used for each turn
- Turn — per-turn token usage and cost
- Run total — aggregate cost across all turns
View cost data per-run in the workspace sidebar, or see aggregate costs in the stats dashboard.
Workspace Diffs
At the start of each run, Mains captures the Git HEAD SHA. After the run completes, it computes a unified diff against the base ref. This diff shows exactly what the agent changed and is displayed in the diff viewer.
Each diff includes:
- Full unified diff text
- List of changed files
- File stats (additions, deletions, modifications)
Sleep Prevention
When enabled in Settings, Mains prevents your Mac from sleeping during active runs using macOS power management. Sleep prevention is released automatically when the run completes or the app quits.