Agents

An agent is a named configuration that binds a model, provider, system prompt, default mode, and tool access together. Each agent is a Markdown file with YAML frontmatter in .aura/config/agents/.

When you switch agents (via /agent, Shift+Tab, or --agent), Aura swaps the entire LLM configuration in one step — model, thinking level, available tools, and system prompt all change together.

Frontmatter Schema 

---
name: AgentName           # Unique identifier (shown in /agent and status bar)
description: ""           # Human-readable description (shown in /agent listing)
inherit: [Base]           # Inherit from parent agent(s).
                          # Key absent = inherit. Key present = replace. No append.

model:
  provider: ollama        # Provider name (must match providers/*.yaml)
  name: llama3:8b         # Model identifier at the provider
  think: high             # Thinking: false/off, true, "low", "medium", "high"
  context: 65536          # Context window in tokens (Ollama: sets num_ctx; others: compaction denominator only)
  generation:             # Optional generation parameters (all pointer fields — omit to inherit)
    temperature: 0.7      # Sampling temperature
    top_p: 0.95           # Nucleus sampling threshold
    top_k: 40             # Top-k sampling (number of highest probability tokens to consider)
    frequency_penalty: 0.0 # Penalize tokens by their frequency in the output so far
    presence_penalty: 0.0  # Penalize tokens that have appeared in the output so far
    max_output_tokens: 8000 # Maximum output tokens
    stop: []              # Stop sequences (generation stops when any sequence is produced)
    seed: 42              # Random seed for reproducibility (provider support varies)
    think_budget: 4000    # Thinking token budget (when think is enabled)

response_format:          # Constrain LLM responses to a specific format (optional)
  type: json_schema       # "text" (default), "json_object", or "json_schema"
  name: my_output         # Schema name (required by OpenAI for json_schema, auto-defaults to "response")
  schema:                 # JSON Schema as YAML (required for json_schema)
    type: object
    properties:
      answer:
        type: string
    required: [answer]
    additionalProperties: false
  strict: true            # Strict schema adherence (OpenAI, OpenRouter)

thinking: ""              # Prior thinking handling: "" (keep), "strip", "rewrite"

tools:
  enabled: ["*"]          # Glob patterns to enable (["*"] = all, [] = all (default))
  disabled: []            # Glob patterns to disable (applied after enabled)
  policy:                 # Tool execution policy (merged with mode-level policy)
    auto: []              # Tool/Bash/path patterns to auto-approve (run without asking)
    confirm: []           # Tool/Bash/path patterns requiring user approval before execution
    deny: []              # Tool/Bash/path patterns to hard-block (even in auto mode)
                          # Pattern syntax: "ToolName", "Bash:command*", or "Tool:/path/*"

hooks:
  enabled: []             # Hook name patterns to include ([] = all). Supports * wildcards.
  disabled: ["go:*"]      # Hook name patterns to exclude. Cascade-prunes dependents.

system: Agentic           # System prompt name (Agentic, Chat, Lite)
mode: Plan                # Default mode (Edit, Plan, Ask)

hide: false               # Exclude from /agent listing and Shift+Tab cycling
default: false            # Use as default when --agent is not specified (only one allowed)
subagent: false           # Make this agent available for the Task tool (subagent delegation)
agentsmd: all             # AGENTS.md injection: "all" (default), "global", "local", "none"

fallback:                 # Provider failover chain (ordered list of agent names)
  - openrouter/gpt-oss-120b   # Tried first if primary provider fails
  - anthropic/sonnet           # Tried second if first fallback also fails

files:                    # Files to load into the system prompt (optional)
  - docs/style-guide.md   # Resolved relative to config home (e.g. .aura/)
  - CHANGELOG.md

features:                 # Feature overrides (merged on top of global defaults)
  compaction:
    threshold: 70         # Override compaction trigger percentage
  tools:
    max_steps: 20         # Override max tool-use iterations
---

The Markdown body below the frontmatter becomes the agent’s prompt template. The system field selects an additional system prompt from prompts/system/.

Inheritance

The inherit: field lets an agent extend one or more parent agents:

inherit: [Base]              # Single parent
inherit: [Base, Restricted]  # Multiple parents (merge left-to-right, child last)

Merge rule: Key absent in child = inherit from parent. Key present in child = replace parent’s value entirely. Slices are always replaced, never appended. The default field is excluded from inheritance — it is an identity property that would cause “multiple defaults” errors if cascaded.

Inheritance is resolved via a DAG (directed acyclic graph). Cycles and missing parents produce clear errors at startup. The prompt body (Markdown below frontmatter) also inherits — last non-empty body in the chain wins. If an agent resolves to an empty prompt (no body in the agent or its immediate parents), a [config] agent "<name>" resolved to empty prompt message appears in the debug log (--debug).

File Autoloading

The files: field lists paths to inject into the system prompt at agent construction time. Each file is read, rendered as a Go template, and registered as a named template (file:<path>). The system prompt’s composition directives control where files appear via {{ range .Files }}{{ include .TemplateName $ }}{{ end }}.

Both file paths and file contents are expanded as Go templates with access to:

