Work interactively in the REPL

The REPL is AFK's interactive terminal surface. Use it when you want a conversation that keeps context between prompts, streams model and tool activity, and lets you review or redirect work without leaving the terminal.

Start a sessionCopy Anchor Link

afk i

afk i "Explain how this project is organized"

Common launch options:

See the CLI reference for the complete option list. Worktree exit behavior is configurable: a normal interactive exit asks whether to keep or delete a clean worktree; dirty worktrees are preserved. See Worktrees.

Read the screenCopy Anchor Link

The conversation and completed tool output become scrollback. The live area shows streaming text, active tool lanes, progress, and your input. The bottom status line summarizes the session. Fields that do not apply are omitted, and peripheral fields disappear first in narrow panes.

Use /usage for Claude subscription quota and /cost for this conversation's spend. /tokens breaks down context usage. /limits lists known model context-window limits, it is not the subscription-quota command. See Usage and cost.

Understand activity, parallelism, and waitingCopy Anchor Link

Progress text comes from current tool activity or the model's live thinking clause when available. It includes elapsed time and accumulated tool or token counts rather than merely changing a spinner label. Repeated same-tool activity may collapse into a ×N group to keep the feed readable.

Tool glyphs briefly brighten on completion. A tool-lane badge such as ∥1/3 identifies a member of a parallel dispatch batch; singleton or sequential calls do not get a parallel badge. Nested agent, skill, and compose work is arranged as a tree. Parallel nested dispatches retain their batch badge on the committed completion line, so scrollback still shows that the work ran together.

Before the first response content arrives, a waiting indicator shows elapsed time after a short grace period. Provider backoff appears as rate-limited · retrying… or a retry delay when supplied. This is different from a subscription pause that needs a longer wait or account change.

Read streaming output and changesCopy Anchor Link

Assistant Markdown streams progressively. Open code fences and tables show live previews before the final formatted block is committed. Terminal frame updates use synchronized output where supported to reduce partial-frame flicker; terminals and multiplexers can differ in how smoothly they display it.

Tool lanes show tool names, summarized arguments, and outcomes. Thinking can appear as a collapsed summary or live output according to your thinking UI setting.

File changes are easier to review in place:

• edit_file can show a proposed replacement diff before execution. This is a display preview, not an approval or proof that the edit succeeded. Multi-occurrence replace_all edits skip that preview.
• Completed edit, write, and patch_apply results show colored additions, removals, hunk headers, and change counts when diff data is available. Multi-file patches identify the affected files.
• Set AFK_SHOW_DIFFS=0 to hide inline diff blocks without changing whether tools execute.

Use /diff for the current tracked working-tree changes (staged and unstaged), /diff --staged for staged changes only, or /diff src/index.ts to focus on one path. Large diffs are shortened in the REPL; the default body limit is 60 lines. AFK_DIFF_LINES=0 removes that display limit.

Watch shell output and detach workCopy Anchor Link

While a model-run bash command is active, its lane shows a rolling output tail. By default, the preview keeps the last seven lines and no pinned opening lines. AFK_BASH_PREVIEW_TAIL_LINES and AFK_BASH_PREVIEW_HEAD_LINES change those display counts, not the model's output cap.

For large captured bash output, press Ctrl+G to open the scrollable viewer. It starts near the end. Use arrows or Page Up/Page Down to scroll, g/G for top/bottom, / to search, and n/N for the next/previous match. q closes it. Esc clears an active search first, then closes. A capture must exist: output that fit the model cap may have no saved capture, and retention can remove old captures. The viewer loads at most 20,000 lines.

Ctrl+B during a turn tries these actions in order:

1. Promote a running foreground subagent into a background job.
2. If no subagent is promotable, detach registered in-flight bash or compose calls so they can finish without holding up the immediate tool await.
3. If nothing is eligible, do nothing.

This does not detach the whole conversation turn. Detached tool results arrive later as session input. Background subagents can be inspected with /bgsub, /bgsub:status, /bgsub:join <id>, and /bgsub:cancel <id>. These jobs belong to the session, they are not persistent services. See Background processes and Subagents.

Run your own shell commandCopy Anchor Link

Prefix a prompt with ! to execute it directly without asking the model to run it:

!git status
!ls -la

Use /sh to inspect user-started shell jobs. --no-shell-passthrough or AFK_SHELL_PASSTHROUGH=0 disables this input shortcut. Ctrl+C first aborts a foreground passthrough shell rather than opening the model-turn interrupt menu.

Stop and redirect a turnCopy Anchor Link

Esc soft-stops the active turn and keeps completed work. The progress banner changes to stopping… while teardown finishes, which can take time when child work is active. A second Esc does not restart cancellation. This stop behavior also applies to OpenAI-compatible streaming sessions.

Ctrl+C during a normal TUI turn opens an interrupt picker:

To redirect, choose Stop (or press Esc outside the picker), then send the new instruction. There is no separate Steer option in the current interrupt picker. Without a live TUI compositor, Ctrl+C takes the soft-stop path directly. At an idle prompt, two Ctrl+C presses within 1.5 seconds exit.

Type ahead without losing your draftCopy Anchor Link

