Agent AFK

Past the happy path of AI coding.

One prompt, one agent, one clean diff is the easy case. Agent AFK is the runtime for everything after — multi-session work, nested subagents, verification loops, and traces you can actually read. Local-first. Bring your own model.

Install

npm install -g agent-afk

Requires Node ≥ 20. Then point it at an API key:

export ANTHROPIC_API_KEY=sk-ant-...
# or, for Anthropic OAuth:
afk login

Smoke test:

afk chat "hello"
afk doctor       # environment self-check

What you can do with it

• Chat from your terminal — afk chat "..." for one-shot, afk i for a REPL with full tool access (Bash, file ops, web fetch, grep/glob, subagents).
• Hand long work off to a daemon — afk daemon runs headless. Pair it with send_telegram and you get pings on your phone when work lands in a terminal state.
• Message Claude from Telegram — afk telegram setup walks you through bot token + allowlist. After that you have a private chat surface backed by the same session manager as the REPL.
• Built-in orchestrators — /mint, /diagnose, /forge, /audit-fit dispatch subagent waves. /mint takes a feature idea and runs spec → research → plan → parallelize → build → verify → ship. /diagnose forks parallel root-cause hypotheses for failing tests and bugs.
• Cross-session memory — Claude remembers preferences, decisions, and procedures across runs. Backed by SQLite at ~/.afk/agent-framework/memory/ plus a HOT.md that injects into every future session's system prompt.
• Background tasks — Ctrl+B in the REPL detaches the current turn into a tracked task; /tasks lists them, /attach <id> re-attaches.

Four surfaces, one session manager

| Command | Surface | |---|---| | afk chat "..." | One-shot turn — pipe-friendly, scripts well | | afk i (alias of afk interactive) | REPL with slash commands, streaming, plan mode, image paste | | afk daemon | Long-running headless agent, cron-friendly | | afk telegram start | Telegram bot — same tools, same memory, on your phone |

Configuration

agent-afk keeps all of its state under ~/.afk/ — sessions, plugins, memory, logs, settings. Nothing is shared with ~/.claude/. You can delete ~/.claude entirely and afk still runs.

Minimum viable config is one env var:

ANTHROPIC_API_KEY=sk-ant-...

Optional, in order of usefulness:

# Pick a model — opus | sonnet | haiku (Anthropic) or codex (OpenAI)
AFK_MODEL=sonnet

# Enable the Telegram bot + send_telegram tool
TELEGRAM_BOT_TOKEN=1234567890:ABC...
AFK_TELEGRAM_ALLOWED_CHAT_IDS=12345678

# Per-task safety rails
AFK_MAX_BUDGET_USD=5.00

Project-scoped system prompt. Drop an AFK.md at your project root and afk reads it as the system prompt whenever you run from that directory. No frontmatter needed.

Check what resolved. afk config dumps the live configuration. afk doctor validates keys, paths, and provider connectivity.

Models

Default is sonnet. Override per-call with --model:

afk chat "explain this stack trace" --model opus
afk i --model haiku
afk chat "refactor this" --model codex

| Model | Best for | |---|---| | opus | Complex reasoning, multi-step planning, long contexts | | sonnet | Day-to-day default — balanced speed and capability | | haiku | Fast, cheap, one-shots | | codex | OpenAI's GPT-5 family via @openai/codex-sdk |

Useful commands

afk status               # connection, model, bypass-mode state
afk doctor               # environment self-check
afk config               # dump resolved config
afk plugin list          # installed plugins under ~/.afk/plugins/
afk completion zsh       # shell completion (also: bash, fish)
afk --help               # full command tree

Aliases: afk c → chat, afk i → interactive, afk s → status.

A note on permissions

afk runs with bypass permissions by default: no per-tool prompts. Claude can run bash, read and write files, fetch URLs, and call MCP servers without asking each time. This is intentional — afk is built for unattended work, where a permission prompt with no human in front of it is just a wedged session.

Use afk on a machine and account you trust. Override per-session with --permission-mode if you want stricter behavior.

Troubleshooting

invalid x-api-key / ANTHROPIC_API_KEY not found — run afk doctor. Confirm the key is set in your shell or in ~/.afk/config/afk.env.

Cannot send message: session is closed — the session timed out or was closed. Start a new one (afk i or a fresh afk chat).

Maximum turns exceeded — safety rail tripped. Bump it with --max-turns 50 or higher.

Hit the budget cap — raise AFK_MAX_BUDGET_USD or unset it for the session.

Telegram bot won't start — afk telegram status then afk telegram logs. Most common cause: missing AFK_TELEGRAM_ALLOWED_CHAT_IDS after token setup.

Changelog

Recent releases at CHANGELOG.md, also viewable in-REPL via /changelog.

License

Proprietary. © Griffin Long. All rights reserved.

The agent-afk package on npm is provided as-is for use; the source is not licensed for redistribution, modification, or derivative works. See LICENSE.