Configuration

All configuration lives under .aura/config/ as YAML and Markdown files. Bootstrap the default configuration with:

aura init

Directory Structure

.aura/
├── config/
│   ├── agents/           # Agent definitions (Markdown + YAML frontmatter)
│   │   └── features/     # Hidden agents used by internal features (e.g. embeddings, guardrail)
│   ├── commands/         # Custom slash commands (Markdown + YAML frontmatter)
│   ├── features/         # Feature configs (YAML)
│   ├── hooks/            # User hook definitions (YAML) — pre/post tool execution
│   ├── lsp/              # LSP server definitions (YAML)
│   ├── mcp/              # MCP server definitions (YAML)
│   ├── modes/            # Mode definitions (Markdown + YAML frontmatter)
│   ├── prompts/          # System prompts (Markdown + YAML frontmatter, supports `inherit:`)
│   │   ├── system/       # Main system prompts (referenced by agent `system:` field)
│   │   ├── features/     # Feature-specific prompts (compaction, thinking)
│   │   └── logs/         # Logging-specific prompts
│   ├── providers/        # Provider configs (YAML)
│   ├── rules/            # Persistent approval rules (created on-demand when approvals are saved)
│   ├── sandbox/          # Landlock sandbox config (YAML) — merged into features sandbox
│   ├── tasks/            # Scheduled task definitions (YAML)
│   └── tools/            # Optional tool text overrides (any tool type)
├── plugins/              # Go plugins (recursive: organize into subdirs freely)
├── sessions/             # Saved sessions ({uuid}.json)
├── skills/               # LLM-invocable skills (Markdown + YAML frontmatter)
├── embeddings/           # Embeddings index
├── memory/               # Persistent key-value memory files
└── debug.log             # Debug log (when --debug is enabled)

Name Resolution

All name-based lookups (agents, modes, prompts, providers, commands, MCP servers, plugins, hooks, LSP servers, slash commands) are case-insensitive. For example, /agent high and /agent High resolve to the same agent. Tool and model names remain case-sensitive (LLM-facing contracts).

Sessions

Sessions are stored as JSON files at .aura/sessions/{uuid}.json. Each session contains the conversation history, metadata (title, agent, mode, model, provider, thinking state, loaded tools, sandbox state, read-before policy, session approvals, stats, cumulative usage), and todo list. Manage sessions with /save, /resume, /name, and /fork.

Embeddings Index

The embeddings index is stored at .aura/embeddings/. It is automatically created and incrementally updated when using the Query tool, /query command, or aura query CLI.

Workspace Instructions

Aura automatically loads AGENTS.md files into the system prompt. When --workdir is used, it walks upward from the working directory, collecting AGENTS.md files at each level until it reaches a .git directory, the launch directory, or the filesystem root. Without --workdir, only the current directory and config homes are checked.

Example Files

Each config directory includes a .example. reference file (e.g. agent.example.md, provider.example.yaml) that documents every possible field. These files are not loaded by Aura — they exist purely as documentation. To use one as a starting point, copy and rename it (removing .example. from the name).

Environment Variables

All CLI flags support AURA_ prefixed environment variables (e.g. AURA_AGENT, AURA_MODEL, AURA_DEBUG). Precedence: CLI flag > AURA_* env var > default. Use aura --print-env to see all resolved settings.

Provider tokens follow the pattern AURA_PROVIDERS_{NAME}_TOKEN (e.g. AURA_PROVIDERS_OPENROUTER_TOKEN). Tokens can also be set in provider YAML configs or loaded from an env file via --env-file (default: secrets.env).