Quickstart

Install Agent AFK, set your API key, and run your first command in under two minutes.

Prerequisites

Node.js ≥ 22 — check with node --version
An Anthropic API key (or run claude login for browser-based OAuth)

Install

npm install -g agent-afk

Confirm the binary is on your PATH:

afk --version

To update to the latest published version at any time:

afk update              # installs latest via npm install -g
afk update --check      # check for a newer version without installing
afk update --pin 1.2.3  # install a specific semver instead of latest

afk upgrade is an alias for afk update.

Set your API key

The simplest path is an environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Add that line to your shell profile (~/.zshrc, ~/.bashrc, etc.) to make it permanent.

Alternatively, write it to Agent AFK's env config file so it's scoped to afk only:

echo "ANTHROPIC_API_KEY=sk-ant-..." >> ~/.afk/config/afk.env

Or keep the key out of your shell history with a masked prompt:

afk config env set ANTHROPIC_API_KEY   # prompts without echoing the value

Or use the OAuth flow (no API key required — authenticates via console.anthropic.com):

claude login

Smoke test

Verify the installation and provider connectivity:

afk chat "hello"
afk doctor       # environment self-check: Node version, API key, paths, config

afk doctor will flag any missing keys, path problems, or provider connectivity issues.

Your first session

For a one-shot question:

afk chat "summarise the last 10 git commits in this repo"

For an interactive REPL with full tool access (bash, file ops, web fetch, subagents):

afk i

Inside the REPL, type a message and press Enter. Use /help to list slash commands.

afk i is an alias for afk interactive. The REPL is the default command — running afk with no subcommand also starts the REPL.

Choose a model

The default model is the medium capability tier — Claude Sonnet on an unconfigured install. Override per-command:

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

Alias	Description
`fable`	Most capable — hardest reasoning, 1M context
`opus`	Complex reasoning, multi-step planning
`sonnet`	Balanced speed and capability
`haiku`	Fast and cheap, good for simple tasks

Coming from Claude Code or Codex?

If you already have plugins, skills, or MCP servers installed in Claude Code or Codex, import them into AFK with a single command:

afk migrate             # auto-detects Claude Code and Codex; prompts before writing
afk migrate --dry-run   # preview what would be imported without changing anything
afk migrate --mcp       # also import MCP servers (discloses each server's command first)
afk migrate -y          # skip the confirmation prompt (CI / non-interactive)

Rather than copying files, afk migrate records a trust grant in afk.config.json. AFK then live-reads the source tool's directories every session — plugins installed in Claude Code tomorrow appear in AFK tomorrow without re-running the command. MCP import is opt-in (--mcp) because MCP servers auto-run a command on session start.

Next steps

How It Works — session lifecycle, provider routing, terminal states
Interactive REPL — slash commands, plan mode, background tasks
One-Shot Chat — pipe-friendly, headless streaming
Daemon — cron scheduling, unattended runs
Telegram — bot setup and supervision

Quickstart

On this page