Variable Description
{{ .Config.Global }} Global config home (~/.aura or --home override; empty if disabled)
{{ .Config.Project }} Write home (last --config entry)
{{ .Config.Source }} Config home that owns the agent file
{{ .LaunchDir }} CWD at process start (before os.Chdir(--workdir))
{{ .WorkDir }} Effective working directory after os.Chdir(--workdir)
{{ .Model.Name }} Resolved model name
{{ .Provider }} Provider name
{{ .Agent }} Agent name
{{ .Mode.Name }} Mode name
{{ .Tools.Eager }} List of resolved eager tool names
{{ .Memories.Local }} Concatenated local memory entries (.aura/memory/*.md)
{{ .Memories.Global }} Concatenated global memory entries (~/.aura/memory/*.md)
{{ env "VAR" }} Environment variable (sprig)
{{ index .Vars "key" }} User-defined --set key=value

Conditional paths that evaluate to an empty string are silently skipped:

files:
  - docs/style-guide.md
  - "{{ .Config.Source }}/shared/rules.md"
  - '{{ if env "LOAD_EXTRA" }}config/prompts/extra.md{{ end }}'

Paths are resolved relative to the config home directory (e.g. .aura/). Missing or unreadable files cause an error — the agent will not load.

When switching agents, the new agent’s files replace the previous agent’s files automatically.

AGENTS.md Injection

The agentsmd: field controls whether workspace instruction files (AGENTS.md) are automatically loaded into this agent’s system prompt. AGENTS.md files are discovered from:

  1. Config homes — each config directory (e.g., ~/.aura/, .aura/, --config entries) is checked for AGENTS.md
  2. Upward walk — when --workdir is used, aura walks upward from the working directory toward the launch directory, collecting AGENTS.md at each level. The walk stops at the first .git directory, the launch directory, or the filesystem root. Without --workdir, only the current directory is checked (no walk).

Discovered files are classified into two scopes:

  • Global — AGENTS.md found under the global config home (~/.aura/)
  • Local — all other AGENTS.md files (project config homes, walked directories)
Value Behavior
"" or "all" Inject all AGENTS.md files (default)
"global" Inject only global-scoped AGENTS.md
"local" Inject only local-scoped AGENTS.md
"none" Skip all AGENTS.md injection

This is independent of hide: — a visible agent can suppress AGENTS.md, and a hidden agent can still receive it. Use agentsmd: none for feature agents or lightweight agents that should not be influenced by workspace instructions.

Feature Agents

Agents with hide: true are excluded from the user-facing agent list (cycling via Shift+Tab, the /agent picker, and TUI overlay). The hide field is purely about UI visibility — it does not affect AGENTS.md injection (use agentsmd: none for that).

A subset of hidden agents are feature agents — agents used internally by features like compaction, embeddings, vision, transcription, speech synthesis, and title generation. They live in .aura/config/agents/features/ and define their own provider, model, and prompt independently of the main conversation agent.

Feature configs (in features/*.yaml) reference these agents by name via their agent: field. See Features.

Provider Failover

The fallback: field defines an ordered list of agent names to try when this agent’s provider fails permanently (after retries are exhausted). Each fallback is a full agent — it brings its own provider, model, prompt, tools, and mode.

fallback:
  - openrouter/gpt-oss-120b
  - anthropic/sonnet

Failover triggers on provider-level errors: network failures, auth errors, rate limits (after retry exhaustion), credit exhaustion, model unavailable, and server errors. Content filter errors and user cancellation do not trigger failover.

Failover is one-way per session — once switched to a fallback, the session stays on that agent. Use /agent <name> to switch back manually. Only the primary (starting) agent’s fallback list is evaluated; fallback agents’ own fallback: lists are ignored.

CLI --model and --provider overrides are stripped when switching to a fallback agent — they belong to the primary agent’s provider.

Default Agent

When --agent is not specified, the default agent is resolved automatically:

  1. The agent with default: true in its frontmatter (only one allowed — error if multiple).
  2. If none found, the first non-hidden agent (alphabetical by name).
  3. If no non-hidden agents exist, error.

Hidden agents (hide: true) can have default: true.

Switching Agents

  • Keybinding: Shift+Tab cycles through visible agents
  • Slash command: /agent [name] switches to a specific agent or lists all
  • CLI flag: --agent <name> sets the starting agent

Switching agents swaps model, provider, mode, tools, and system prompt. If the new agent has different MCP filter rules (features.mcp.enabled/features.mcp.disabled), MCP sessions are automatically closed and reconnected with the new filter set.

Feature Overrides

The features: block lets an agent override global feature defaults from features/*.yaml. Only set fields you want to change — unset fields inherit the global value.

The override uses a deep merge: non-zero values in the agent’s features: block replace the global default for that field. Zero values and omitted fields fall through.

Override precedence: global features → CLI flags → agent frontmatter → mode frontmatter → task definition

Available feature keys match the top-level keys in features/*.yaml: compaction, title, thinking, vision, embeddings, tools, stt, tts, sandbox, subagent, plugins, mcp, estimation, guardrail. See Features for all available fields.

Example 

---
name: MyAgent
model:
  provider: ollama
  name: llama3:8b
  think: medium
  context: 16384
  generation:
    temperature: 0.7
    top_k: 40
    max_output_tokens: 8000
thinking: strip
tools:
  enabled: ["*"]
  disabled: ["Bash"]
hooks:
  disabled: ["go:*"]
features:
  tools:
    max_steps: 100
  compaction:
    threshold: 90
system: Agentic
mode: Edit
---

To see the default agents that ship with aura init, inspect .aura/config/agents/ after scaffolding.

Back to top

Copyright © 2026 idelchi. Distributed under the MIT License.