Configuration Overview

agent-afk keeps all state under ~/.afk/ — completely independent of ~/.claude/. You can delete ~/.claude/ entirely and afk still runs.

Directory layout

~/.afk/
  config/
    afk.env              # API keys and env overrides — written by `afk login` or `afk config env set`
    afk.config.json      # structured config — edited with `afk config set` or by the agent
    mcp.json             # MCP server registry
  state/                 # $AFK_STATE_DIR overrides this tier
    sessions/            # session-store sidecars
    todos/               # todo-panel data
    transcripts/         # autosaved REPL session transcripts
    daemon/              # per-instance daemon state
  agent-framework/       # local telemetry and operational data
  skills/                # user-authored or generated skills
  plugins/               # installed plugins and marketplace caches
  logs/
  cache/

The root directory is controlled by AFK_HOME (default ~/.afk/). Set it to an absolute path to relocate everything at once — useful on shared machines or when you want a project-isolated state tree.

Config resolution tiers

Configuration is layered. Higher tiers win over lower ones.

The built-in prompt is always present. Any overlay you set is appended after it under an # Operator configuration header — it adds to the base, never overwrites it.

Environment variables override matching fields in afk.config.json. For example, AFK_MODEL overrides model. See Environment Variables for the full list.

.env file loading

Before env vars are read, loadEnvConfig() loads dotenv files in this order (first occurrence wins, no override):

1. <cwd>/.env — per-repo overrides
2. ~/.afk/config/afk.env — user-scope, the canonical place for API keys
3. Legacy ~/.afk.env — back-compat

The afk login wizard writes keys to ~/.afk/config/afk.env.

Inspecting and editing config

afk config           # human-readable dump of resolved model, provider, API key presence
afk config --format json   # machine-readable JSON
afk doctor           # validates keys, paths, and provider connectivity

Edit config without opening an editor:

afk config set model opus            # write afk.config.json
afk config env set AFK_EFFORT high   # write afk.env
afk config env set ANTHROPIC_API_KEY # secrets prompt for a masked value

See Editing Configuration for the full command reference, the agent-vs-human sensitivity tiers, and the config_get/config_set tools the agent uses to tune its own settings.

--dump-prompt <path> on any command writes the fully-resolved system prompt (framework base + operator overlay) to a file, with provenance noted in a header (e.g. framework+afk-md:/path/to/AFK.md).

Overriding home

AFK_HOME=/opt/my-afk afk config

AFK_HOME must be an absolute path and must not be /. The runtime enforces this at startup.

What's not shared with Claude Code

AFK's state directories (~/.afk/) are fully independent of Claude Code's ~/.claude/. Plugin state for the plugin surface writes to ~/.claude/agent-framework/ independently — no shared state.

afk.config.json schema

afk.config.json is a JSON file (no JSONC comments in the runtime-parsed copy; the .example ships with comments for documentation only). All fields are optional; unset fields fall through to env vars or built-in defaults.

Top-level fields

{
  "model": "sonnet",
  "maxTokens": 4096,
  "temperature": 1.0,
  "systemPrompt": "Always run the test suite before declaring a task done. Prefer small, reversible commits.",
  "updatePolicy": "notify",
  "autoResumeOnUsageLimit": true,
  "bgSummaries": false,
  "maxSummaryCallsPerSession": 200,
  "enableShellHooks": true
}

models — per-tier model bindings

Bind specific models to the small, medium, and large quality tiers used by skills and subagent dispatch. Each slot accepts a bare model id string or an object with optional provider credentials.

{
  "models": {
    "small": "claude-haiku-4-5-20251001",
    "medium": "claude-sonnet-5",
    "large": {
      "id": "claude-opus-5",
      "name": "big",
      "provider": "anthropic",
      "baseUrl": "http://localhost:8080",
      "apiKey": "sk-local"
    }
  }
}

When using the object form, each slot accepts:

autoRouting — per-surface auto-routing

Controls whether each surface runs in "auto-routing" mode. When enabled for a surface, the agent automatically routes work without waiting for explicit confirmation. Accepts a boolean per surface key.

