Configure AFK

AFK combines environment variables, JSON settings, and an optional Markdown prompt overlay. Start with afk config to see the effective model and provider, then edit only the setting you need. The complete, generated key list is in Configuration keys; this page explains where values come from.

Fast pathCopy Anchor Link

Secrets are entered through a masked prompt with afk config env set ANTHROPIC_API_KEY, not as a command-line value. For initial Anthropic authentication, afk login also prompts without echoing the token. See API keys.

Where configuration livesCopy Anchor Link

AFK_HOME changes the user root, and AFK_STATE_DIR changes the state tier. Both must be absolute paths. AFK state is separate from Claude Code's ~/.claude/ tree.

PrecedenceCopy Anchor Link

Shell environment variables take priority over values loaded from dotenv files. Dotenv loading checks ./.env, then ~/.afk/config/afk.env, then legacy ~/.afk.env, without overwriting an existing value. Matching environment settings, such as AFK_MODEL, can override JSON settings.

The operator prompt always starts with the built-in framework prompt. One overlay source is appended: AFK_SYSTEM_PROMPT wins, otherwise a systemPrompt value from the first applicable JSON config, otherwise nonempty personal and project AFK.md files are combined. JSON config is searched from the working directory, user config, then the legacy location. A higher-priority prompt source shadows the AFK.md files; /config view reports them. See AFK.md.

Example: allow one plugin hook to see an environment variableCopy Anchor Link

Plugin hook subprocesses normally receive a restricted environment. If a hook shipped by a trusted installed plugin needs a non-AFK credential, explicitly allow its variable for that plugin alone in the user-global ~/.afk/config/afk.config.json:

{
  "enablePluginHooks": true,
  "pluginHookEnv": {
    "example-reviewer": ["REVIEW_SERVICE_API_KEY"]
  }
}

Use the plugin's manifest name as the map key. Supply REVIEW_SERVICE_API_KEY through your shell environment or afk.env; do not put the secret value in this JSON. Only hooks from example-reviewer receive that named variable. Project-local pluginHookEnv is ignored. AFK's own protected credentials, including ANTHROPIC_API_KEY and AFK_*_API_KEY, cannot be forwarded through this allowlist. Enabling plugin hooks executes third-party commands, so inspect and trust the plugin first. For hook events, controls, and diagnostics see Hooks and Hook reference.

RelatedCopy Anchor Link