You can type while the model is working. Enter commits a non-empty message to the queue and clears the input so you can draft another. The input shows [queued] or [N queued]. Messages normally drain in order, one per completed turn.

With an empty input and no completion menu open, ↑ recalls the newest queued message as an editable draft. Press Enter to queue it again. Backspace does not silently dequeue submitted messages.

Esc preserves both already queued messages and any unsubmitted draft. Text you only typed is not automatically submitted by stopping. Messages submitted during the post-Esc handoff can be coalesced into one redirect, rather than starting several tiny turns.

Handle a subscription pauseCopy Anchor Link

When a supported subscription limit pauses the turn with automatic resumption enabled, the TUI opens a usage-limit picker:

Use arrows and Enter to choose. There is no dedicated C-key action in the current picker. Esc dismisses the picker rather than selecting Stop waiting. Outside the picker, Esc soft-stops the waiting turn; submitting a line during a pause also ends the wait instead of leaving it queued indefinitely.

For Claude subscription sessions, the notice also explains that signing in to another account with claude login in another terminal can let the waiting turn resume automatically on that account. Other providers do not get that Claude-specific instruction. With autoResumeOnUsageLimit: false, or without a live TUI, AFK shows a passive usage notice instead of the interactive waiting picker.

Compose better promptsCopy Anchor Link

Files, completion, and imagesCopy Anchor Link

Type @ followed by a path to complete a file reference. Matches include subsequences, not just prefixes, with prefix matches first. Slash completion also works after whitespace inside a draft, so you can mention a skill in a sentence. Recently used slash commands rank ahead of other matches within their match group.

Use ↑/↓ to select a completion and Tab to insert it without sending. Enter on a slash-command completion completes and submits; Enter on a file or flag completion only inserts the selection. Type -- after a command to request its advertised flag completions.

Press Ctrl+V to attach a clipboard image. On macOS, ordinary Cmd+V can also trigger image detection through terminal paste handling. Linux image paste uses wl-paste on Wayland or xclip on X11 when installed. Clipboard image extraction is not implemented for Windows. With an empty text buffer, Backspace removes the most recently attached image. See Images.

Open an external editorCopy Anchor Link

Press Ctrl+O, or run /editor, to compose a longer prompt. AFK chooses $VISUAL before $EDITOR, seeds a temporary file with your input, and returns a successful edit to the input box for review. It does not send the prompt automatically. A failed editor launch or nonzero exit keeps the original draft. This requires the interactive TUI.

Control ghost suggestionsCopy Anchor Link

Dim ghost text proposes completions from input history and command candidates. When those do not match, an enabled model-backed suggester can complete a prefix after a pause. A separate model-backed proposal can suggest an entire next action at an empty prompt after a turn.

If the engine was disabled at startup, /ghost on cannot create it mid-session. /suggestions shows the last 20 saved inputs, /suggestions 50 shows more, and /suggestions rm 3 or /suggestions clear removes history entries. Begin an input with a space to exclude it from saved input history.

Review and revisit a conversationCopy Anchor Link

Use /search retry to find case-insensitive matches in this session's user prompts and assistant replies. It prints turn numbers and snippets for up to the 20 most recent matching turns. /search --error (or -e) prints the most recent recorded tool error. These commands locate content, they do not move a scrollback cursor.

Use /history to replay conversation output, /history 10 to limit it to recent turns, or /transcript to open the transcript in your pager. Journal-backed replay preserves content blocks, tool cards, and results using the live renderer. Older saves without a journal fall back to a less detailed turn-record replay.

Rewind an earlier promptCopy Anchor Link

Run /rewind to choose an earlier message, then choose whether to rewind the conversation, the files the agent edited, or both. A conversation rewind loads that prompt's text into your input; edit it, then press Enter to start the revised branch. A file rewind previews every file before restoring. Pressing Esc twice at an empty, idle prompt runs a conversation-only rewind. Rewind cannot run while a turn is active.

File rewind covers the agent's write_file, edit_file, and patch_apply edits, not shell commands. See the undo guide.

Copy useful outputCopy Anchor Link

Clipboard copying requires the interactive REPL and a TTY. AFK tries local clipboard utilities first, then OSC 52 through the terminal, useful over SSH. Your terminal must permit OSC 52; AFK cannot confirm that an OSC 52 write reached the clipboard.

Resume saved workCopy Anchor Link

Run /resume for a searchable picker with relative save times, model, turn count, cost, and session name. If this directory has saved sessions, only those appear; if none exist here, the picker falls back to all directories. You can also run /resume <name-or-id> directly.

Type to fuzzy-filter the list, use arrows to select, then press Enter for a conversation preview. Confirm with Enter or cancel with Esc. The preview shows up to ten recent stored turns with shortened text and tool summaries. Once resumed, AFK replays the conversation, preferring the full journal when available. The active session cannot be swapped while a turn is running.

For startup resumption, use afk i --continue or afk i --resume <id>. /name gives a session a memorable label, and /fork creates an independent conversation from the current one. See Sessions and context.

Change models, settings, and instructionsCopy Anchor Link