{
  "autoRouting": {
    "interactive": false,
    "chat": true,
    "telegram": true,
    "daemon": true
  }
}

Env override: AFK_AUTO_ROUTING=true sets all four surfaces simultaneously.

daemon — headless daemon defaults

Configures default task and optional worktree pruning for afk daemon.

{
  "daemon": {
    "task": "/review the most recent pr",
    "taskId": "default",
    "worktreePrune": {
      "enabled": true,
      "cron": "0 4 * * *",
      "maxAgeDaysClean": 14,
      "maxAgeDaysDirty": 30,
      "scope": "all"
    }
  }
}

interactive — REPL defaults

Controls worktree and UX behavior for afk interactive.

{
  "interactive": {
    "worktreeAutoname": true,
    "worktreeBranchPrefix": "afk/",
    "worktreeBase": "origin/main",
    "suggestGhost": true
  }
}

hooks — shell-command lifecycle hooks

The hooks block maps lifecycle event names to arrays of matcher groups. Each group runs one or more shell commands when the event fires and the optional tool-name matcher matches.

Prerequisites: enableShellHooks: true must be set in a user-global config file (~/.afk/config/afk.config.json). To also admit hook definitions from project-local files, additionally set allowProjectHooks: true in a user-global file.

{
  "enableShellHooks": true,
  "allowProjectHooks": false,
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.afk/hooks/pre-bash-check.sh",
            "timeout_ms": 5000
          }
        ]
      },
      {
        "matcher": "/^write_/",
        "hooks": [
          { "type": "command", "command": "~/.afk/hooks/write-guard.sh" }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.afk/hooks/on-session-start.sh",
            "timeout_ms": 3000
          }
        ]
      }
    ]
  }
}

Event keys

Every event's payload also includes cwd and transcript_path (the latter is null when no transcript file is tracked).

A Stop hook's output reaches the model. Because Stop fires after every REPL turn, a Stop shell hook that returns hookSpecificOutput.additionalContext feeds that text into the next turn's prompt — the same channel UserPromptSubmit uses. This is the general injectContext primitive (see src/agent/hooks.ts) applied to a config-driven shell hook; it introduces no new trust boundary, since it only fires when you have already opted a Stop hook in under the enableShellHooks gate below.

Matcher group fields

Hook definition fields

Exit-code protocol

Trust gates

Plugin-contributed hooks

AFK discovers and runs hooks shipped by installed plugins, matching Claude Code's plugin-hook layout so plugins are portable across both runtimes.

• Location. Any installed plugin under ~/.afk/plugins/ that ships a <plugin>/hooks/hooks.json (alongside its .claude-plugin/plugin.json manifest) contributes hooks. Both the flat and marketplace-cache layouts are scanned. Plugin hooks merge after your own config hooks.
• Trust gate. Plugin hooks run only when enablePluginHooks: true is set in a user-global file — a separate opt-in from enableShellHooks, because a plugin's hooks.json executes third-party code. When plugin hooks.json files are present but the gate is off, AFK emits a one-line warning naming how to enable them (it never runs them silently). Set it with afk config set enablePluginHooks true. Because the two gates are independent, turning enableShellHooks off does not disable plugin hooks — to run no third-party hooks, leave enablePluginHooks unset (or set it to false).
• Supported types. Only command-type hooks run. Claude Code's other hook types (http, mcp_tool, prompt, agent) are skipped with a warning that names the unsupported type.
• Environment. Plugin hook commands receive CLAUDE_PLUGIN_ROOT (the plugin's install directory) and CLAUDE_PROJECT_DIR, so commands like python3 "${CLAUDE_PLUGIN_ROOT}/hooks/on_start.py" resolve. The same secret redaction as shell hooks applies — no API keys or tokens are forwarded.
• Scope. Discovery covers user-global installed plugins only. Project-scoped and bundled plugin hooks, inline hooks in plugin.json, and the non-command hook types are not yet honored.