Prompts

Aether assembles each agent’s system prompt from user-supplied prompt sources and MCP servers specified in an agent’s prompts field. There is no built-in system prompt, so you control every token in context.

Prompt sources

The prompts field accepts these formats:

Form	Example
String path shorthand	"AGENTS.md"
Typed file	{ "type": "file", "path": ".aether/BUILD.md" }
Typed glob	{ "type": "glob", "pattern": ".aether/prompts/*.md" }
Optional file/glob	{ "type": "file", "path": "AGENTS.md", "optional": true }
Inline text	{ "type": "text", "text": "Always answer concisely." }

Top-level prompts are defaults. An agent inherits them only when its own prompts array is empty. If an agent provides a non-empty prompts array, that array replaces the top-level prompt list for that agent.

.aether/settings.json

{
  "prompts": ["AGENTS.md"],
  "agents": [
    {
      "name": "Build",
      "description": "Coding agent",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true,
      "prompts": [
        ".aether/BUILD.md",
        "AGENTS.md",
        { "type": "file", "path": "${WORKSPACE}/AGENTS.md", "optional": true },
        { "type": "glob", "pattern": ".aether/prompts/*.md", "optional": true },
        { "type": "text", "text": "Prefer small, reviewable patches." }
      ]
    }
  ]
}

Prompt file paths and glob patterns use resource path resolution:

Prompt globs are for content that should always be part of the system prompt, such as shared prompt fragments. Do not add read-triggered rule files to prompts; rules with triggers.read are loaded automatically by the MCP servers when matching files are read.

• In project settings (.aether/settings.json), plain relative paths resolve from the workspace root.
• In user settings ($HOME/.aether/settings.json by default), plain relative paths resolve from the Aether home ($HOME/.aether by default). Set AETHER_HOME to use a different Aether home directory.
• ${WORKSPACE} always resolves to the current workspace root, so user-level agents can include project files such as ${WORKSPACE}/AGENTS.md.
• Other $VAR and ${VAR} references are expanded from the process environment.
• Required files must exist, and required globs must match at least one file. Add "optional": true to skip a missing file, zero-match glob, or unresolved variable.

$HOME/.aether/settings.json

{
  "agents": [
    {
      "name": "Planner",
      "description": "Plans work across any workspace",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true,
      "prompts": [
        "PLANNER.md",
        { "type": "file", "path": "${WORKSPACE}/AGENTS.md", "optional": true }
      ]
    }
  ]
}

In this user-level example, PLANNER.md is loaded from the Aether home, while AGENTS.md is loaded from whichever workspace is currently open.

Agent prompt files

The onboarding wizard writes an agent-name-derived prompt file, for example .aether/BUILD.md for an agent named Build:

.aether/BUILD.md

# Build

Build features and fix bugs in this project.

## System Env

Working directory: !`pwd`\
Platform: !`uname -s`\
Today's date: !`date +%Y-%m-%d`\
Git branch: !`git rev-parse --abbrev-ref HEAD`

Additional files such as AGENTS.md, CLAUDE.md, or GEMINI.md are ordinary prompt sources. Include them when you want to reuse instructions already authored for other tools.

AGENTS.md

# Project Instructions

You are a coding assistant for this Rust project.

## Rules

- Always read files before editing them.
- Write tests for new behavior.
- Use the project `just` commands when available.

Shell interpolation

Prompt files support shell interpolation markers:

Current branch: !`git branch --show-current`
Crate count: !`find packages -name Cargo.toml | wc -l`

Aether runs each marker with $SHELL -c from the prompt cwd, substitutes trimmed stdout, and removes the marker if the command fails. Use interpolation for small, deterministic context such as dates, branch names, or environment summaries; avoid expensive commands in prompts because they run when the prompt is assembled.

Inline text sources do not run shell interpolation. Globbed markdown files do.

Prompt ordering

Prompt sources are resolved in the order listed. Glob matches are sorted before their file contents are joined. The final system prompt joins non-empty prompt parts with blank lines, followed by MCP server instructions when tools are connected.

Debugging prompts

Use show-prompt to see the fully assembled prompt and the MCP tool summary for any agent after user and project settings have been merged and all resource paths have been resolved:

aether show-prompt
# Inspect a specific agent
aether show-prompt -a Build
aether show-prompt -C /path/to/project

show-prompt accepts the same settings and MCP override flags as headless mode: --settings-json, --settings-file, --mcp-config, --mcp-config-json, and --system-prompt.