Skip to content

Agents

Agents are defined in .aether/settings.json — their model, prompts, tool access, and how they can be invoked.

File location

Directory.aether/
- settings.json — Agent catalog
- mcp.json — MCP server config
- DEFAULT.md — Shared prompt scaffold
AGENTS.md — Project instructions

Example

{
  "prompts": [".aether/DEFAULT.md", "AGENTS.md"],
  "mcpServers": [".aether/mcp.json"],
  "agents": [
    {
      "name": "planner",
      "description": "Plans implementation strategy",
      "model": "anthropic:claude-sonnet-4-5",
      "reasoningEffort": "high",
      "userInvocable": true
    }
  ]
}

Top-level fields

Field	Type	Description
`prompts`	`string[]`	Glob patterns for prompt files inherited by all agents
`mcpServers`	`Array<string \| { path: string, proxy?: boolean }>`	Inherited MCP config refs. Files are merged in order; on collisions, the last file wins. Use `{ "path": "...", "proxy": true }` to route a referenced config through Aether’s built-in proxy.
`agents`	`AgentEntry[]`	Array of agent definitions

Agent entry fields

Field	Type	Default	Description
`name`	`string`	required	Unique identifier for the agent
`description`	`string`	required	Human-readable description shown in the UI
`model`	`string`	required	Model spec — `provider:model-id` or comma-separated alloy
`reasoningEffort`	`string`	—	`"low"`, `"medium"`, `"high"`, or `"xhigh"`
`userInvocable`	`boolean`	`false`	Appears as a mode in the TUI and ACP clients
`agentInvocable`	`boolean`	`false`	Can be spawned as a sub-agent
`prompts`	`string[]`	`[]`	Glob patterns for agent-specific prompt files
`mcpServers`	`Array<string \| { path: string, proxy?: boolean }>`	`[]`	When non-empty, replaces the inherited MCP config list for that agent. Files are merged in order; on collisions, the last file wins.
`tools`	`object`	`{}`	Tool filtering with `allow` and `deny` arrays

Validation rules