/model opens an arrow-key picker of model slots, identity aliases, and curated OpenAI model IDs. You can also type a full model ID or org/model directly. /model <name> switches the running session and retains its conversation context.

The non-TUI model listing marks unavailable aliases with needs sign-in. The current interactive picker does not display those auth labels, so appearing in the picker does not prove a model is authenticated. See Models and providers.

/config opens the settings menu. Choose a category, setting, then value; Esc backs out a level. Rows show resolved values and their configuration source so you can spot overrides. model and theme can apply live; other edits report when a restart is needed. /config view is read-only, and /config set <key> <value> is the direct editing path for supported keys. See Edit configuration.

/afk-md shows the personal and project instruction overlays. /afk-md project or /afk-md user opens one in your editor and attempts a live reload after a successful save. /afk-md reload rereads external edits. The command reports when a higher-priority prompt shadows the file or a provider needs a new launch; successful live changes affect your next message. This edits standing instructions, not the separate cross-session memory archive. See AFK.md.

Fast modeCopy Anchor Link

/fast reports the current preference and whether it is effective. /fast on and /fast off take effect on the next turn. Fast mode is off by default, applies to the main session only, and excludes custom or local endpoints. Eligible Anthropic Opus models use fast mode; eligible OpenAI models use the priority tier. An unsupported model leaves the preference on but inactive, with a reason shown by /fast. Provider eligibility and billing still apply.

Plan safely and manage tasksCopy Anchor Link

Shift+Tab cycles default → plan → bypassPermissions → default. In autonomous mode it exits AFK and lands on default; it never enters AFK. Use /afk to enter autonomous operation. The status line and transient mode notice show the active mode.

/plan on enters a read-only planning conversation: writes and mutating shell commands are refused, while read-only investigation runs. /plan off returns to default mode and starts a turn to save the plan under .afk/plans/ and implement it. Shift+Tab changes modes without seeding implementation.

When the agent proposes leaving plan mode, its approval picker lets you restore the previous mode, explicitly choose bypass when different, keep planning, or type revision feedback. Free-text feedback is not approval. Approval schedules a separate save-and-implement turn; writes remain blocked for the rest of the current planning turn.

Use /tasks to browse subagents and Enter to view a selected task. During streaming, Tab can open the newest running subagent's live view if no completion menu takes precedence. Type a message and Enter there to send it to that child, or Esc to return to the parent view.

Other slash-command highlights, grouped by task:

/goal stores a project-scoped objective across sessions; changes are saved immediately but enter the model's standing context at the next session start. /todo manages this session's durable checklist. /spine manages the git-tracked SPINE.md architecture manifest, including its invariants and rejected patterns. See Goal tracking, State store, and Spine.

Use /allow-dir to authorize another directory, or revoke a grant with its --revoke option. There is no /bypass command, use the permission cycle when you deliberately want bypass mode.

Use /help and the slash-command reference for the full list and arguments. See Skills for skill workflows.

Tune the terminalCopy Anchor Link

Themes and reading widthCopy Anchor Link

Choose dark, light, umber, or auto with --theme, AFK_THEME, the theme config key, or /theme during a session. auto uses COLORFGBG and falls back to dark; it never selects umber. /theme light restyles the active frame and future output, not existing scrollback. Persist a choice with afk config set theme light.

Prose normally wraps at 80 columns and wider unbordered content, including code, at 100. AFK_PROSE_MEASURE changes prose width. An explicitly set AFK_TEXT_MEASURE overrides it for compatibility. Set AFK_TEXT_MEASURE=full to use the terminal's full width. Width controls affect display, not model behavior.

Titles, notifications, and upgradesCopy Anchor Link

On a TTY, AFK sets the terminal title to include the project and adds running during turns. AFK_TERM_TITLE=0 leaves your title alone. Completion notifications through OSC 9 are opt-in with AFK_NOTIFY=1 and require terminal support.

If AFK is upgraded while this REPL is running, a notice identifies the installed and running versions. The running process does not restart automatically. Save your work and restart the session to load the new version.

tmux and plain outputCopy Anchor Link

For tmux, these settings reduce Escape latency and improve colors, clipboard support, and modified Enter handling:

set -sg escape-time 10
set -g default-terminal "tmux-256color"
set -as terminal-features ",*:RGB"
set -g set-clipboard on
set -g extended-keys on

With tmux's default Ctrl+B prefix, press Ctrl+B twice to send the detach shortcut through to AFK. OSC 52 clipboard writes use tmux's native clipboard forwarding; they do not require allow-passthrough. If auto theme detection is wrong inside tmux, select a theme explicitly. On Node 22 or 24, FORCE_COLOR=3 can help when tmux incorrectly reports only 256-color support.

If cursor redraws misbehave over tmux or SSH, start with plain output:

AFK_PLAIN_OUTPUT=1 afk i

This replaces live overlays and the rich input box with simpler line-oriented output and input. Tool completions and subagent lifecycle events still print concise progress lines. On a real terminal, a static waiting notice disappears when content starts; redirected output omits that waiting notice. Do not expect TUI pickers, ghost text, image-paste controls, or the normal compositor key bindings in plain mode.

RelatedCopy Anchor Link