CLI Reference

Sessions

`afk` / `afk interactive`

Start an interactive REPL session. This is the default command — running afk alone launches it.

Alias: afk i

afk [input...]
afk interactive [input...]

An optional positional argument is auto-submitted as the first turn (prompt or slash command):

afk "explain this codebase"
afk /review

Flag	Description
`-m, --model <model>`	Model to use. Short aliases: `opus`, `opus_1m`, `sonnet`, `sonnet_1m`, `haiku`.
`--max-turns <number>`	Maximum conversation turns (default: 100).
`--thinking <mode>`	Thinking mode: `adaptive` \| `disabled` \| `max` \| `enabled:<N>`
`--thinking-ui <mode>`	How thinking blocks render: `summary` \| `live` \| `digest` \| `off` (default: `live`).
`--theme <mode>`	Color palette: `dark` \| `light` \| `umber` \| `auto`.
`--effort <level>`	Effort level: `low` \| `medium` \| `high` \| `xhigh` \| `max`
`-w, --worktree [branch]`	Create an isolated git worktree for the session.
`--worktree-on-exit <ask\|keep\|remove>`	Clean-worktree exit policy (default: ask on TTY).
`--no-worktree-autoname`	Disable auto-naming worktrees from the first message.
`--worktree-base <ref>`	Base git ref for the worktree (default: remote default branch).
`--resume <id>`	Resume a persisted session by id.
`--continue`	Continue the most recent persisted session in the current directory.
`--debug`	Show SDK init metadata and enable the `/debug` command.
`--no-shell-passthrough`	Disable the `!` shell passthrough feature.
`--plain`	Force plain append-only output (disables the live compositor).
`--provider <name>`	Provider override: `anthropic` \| `openai` \| `xai` \| ...
`--mcp-config <path>`	Additional MCP config file (highest priority).
`--dump-prompt [path]`	Dump the resolved system prompt to a file or `stderr`.
`--dangerously-skip-permissions`	Skip path-approval prompts (bypass mode).

`afk chat`

Send a single message and exit (one-shot, non-interactive).

Alias: afk c

afk chat "What is 2+2?"
echo "summarize this" | afk chat -
afk chat --format stream-json "explain async/await"

Flag	Description
`[message]`	Message to send. Use `-` or omit to read from stdin.
`-m, --model <model>`	Model to use.
`-f, --format <format>`	Output format: `text` \| `json` \| `stream-json` (default: `text`).
`--max-turns <number>`	Maximum conversation turns (default: 10).
`--thinking <mode>`	Thinking mode.
`--effort <level>`	Effort level.
`--theme <mode>`	Color palette.
`--max-budget-usd <usd>`	Hard cost ceiling in USD. Env: `AFK_MAX_BUDGET_USD`.
`--task-budget <tokens>`	Soft per-task token budget. Env: `AFK_TASK_BUDGET`.
`--max-output-tokens <n\|max>`	Per-response output cap. Env: `AFK_MAX_OUTPUT_TOKENS`.
`-w, --worktree [branch]`	Isolated git worktree for this one-shot run.
`--worktree-base <ref>`	Base git ref for the worktree.
`--resume <id>`	Resume a persisted session by id.
`--continue`	Continue the most recent persisted session.
`--session-id <uuid>`	Assign a specific UUID to this session.
`--post <targets>`	Publish the final response: `github`, `telegram`, or `github,telegram`.
`--post-pr <ref>`	PR number, URL, or branch for `--post github`.
`--provider <name>`	Provider override.
`--mcp-config <path>`	Additional MCP config file.
`--dump-prompt [path]`	Dump the resolved system prompt.
`--dangerously-skip-permissions`	Skip path-approval prompts.

`afk daemon`

Run agent-afk as a headless daemon that fires scheduled tasks on a cron expression or session-start trigger.

afk daemon --cron "0 */6 * * *" --task "/forge-friction --auto"
afk daemon --trigger sessionstart
afk daemon --trigger pull
afk daemon --once

Flag	Description
`-p, --port <number>`	Control HTTP port (default: 7777).
`--host <address>`	Bind address for the control surface (default: 127.0.0.1).
`-t, --task <command>`	Command to fire on each tick.
`-c, --cron <expression>`	Cron expression (required when `--trigger` includes `cron`).
`-i, --task-id <id>`	Task identifier.
`--trigger <mode>`	Trigger mode: `cron` \| `sessionstart` \| `both` \| `pull`.
`--once`	Fire one tick and exit (for testing).
`--timeout-ms <ms>`	Per-tick session timeout. Env: `AFK_TIMEOUT_MS`.
`--thinking <mode>`	Thinking mode for daemon sessions.
`--effort <level>`	Effort level for daemon sessions.
`--sessionstart-cooldown-ms <ms>`	Cooldown between sessionstart fires (default: 6h).
`--dump-prompt [path]`	Dump the resolved system prompt.

