User and Project Settings

Aether loads settings from two locations — user level and project level — and merges them into a single resolved configuration.

User settings

• Directory$HOME/.aether/

  • settings.json — Shared across all projects

User-level settings live in $HOME/.aether/settings.json. Set the AETHER_HOME environment variable to use a different directory:

export AETHER_HOME=/custom/path/.aether

Generate a user-level settings file with the interactive wizard:

aether settings init --user

Path resolution

Paths in user settings resolve from the Aether home directory ($HOME/.aether by default):

$HOME/.aether/settings.json

{
  "agents": [
    {
      "name": "Planner",
      "description": "Plans work across any workspace",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true,
      "prompts": ["planner/SYSTEM.md"],
      "mcps": ["mcp.json"]
    }
  ]
}

Here planner/SYSTEM.md resolves to $HOME/.aether/planner/SYSTEM.md, and mcp.json resolves to $HOME/.aether/mcp.json.

Project settings

• Directorymy-project/.aether/

  • settings.json — Specific to this project

Project-level settings are optional and live in my-project/.aether/settings.json.

Generate a project-level settings file with the interactive wizard:

aether settings init --project

Path resolution

Plain relative paths in project settings resolve from the workspace root (the directory containing .aether/):

.aether/settings.json

{
  "agents": [
    {
      "name": "Build",
      "description": "Builds features",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true,
      "prompts": ["AGENTS.md"],
      "mcps": [".aether/mcp.json"]
    }
  ]
}

Here AGENTS.md resolves to <workspace-root>/AGENTS.md.

Initialization options

aether settings init runs an interactive wizard by default. Pass flags to answer the prompts non-interactively, which is useful for scripts and CI:

Flag	Description
--user / --project	Required. Choose the settings scope.
--path <dir>	Project directory to initialize (defaults to .). Only with --project.
--provider <name>	Provider to use, e.g. anthropic, codex, or bedrock. Skips the provider prompt.
--preset <name>	minimal (a single agent with bash and skills tools) or batteries-included (Plan, Build, and Explore agents wired to the built-in MCP servers). Skips the preset prompt.
--harness <name>	Harness conventions to auto-load with batteries-included. Repeatable: claude, agents.
--force	Overwrite an existing settings file at the selected target.

# Batteries-included project setup, fully non-interactive
aether settings init --project \
  --provider anthropic \
  --preset batteries-included \
  --harness claude --harness agents

Variable expansion

All resource paths support $VAR / ${VAR} variable expansion. This lets user-level settings reference project files without knowing the project’s location.

Use this for prompt files and MCP config files that should be loaded up front. Do not use prompts to load read-triggered rules; rule artifacts are loaded automatically by the MCP servers when their read globs match.

${WORKSPACE}

${WORKSPACE} always resolves to the current workspace root — the project directory you launched Aether from.

$HOME/.aether/settings.json

{
  "agents": [
    {
      ...
      "prompts": [
        "BUILD.md",
        { "type": "file", "path": "${WORKSPACE}/AGENTS.md", "optional": true }
      ],
      "mcps": [
        "mcp.json",
        { "type": "file", "path": "${WORKSPACE}/.aether/mcp.json", "optional": true }
      ]
    }
  ]
}

In this example:

• BUILD.md loads from $HOME/.aether/BUILD.md (user home).
• ${WORKSPACE}/AGENTS.md loads from the current project’s root.
• ${WORKSPACE}/.aether/mcp.json loads the project’s MCP config.
• The optional flag means the agent still works in projects that don’t have these files.

Inline settings

Settings can be passed directly via the --settings-json CLI flag. This bypasses file loading and uses the same schema:

aether headless \
  --settings-json '{
    "agent": "Hello",
    "agents": [
      {
        "name": "Hello",
        "description": "A minimal hello world agent",
        "model": "zai:glm-5.1",
        "userInvocable": true,
        "prompts": [
          {
            "type": "text",
            "text": "You are a friendly assistant."
          }
        ]
      }
    ]
  }' \
  "Say hello"

Inline settings are merged on top of file-based settings using the same rightmost-wins rules.

Typical patterns

Shared agent with project overrides

Define a general-purpose agent in user settings and let projects extend it:

$HOME/.aether/settings.json

{
  "agents": [
    {
      "name": "Build",
      "description": "Builds features and fixes bugs",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "reasoningEffort": "high",
      "userInvocable": true,
      "prompts": [
        "BUILD.md",
        { "type": "file", "path": "${WORKSPACE}/AGENTS.md", "optional": true }
      ],
      "mcps": [
        { "type": "file", "path": "mcp.json", "proxy": true },
        {
          "type": "file",
          "path": "${WORKSPACE}/.aether/mcp.json",
          "optional": true,
          "proxy": true
        }
      ]
    }
  ]
}

This agent loads its base system prompt and MCP config from the user’s Aether home, then optionally adds project-level instructions and MCP servers when they exist.

Team-shared project config

Commit .aether/settings.json and .aether/mcp.json to version control so every team member gets the same agent configuration:

.aether/settings.json

{
  "agent": "Build",
  "agents": [
    {
      "name": "Build",
      "description": "Builds features for this project",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true,
      "prompts": [".aether/BUILD.md", "AGENTS.md"],
      "mcps": [".aether/mcp.json"]
    }
  ]
}