Configuration

Athena Flow uses JSON config files for persistent settings. CLI flags always take final precedence.

Config File Locations

Both files are optional. If neither exists, Athena uses defaults for all settings.

Merge Order

Settings are applied in this order, with later sources winning:

Global config → Project config → CLI flags

Config Schema

{
  "plugins": ["/path/to/plugin-dir", "name@owner/repo"],
  "additionalDirectories": ["/path/to/allow"],
  "workflow": "e2e-test-builder",
  "theme": "dark",
  "model": "sonnet",
  "harness": "claude-code"
}

plugins

Type: string[]

An array of plugin references. Each entry is either an absolute or relative path to a plugin directory, or a marketplace ref in the form name@owner/repo. Marketplace refs cause Athena to clone the marketplace repo into ~/.config/athena/marketplaces/ and resolve the plugin from it.

{
  "plugins": [
    "./plugins/custom-commands",
    "e2e-test-builder@lespaceman/athena-workflow-marketplace"
  ]
}

Plugins are merged in order: global config → project config → --plugin CLI flags.

additionalDirectories

Type: string[]

Additional filesystem paths that Claude Code is granted access to. Passed as --add-dir flags to the spawned Claude process. Useful when your project reads from shared directories outside the project root.

{
  "additionalDirectories": [
    "/data/fixtures",
    "/home/user/shared-schemas"
  ]
}

workflow

Type: string

The workflow name to activate. Resolved from the local workflow registry at ~/.config/athena/workflows/<n>/workflow.json. The workflow must be installed before it can be referenced here — see Marketplace Resolution.

{
  "workflow": "e2e-test-builder"
}

theme

Type: "dark" | "light" | "high-contrast"

The default terminal UI theme. Defaults to dark if not set.

{
  "theme": "dark"
}

model

Type: string

The model alias or full model ID to use for the spawned Claude process. Accepts short aliases like "sonnet" or "opus", or a full model ID.

{
  "model": "sonnet"
}

harness

Type: "claude-code" | "openai-codex" | "opencode"

Which agent harness to use. Defaults to claude-code. Only claude-code is available in production; others are planned.

{
  "harness": "claude-code"
}

Example: Global Config

{
  "theme": "dark",
  "model": "sonnet",
  "plugins": ["e2e-test-builder@lespaceman/athena-workflow-marketplace"]
}

Example: Project Config

{
  "workflow": "e2e-test-builder",
  "additionalDirectories": ["../shared-fixtures"],
  "plugins": ["./athena-plugins/project-helpers"]
}

Editing Config Files

Config files are plain JSON. Changes take effect on the next Athena startup — there is no hot-reload at runtime.

To update config interactively, run:

athena-flow setup