`afk web`

Serve a local web UI for live agent sessions.

afk web
afk web --port 4141 --no-open

Flag	Description
`-p, --port <port>`	Port to listen on (default: 4141, or `AFK_WEB_PORT`).
`-H, --host <host>`	Bind address (default: 127.0.0.1, or `AFK_WEB_HOST`).
`--token <token>`	Bearer token (default: randomly minted per run).
`--no-open`	Do not open a browser window.
`-m, --model <model>`	Model for sessions started from the browser.
`--bypass-permissions`	Run browser-started sessions without tool approvals.

`afk farm`

Run a task across N speculative git worktree branches in parallel, then rank the results.

afk farm "add type-safe API client" --branches 3
afk farm "optimize the parser" -n 4 --model opus

Flag	Description
`<task>`	Task description to run on each branch (required).
`-n, --branches <number>`	Number of branches to spawn, 1–16 (default: 3).
`--labels <labels>`	Comma-separated branch labels (count must equal `--branches`).
`-m, --model <model>`	Model to use.
`--base-ref <ref>`	Base git ref (default: HEAD).
`--cwd <path>`	Source repo root (default: `process.cwd()`).
`--fail-fast`	Abort remaining branches on first failure.
`--no-score`	Skip the post-run scorer (tests + lint + LoC).
`--score-timeout <ms>`	Per-branch test timeout in ms.
`--no-memory`	Skip writing the farm-run fact to cross-session memory.
`--no-digest`	Skip pushing the Telegram digest on completion.

Configuration

`afk config`

View or edit AFK configuration (afk.config.json and afk.env).

afk config                          # show effective config
afk config get model                # read one key
afk config set model opus           # write a key
afk config unset model              # remove a key
afk config env get AFK_EFFORT       # read an env var
afk config env set AFK_EFFORT high  # write an env var
afk config env unset AFK_EFFORT     # remove an env var

afk config

Flag	Description
`-f, --format <format>`	Output format: `text` \| `json` (default: `text`).

afk config get [key] — Read afk.config.json. Omit key to print the whole file.

Flag	Description
`--json`	Output raw JSON.

afk config set <key> <value> — Set an afk.config.json key (dotted path).

Flag	Description
`--json`	Output result as JSON.

afk config unset <key> — Remove an afk.config.json key.

afk config env get [key] — Read afk.env. Omit key to list all present vars (secrets masked).

Flag	Description
`--all`	Include every known var, not just those currently set.
`--json`	Output raw JSON.

afk config env set <key> [value] — Set an afk.env var. Secret vars are prompted (masked).

Flag	Description
`--stdin`	Read the value from stdin (for scripted secret entry).
`--json`	Output result as JSON.

afk config env unset <key> — Remove an afk.env var.

Save an Anthropic API key or OAuth token.

afk login
afk login sk-ant-api...

Anthropic-only. For OpenAI-backed models, use OPENAI_API_KEY or codex login.

`afk status`

Check agent connection status.

Alias: afk s

afk status
afk status --format json

Flag	Description
`-f, --format <format>`	Output format: `text` \| `json` (default: `text`).

Import plugins, skills, and MCP servers from Claude Code or Codex into AFK. Records a live-read trust grant in afk.config.json — assets from the trusted binary show up automatically on every session without copying files.

afk migrate
afk migrate claude-code
afk migrate --mcp --dry-run

Flag	Description
`[binary]`	Source binary: `claude-code` \| `codex`. Auto-detects if omitted.
`--from <binary>`	Alternative way to specify the source binary.
`--dry-run`	Show what would be imported without writing config.
`--mcp`	Also import MCP servers (off by default — discloses each command first).
`-y, --yes`	Apply without the interactive confirmation.

`afk update`

Update agent-afk to the latest published version.

Alias: afk upgrade

afk update
afk update --check
afk update --pin 1.2.3

Flag	Description
`--check`	Only check whether an update is available; do not install.
`--pin <version>`	Install a specific version instead of latest (semver).

`afk completion`

Emit a shell completion script.

eval "$(afk completion zsh)"
afk completion bash >> ~/.bashrc

afk completion <shell>

Supported shells: zsh, bash, fish.

`afk shell-init`

Emit the optional shell wrapper that auto-cds the parent shell into a preserved worktree when afk exits.

