Agents

Agents define different AI personas with specific models, prompts, permissions, and capabilities.

Built-in Agents

Agent	Description	Access Level
builder	Create and modify dbt models, SQL pipelines, and data transformations	Full read/write. SQL mutations prompt for approval.
analyst	Answer questions about your data — explore it, run SELECT queries, inspect schemas, generate insights	Read-only (enforced). SQL writes, file edits, shell, memory saves and other built-in write tools denied, even if config allows them. MCP and custom tools follow your config. Training entries and session scratch tables are still allowed.
plan	Plan before acting — restricted to planning files only	Minimal — no edits, no bash, no SQL

Builder

Full access mode. Can read/write files, run any bash command (with approval), execute SQL, and modify dbt models. SQL write operations (INSERT, UPDATE, DELETE, CREATE, etc.) prompt for user approval. Destructive SQL (DROP DATABASE, DROP SCHEMA, TRUNCATE) is hard-blocked.

Analyst

The agent for asking questions about your data. Truly read-only mode for safe data exploration:

• File access: Read, grep, glob — no prompts
• SQL: SELECT queries execute freely. Write queries are denied (not prompted — blocked entirely)
• Bash: Denied. Use read, grep and glob to read files
• Web: Fetch and search allowed without prompts
• Schema/warehouse/finops: All inspection tools available
• Workspace knowledge: Loads workspace and project skills; reads workspace memory and views this checkout's memory audit log. Can read files bundled with skills, including global skills stored outside the project. Reloading memory syncs the local copy with the workspace, which can remove a local copy of a block the workspace archived. Saving memory is done with builder.
• Config overrides: A permission config such as "*": "allow" cannot turn file edits, SQL writes (including data diffs of arbitrary queries), shell, memory saves, warehouse connection or MCP config changes, training imports, sample project setup, feedback submission, batch tool calls or delegation beyond data-explorer back on. A global "*": "allow" does turn on MCP and custom tools for analyst, including ones that write (for example a SQL MCP server); to keep them from analyst, put the "*": "allow" under agent.builder instead of the global config, or deny those tools under agent.analyst.permission.
• Reasoning effort: On adaptive-thinking models the analyst requests high effort unless the agent or model options already choose one. Set ALTIMATE_ANALYST_EFFORT (low, medium, high, xhigh, max, or off to send none) to change it.
• Final answers: answer_commit asks the interactive analyst once per turn to re-check any number that did not appear in tool output before the answer is committed.

Tip

Use analyst when exploring data to ensure no accidental writes. Switch to builder when you're ready to create or modify models.

Plan

Planning mode with minimal permissions. Can only read files and edit plan files in .opencode/plans/. No SQL, no bash, no file modifications.

SQL Write Access Control

All SQL queries are classified before execution:

Query Type	Builder	Analyst
SELECT, SHOW, DESCRIBE, EXPLAIN	Allowed	Allowed
INSERT, UPDATE, DELETE, CREATE, ALTER	Prompts for approval	Denied
DROP DATABASE, DROP SCHEMA, TRUNCATE	Blocked (cannot override)	Blocked

The classifier detects write operations including: INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, ALTER, TRUNCATE, GRANT, REVOKE, COPY INTO, CALL, EXEC, EXECUTE IMMEDIATE, BEGIN, DECLARE, REPLACE, UPSERT, RENAME.

Multi-statement queries (SELECT 1; INSERT INTO ...) are classified as write if any statement is a write.

Custom Agents

Define custom agents in altimate-code.json:

{
  "agent": {
    "reviewer": {
      "model": "anthropic/claude-sonnet-4-6",
      "prompt": "You are a data engineering code reviewer. Focus on SQL best practices, dbt conventions, and warehouse cost efficiency.",
      "description": "Reviews data engineering code",
      "permission": {
        "write": "deny",
        "edit": "deny",
        "bash": {
          "*": "deny",
          "dbt docs generate": "allow"
        }
      }
    }
  }
}

Agent Configuration

Field	Type	Description
model	string	Model to use (provider/model)
variant	string	Model variant
temperature	number	Sampling temperature
top_p	number	Nucleus sampling
prompt	string	System prompt
description	string	Agent description
disable	boolean	Disable this agent
mode	string	"primary", "subagent", or "all"
hidden	boolean	Hide from agent list (subagents only)
color	string	Hex color or theme color name
steps	number	Max agentic iterations
permission	object	Agent-specific permissions
options	object	Custom options

Markdown Agent Definitions

Create agents as markdown files in .altimate-code/agents/:

---
name: cost-reviewer
model: anthropic/claude-sonnet-4-6
description: "Reviews queries for cost efficiency"
---

You are a Snowflake cost optimization expert. For every query:
1. Estimate credit consumption
2. Suggest warehouse size optimization
3. Flag full table scans and cartesian joins
4. Recommend clustering keys where appropriate

Info

Markdown agent files use YAML frontmatter for configuration and the body as the system prompt.

Agent Permissions

Each agent can have its own permission overrides:

{
  "agent": {
    "builder": {
      "permission": {
        "write": "deny",
        "edit": "deny",
        "sql_execute_write": "deny",
        "bash": {
          "*": "deny",
          "dbt list *": "allow",
          "ls *": "allow"
        }
      }
    }
  }
}

analyst already denies its shell and built-in write tools whatever its config says, so its config is mainly useful to restrict it further (for example "webfetch": "deny") or to allow MCP and custom tools.

Warning

Agent-specific permissions override global permissions. A "deny" at the agent level cannot be overridden by a global "allow".

Switching Agents

• TUI: Press leader + a or use /agent <name>
• CLI: altimate --agent analyst
• In conversation: Type /agent analyst