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": "You are a helpful assistant.",
  "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-4-6",
    "large": {
      "id": "claude-opus-4-8",
      "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": "/forge-friction --auto",
    "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

Matcher group fields

Hook definition fields

Exit-code protocol

Trust gates