eval "$(afk shell-init)"              # bash / zsh (add to ~/.bashrc or ~/.zshrc)
afk shell-init fish | source -        # fish

Argument	Description
`[shell]`	Target shell: `bash` \| `zsh` \| `fish`. Auto-detected from `$SHELL` if omitted.

`afk telegram`

Manage the Agent AFK Telegram bot.

afk telegram setup — Interactive setup: validate bot token, discover chat ID, persist to ~/.afk/config/afk.env.

afk telegram start — Start the bot as a background daemon.

afk telegram stop — Stop the bot (SIGTERM, then SIGKILL after 5 seconds).

afk telegram restart — Stop and restart the bot.

afk telegram status — Show running state, uptime, memory, and recent log entries.

afk telegram logs — Show or follow the bot log.

Flag	Description
`-f, --follow`	Stream new log entries (like `tail -f`).
`-n, --lines <count>`	Number of trailing lines to show (default: 50).

afk telegram check-token — Validate TELEGRAM_BOT_TOKEN via getMe. Emits JSON {set, valid, username?, botId?, reason?}.

afk telegram discover-chat — Poll getUpdates for chats that have DM'd the bot.

Flag	Description
`--timeout-sec <n>`	How long to poll before giving up (default: 60).

afk telegram set-allowed-chat <chatId> — Persist AFK_TELEGRAM_ALLOWED_CHAT_IDS=<chatId> to afk.env.

Plugins

`afk plugin`

Manage AFK plugins.

afk plugin install <source> [name] — Install a plugin from a git URL, owner/repo shorthand, local path, or <marketplace>:<plugin>.

Flag	Description
`-r, --ref <ref>`	Install a specific tag, branch, or SHA.
`-f, --force`	Replace an existing plugin with the same name.
`-y, --yes`	Skip the install warning (non-interactive / CI).

afk plugin update [name] — Update one plugin, or all if no name is given.

Flag	Description
`-r, --ref <ref>`	Pin to a specific ref instead of the latest tag.

afk plugin list — List installed plugins with source, version, and enabled state.

Flag	Description
`-f, --format <format>`	Output format: `text` \| `json` (default: `text`).

afk plugin remove <name> — Remove a plugin (directory + index entry).

afk plugin enable <name> — Re-enable a previously disabled plugin.

afk plugin disable <name> — Keep the plugin on disk but skip it at session init.

Marketplace

`afk marketplace`

Manage AFK plugin marketplaces.

afk marketplace install <source> [name] — Clone or symlink a marketplace into the local plugin cache.

Flag	Description
`-r, --ref <ref>`	Install a specific tag, branch, or SHA.
`-f, --force`	Replace an existing marketplace with the same name.

afk marketplace list — List installed marketplaces with source and ref.

Flag	Description
`-f, --format <format>`	Output format: `text` \| `json` (default: `text`).

afk marketplace plugins <name> — List plugins inside a marketplace with [installed] / [available] markers.

Flag	Description
`-f, --format <format>`	Output format: `text` \| `json` (default: `text`).

afk marketplace install-plugin <marketplace> <plugin> — Install a single plugin from a marketplace.

Flag	Description
`-r, --ref <ref>`	Pin to a specific tag, branch, or SHA.
`-f, --force`	Replace an existing plugin with the same key.
`-y, --yes`	Skip the install warning.

afk marketplace remove <name> — Remove a marketplace and cascade-delete its installed plugins.

afk marketplace update [name] — Update one marketplace, or all if no name is given.

Flag	Description
`-r, --ref <ref>`	Pin to a specific ref instead of the latest tag.

Scheduling

`afk schedule`

Manage scheduled daemon tasks (persisted in ~/.afk/config/schedules.json). Write operations attempt live-sync to a running daemon.

afk schedule add — Add a new scheduled task.

Flag	Description
`--name <name>`	Human-readable label (required).
`--command <cmd>`	Command to run (required).
`--cron <expr>`	5-field cron expression (required).
`--trigger <mode>`	`cron` \| `sessionstart` \| `both` (default: `cron`).
`--notify <when>`	`failure` \| `always` \| `never` (default: `failure`).
`--disabled`	Add in disabled state.

afk schedule list — List all scheduled tasks.

afk schedule remove <id> — Permanently remove a scheduled task.

afk schedule enable <id> — Enable a scheduled task.

afk schedule disable <id> — Disable a scheduled task.

afk schedule logs <id> — Show recent execution history for a task.

Flag	Description
`-n, --limit <n>`	Number of records to show (default: 10, max: 50).

`afk queue`

Manage the pull-trigger task queue (used with afk daemon --trigger pull). Tasks are persisted as JSON files in ~/.afk/state/queue/.

