Interactive REPL

The interactive REPL is Agent AFK's primary surface. Launch it with:

afk i
# or
afk interactive
# or just
afk          # interactive is the default command

The REPL gives you a persistent session with full tool access — bash, file ops, web fetch, subagents, MCP servers, memory — plus slash commands for built-in and plugin skills.

Common options

afk i --model opus           # pick a model
afk i --max-turns 200        # raise the turn limit (default 100)
afk i --resume <id>          # resume a saved session
afk i --continue             # continue the most recent session in cwd
afk i -w                     # create a git worktree for isolation
afk i -w my-feature          # worktree on a named branch
afk i --mcp-config ./mcp.json  # load an additional MCP config

Slash commands

Type / in the REPL to see available commands. Typos are caught automatically — type /mnt and AFK suggests /mint.

Session control

Information

Permissions

There is no /bypass command — cycle into bypassPermissions with Shift+Tab (the REPL shows a ⚠ BYPASS badge while it is active). See Permissions for the full model behind these commands.

Planning and state

Background tasks

Press Ctrl+B to background a running foreground subagent (there is no whole-turn detach). The status bar at the bottom of the REPL shows running background-subagent counts.

Built-in skills

Plugins and discovery

Plan mode

/plan opens an in-REPL plan editor. You can write a multi-step plan, iterate on it, and then let the agent execute it. Plan state is saved to ~/.afk/state/ and survives session restarts.

Exiting plan mode

When the model judges its plan ready, it calls the exit_plan_mode tool. This presents a three-choice picker:

The mode flip is deferred to the start of the next turn — the gate stays locked in plan mode for the remainder of the current turn. On approval, the model is instructed to first save the plan to .afk/plans/ as a markdown file, then implement it.

You can also exit plan mode manually with /plan off.

Shift+Tab permission cycle

Press Shift+Tab at any time to cycle the active permission mode. The cycle order is:

default → plan → bypassPermissions → default (wraps)

Each press advances one step and prints a one-line status message. If the session is already in autonomous (AFK) mode, Shift+Tab exits AFK and lands on default — the key never enters AFK. Use /afk to enter autonomous mode.

See Permissions for full mode descriptions.

Streaming output

The REPL streams model output token-by-token with markdown rendering. Tool calls render as collapsible lane entries showing the tool name, arguments, and result. Extended thinking renders as a summary lane (or live, depending on --thinking-ui).

Type-ahead and queueing

You don't have to wait for the agent to finish a turn before typing your next message. Press Enter on a non-empty buffer while a turn is in flight and the message is queued — the input clears so you can draft the next one. The input line shows [queued] for one pending message or [N queued] for several.

Queued messages drain in order (FIFO), one per completed turn. To revise the message you most recently queued, press ↑ (Up arrow) on an empty buffer: the last queued message pops back into the input as an editable draft (non-destructive). Backspace does not dequeue — committed type-ahead is only ever recalled for editing with ↑, never silently discarded.

Usage limits

When your Claude subscription hits its hourly limit mid-session, the REPL shows a usage-limit notice rather than failing the turn. By default AFK auto-resumes when the limit resets — you don't need to retype anything. The notice also lists the actions you can take right now:

• Switch model — type /model <name> then Enter to continue on a different model.
• Switch account — run claude login in any terminal; the session resumes automatically.
• Stop waiting — press Esc.

Set autoResumeOnUsageLimit: false in afk.config.json to opt out of automatic resume (the notice then prompts you to resend, switch to API-key billing, or re-auth). The /limits command shows current rate-limit and budget state at any time.

Worktree isolation

-w / --worktree creates a git worktree for the session. Every bash command and file operation the agent runs lands in the isolated worktree, not your main working tree. On a clean exit (no uncommitted changes), the worktree and branch are removed automatically. On a dirty exit, the worktree is preserved so you can review or commit the changes.

afk i -w                     # auto-named worktree
afk i -w my-feature          # named branch
afk i -w --worktree-base HEAD  # base on local checkout instead of origin/main

Shell passthrough

Prefix a line with ! to run it directly in your shell without sending it to the model:

> !ls -la
> !git status

Disable with --no-shell-passthrough or AFK_SHELL_PASSTHROUGH=0.

Session persistence

Sessions are saved to ~/.afk/state/sessions/. Resume from the REPL with /resume, or at startup:

afk i --resume <session-id>
afk i --continue              # most recent session in cwd

/resume lists sessions saved from the current working directory first — so the picker in a project shows that project's sessions, not every session on the machine. When no session was saved from the current directory, it falls back to listing all saved sessions.