afk queue add <command> — Enqueue a command for the pull-trigger daemon to execute.

Flag	Description
`--notify-on <mode>`	When to notify: `failure` \| `always` \| `never`.

afk queue list — List all pending queued tasks in FIFO order.

afk queue remove <id> — Remove a pending task by id.

afk queue clear — Remove all pending tasks from the queue.

Flag	Description
`-y, --yes`	Skip the confirmation prompt.

Services

`afk service`

Manage AFK background services using OS-supervised process managers (launchd on macOS, systemd --user on Linux). Services auto-start on login and relaunch on crash.

Supported service names: telegram, daemon.

afk service install <name> — Install a service so it starts on login and relaunches on crash.

Flag	Description
`--no-watch`	Disable auto-restart on rebuild.
`--dry-run`	Write the config file but do not register with the supervisor.

afk service uninstall <name> — Stop the service and remove its config.

afk service status [name] — Show running PID, last exit status, and log file for one or all services.

afk service list — List all recognised service names and whether each is installed.

afk service restart <name> — Restart the service.

afk service upgrade <name> — Re-render the service config and atomically replace it if it has drifted (e.g. after a version upgrade).

Flag	Description
`--no-watch`	Disable auto-restart on rebuild.

Observability

`afk trace`

Inspect the witness-layer trace of a session — the durable NDJSON record of everything the agent did. Reads from ~/.afk/state/witness/<session>/trace.jsonl.

afk trace show [session] — Pretty-print a session's trace. session defaults to latest.

Flag	Description
`--all`	Include low-signal events (latency phases, paired tool starts).
`--json`	Emit the raw NDJSON unchanged (for piping to `jq`).
`-n, --limit <number>`	Show only the last N events.

afk trace list — List sessions that have a trace, most recent first.

Flag	Description
`-n, --max <number>`	Maximum sessions to show (default: 20).

`afk witness`

Programmatic access to witness trace events (structured JSON output for tooling).

afk witness read [session] — Read and filter events from a session trace (default: latest).

Flag	Description
`-k, --kinds <kinds>`	Comma-separated event kinds to filter by.
`-t, --tool <name>`	Filter `tool_call` events to this tool name.
`-e, --errors`	Show only error events.
`-n, --limit <number>`	Max events to return (default: 50, max: 200).
`--json`	Emit raw JSON.

afk witness search <query> — Text-search across recent sessions' traces.

Flag	Description
`-n, --sessions <number>`	Number of recent sessions to scan (default: 20).
`-k, --kinds <kinds>`	Comma-separated event kinds to filter by.
`--since <date>`	Only search sessions modified after this ISO date.
`--json`	Emit raw JSON.

`afk transcript`

Search and index session transcripts. Transcripts are autosaved Markdown files under ~/.afk/state/transcripts/. Run afk transcript reindex once before searching.

afk transcript reindex — Build (or rebuild) the FTS5 full-text index from all transcript files on disk. Safe to run repeatedly.

afk transcript search <query> — Search indexed transcripts via FTS5 full-text search. Supports "exact phrase", term*, AND, OR.

Flag	Description
`-n, --limit <number>`	Maximum results to return, 1–1000 (default: 10).

`afk bg`

Inspect persisted background subagent job logs from ~/.afk/state/bg/<jobId>/. Background jobs are tied to the parent REPL process — this command reads the persisted log after the fact.

afk bg list — List background jobs from disk, most recent first.

Flag	Description
`-n, --max <number>`	Maximum jobs to show (default: 20).

afk bg tail <jobId> — Stream events from a background job log.

Flag	Description
`--from-start`	Replay all history before following new events.
`--no-follow`	Exit after replaying existing events; do not wait for new ones.

afk bg replay <jobId> — Replay all persisted events for a background job (alias for tail --from-start --no-follow).

`afk captures`

Inspect bash output captures (tool output stored during sessions).

afk captures list — List recent bash output captures, newest first.

Flag	Description
`--session <id>`	Filter to a specific session id.
`-n, --limit <number>`	Maximum entries to show (default: 20).
`--json`	Emit raw JSON.

`afk insights`

Generate a local usage analytics report from AFK telemetry. Produces a self-contained HTML file and opens it in a browser.

afk insights
afk insights --days 7 --no-open

Flag	Description
`--days <n>`	Lookback window in days (default: 30).
`--output <path>`	Output file path for the HTML report.
`--no-open`	Do not open the report in a browser after generation.

Worktrees

`afk worktree`

Manage git worktrees created by afk.

afk worktree list — List all afk-managed worktrees and show prune candidates (dry-run only). Displays path, owner, age, status, and whether the worktree would be pruned.

afk worktree prune — Remove stale, empty, and orphaned worktrees.

Flag	Description
`--apply`	Execute removals (default is dry-run).
`--max-age-days-clean <n>`	Max age (days) for clean worktrees before removal.
`--max-age-days-dirty <n>`	Max age (days) for dirty worktrees before warning.
`--scope <scope>`	`interactive` \| `diagnose` \| `all` (default: `all`).

Browser

`afk browser`

Give the agent web hands: connect your real Chrome, or save a login session it can reuse.

afk browser connect — Wire chrome-devtools-mcp (--autoConnect) so the agent can drive your real, logged-in Chrome. Writes to ~/.afk/config/mcp.json. Requires Chrome ≥ 144.

Flag	Description
`--channel <channel>`	Chrome channel: `stable` \| `beta` \| `canary` \| `dev` (default: `stable`).

afk browser disconnect — Remove the chrome-devtools server from your MCP config.

afk browser login <url> — Open a headed browser, log in manually, and save the session to a vault profile the agent's native browser tools reuse.

Flag	Description
`--profile <name>`	Vault profile name (default: `default`).

afk browser profiles — List saved browser session-vault profiles.

Provider

`afk provider`

Provider diagnostics and configuration.

afk provider auth diagnose — Inspect which auth source will be used for the current model and provider.

Flag	Description
`-f, --format <format>`	Output format: `text` \| `json` (default: `text`).

afk provider xai login — Authenticate with SuperGrok / SuperGrok Heavy / X Premium+ OAuth for Grok models.

Flag	Description
`--device-code`	Use RFC 8628 device-code flow (default).
`--browser`	Use browser PKCE loopback on `127.0.0.1:56121`.

afk provider xai logout — Clear stored SuperGrok / X Premium+ OAuth tokens.

Self-Improvement

`afk improve`

Self-improvement pipeline: scan witness traces for patterns, triage failure cards, draft proposals, and generate replay eval-cases. No LLM calls are made by any subcommand unless explicitly noted.

afk improve scan — Scan witness traces, run every registered detector, and print a summary.

Flag	Description
`--since <duration>`	Lookback window (e.g. `7d`).
`--write`	Persist cards to disk (default: dry-run).
`--min-repeats <n>`	Minimum occurrences before a card is written.
`--only <name,...>`	Comma-separated list of detector names to run.

afk improve cards list — Tabular listing of all pattern cards on disk.

Flag	Description
`--pattern`	Filter by pattern name.
`--severity`	Filter by severity.
`--status`	Filter by status (open / deferred / resolved).
`--regressed`	Narrow to resolved/deferred cards that fired again after triage.
`--json`	Output raw JSON.

afk improve cards show <slug> — Print one card.

Flag	Description
`--json`	Output raw JSON.

afk improve cards triage <slug> — Append a human note and/or change the card's status.

Flag	Description
`--note "..."`	Human note to append (required).
`--status <state>`	`open` \| `deferred` \| `resolved`.

afk improve propose <slug> — Generate a template-mode improvement proposal for the card.

Flag	Description
`--id <override>`	Override the generated proposal id.
`--json`	Output raw JSON.

afk improve proposals list — Tabular listing of proposals.

Flag	Description
`--card <slug>`	Filter to a specific card.
`--risk <l\|m\|h>`	Filter by risk level.
`--json`	Output raw JSON.

afk improve proposals show <id> — Print one proposal.

Flag	Description
`--json`	Output raw JSON.

afk improve eval-gen <cardSlug> — Generate a replay-mode eval-case for a failure card. Slices a fixture from the source witness trace. No LLM calls.

Flag	Description
`--proposal <id>`	Associate with a proposal.
`--evidence-row <i>`	Which evidence row to use.
`--id <override>`	Override the generated eval-case id.
`--json`	Output raw JSON.
`--no-write`	Preview without writing to disk.

afk improve eval-cases list — Tabular listing of eval-cases.

Flag	Description
`--card <slug>`	Filter to a specific card.
`--pattern <name>`	Filter by pattern name.
`--status <state>`	Filter by status.
`--json`	Output raw JSON.

afk improve eval-cases show <id> — Print one eval-case (Markdown view by default).

Flag	Description
`--json`	Output raw JSON.

afk improve eval-run <id> — Run the deterministic validation contract for an eval-case against the live codebase. Accepts an eval-case id or card slug (uses the most recent eval-case). No LLM calls.

Flag	Description
`--id <override>`	Override the generated run id.
`--json`	Output raw JSON.
`--no-write`	Preview without writing to disk.

CLI Reference

On this page