Interactive mode

This is the reference for working inside a live Claude Code session in the terminal: what every key does, how input modes work, and the smaller features that make long sessions pleasant. Launch flags are on the CLI reference and / commands on Commands. To change bindings, see Keybindings.

Note: Shortcuts vary a little by terminal and platform. On macOS, the Alt shortcuts (Alt+B, Alt+F, Alt+D, Alt+Y, Alt+P) need your terminal to treat Option as Meta; Terminal configuration shows the setting for each terminal. In fullscreen rendering, press ? in the transcript viewer for the shortcuts available there.

Keyboard shortcuts

Controlling the session

Editing text

Word-based shortcuts (Alt+B, Alt+F, Alt+D, Option+Delete, Ctrl+Backspace) treat a word as letters and digits, so _, . and / split words: with lib/vat/rates.ts, repeated Alt+B stops at ts, rates, vat and lib. Ctrl+W ignores punctuation and goes back to whitespace. Text without spaces (Chinese, Japanese) still moves a word at a time. These readline conventions apply from v2.1.261; the old keybindingFlavor setting no longer does anything, and these shortcuts cannot be remapped.

Inside the /theme picker only, Ctrl+T toggles syntax highlighting for code blocks.

New lines

Prefixes

In the transcript viewer

/tui with no argument tells you which renderer you are in.

Voice

Hold Space to dictate, or use /voice tap for tap-to-toggle, once voice dictation is enabled. The key can be rebound.

The command menu

Typing / lists built-in commands, bundled and personal skills, plugin commands and MCP prompts. Some commands are hidden by design and only run when typed in full; Commands explains the matching rules. In fullscreen, the / and @ lists respond to the mouse too.

Completing a command mid-prompt

You can complete a command name partway through a message: type a space, /, and the first letters, as in fix the lint errors then /simp. Only names starting with those letters match, so a path like /var/log will not leave a list open. Remember a command only runs if it starts the message.

• Fullscreen: matches appear as a list with nothing highlighted, so Enter still sends your text. Tab inserts the top match, or choose with the arrows and Enter.
• Classic: the rest of the top match appears as ghost text with a count like +2. Tab inserts a single match or opens the list when there are several.

Tab after a bare mid-prompt / lists everything. Plugin skills match on their bare name: /deploy finds acme:deploy-site and inserts the full /acme:deploy-site.

Vim mode

Turn it on in /config → Editor mode. Your mode and cursor position survive opening the transcript viewer or a panel such as /config.

Switching modes

Escaping with a two-key sequence

vimInsertModeRemaps maps a two-character INSERT sequence to Escape (v2.1.208). I use jk:

{
  "editorMode": "vim",
  "vimInsertModeRemaps": { "jk": "<Esc>" }
}

Keys must be exactly two printable characters and "<Esc>" is the only target; anything else is ignored. The first key types normally; if the second follows within one second, both vanish and you are in NORMAL. Pause between them and both stay as text, so you can still type words containing the pair. The setting is read only from user settings, --settings and managed settings, never from a project's .claude/ files, so a repository cannot remap your keys.

Movement (NORMAL)

At the very start or end of the input, j/k and the arrow keys step through history. ← on an empty prompt opens agent view from NORMAL as well as INSERT.

Editing (NORMAL)

Text objects work with d, c and y: iw/aw (word), iW/aW (whitespace-delimited WORD), i"/a", i'/a', i(/a(, i[/a[, i{/a{.

Visual mode

Motions extend the selection; then d/x delete, y yanks, c/s change, p replaces with the register, r{c} replaces every character, ~/u/U toggle, lower or upper case, >/< indent, J joins, o swaps cursor and anchor, a text object selects it, and v/V switch kind or exit. Block-wise Ctrl+V is not supported.

History

• Prompt history is kept per working directory, and Up reaches prompts from earlier sessions of the same project.
• After /clear, the new session's prompts come first, then older ones.
• Sending the same prompt twice in a row records it once.
• Recalling a prompt that contained pasted text resends the full paste. If that paste has since been cleaned up, the literal [Pasted text #N] placeholder is never sent; Terminal configuration explains what happens instead.
• ! history expansion is off by default.

Searching with Ctrl+R

In the classic renderer, Ctrl+R starts an inline search across all projects, newest first with duplicates collapsed. Type to filter (matches are highlighted), press Ctrl+R again for older matches, Tab or Esc to accept and keep editing, Enter to accept and send, and Ctrl+C (or Backspace on an empty search) to cancel.

In fullscreen, Ctrl+R opens a dialog: type to filter, Up/Down to move, Ctrl+S to cycle scope between this session, this project and all projects, Enter or Tab to use a match, Esc to cancel. Recent prompts appear at once and older matches fill in as history loads; accepting or cancelling works immediately regardless.

Background commands

Long-running commands do not have to block you. Ask Claude to run something in the background, or press Ctrl+B while a Bash command is running. Claude gets a task id and keeps responding while the command carries on.

A command that hits its timeout is moved to the background rather than killed (unless it starts with sleep). With background tasks disabled via CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 or bare mode, it stops at the timeout instead. Timeouts are configurable; see the tools reference.

How background tasks behave:

• Output goes to a file that Claude reads with the Read tool; each task has an id.
• Tasks are cleaned up when Claude Code exits. On macOS and Linux, stopping a task from /tasks or at exit also stops processes that detached from its shell (via setsid or timeout, for example).
• If you background the session rather than exiting, its tasks keep running there.
• A task producing more than 5 GB of output is killed, with a note in stderr.
• On macOS and Linux, under critical memory pressure, running tasks are stopped if the session has been idle for 30 minutes with no turn or subagent running. The debug log records the decision; CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 disables this.
• In local sessions you are driving (terminal, desktop, VS Code) background commands have no time limit. Unattended sessions such as -p runs and cloud sessions enforce one.
• A background command started by a foreground subagent ends when that subagent's run ends.

Good candidates: dev servers (next dev, vite), watchers, test suites, docker compose up, terraform plan.

Shell mode

Prefix input with ! to run a shell command yourself, without Claude interpreting or approving it:

! pnpm lint --fix
! git log --oneline -5

The command and its output join the conversation, progress streams live, and Ctrl+B backgrounds long runs. Tab completes from your earlier ! commands in this project, and typing a token with a / (such as ./app/ or ~/) shows a file dropdown (use forward slashes on Windows too). Leave shell mode with Esc, Backspace or Ctrl+U on an empty prompt. Pasting text that starts with ! into an empty prompt enters shell mode.

Claude then responds to the output automatically, so ! pnpm test gets you an explanation of the failures without another prompt (at the cost of a normal prompt). Set respondToBashCommands to false to just add the output to context.

Commands you run this way are outside the sandbox even when sandboxing is on, because the sandbox applies to Claude's commands, except in the sessions listed under strict sandbox mode.

Queueing messages while Claude works

Press Enter while Claude is busy and your message is queued rather than interrupting. Queued entries are listed in the conversation, and both sent and queued messages stay grey until Claude starts on them. You can queue ! commands and most / commands too (the immediate ones, like /status, just run). A message queued with an IDE selection keeps the selection you had at the moment you pressed Enter.

When queued items go out:

• Messages queued during tool calls are handed to Claude as soon as those calls finish, inside the same turn. Anything left when the turn ends is sent automatically, in order.
• Commands and shell commands wait until the turn ends, then run one at a time in order.

Sending now. Ctrl+Enter (or Ctrl+X Ctrl+S, which works in terminals that do not report extended keys) sends queued messages immediately, with your draft behind them. If a queued ! command is ahead of your messages, the turn is interrupted. Otherwise, work that can move to the background (shell commands, subagents) does so and Claude reads your messages in the same turn; if Claude is only writing, or running something that cannot be backgrounded, the turn is interrupted and your messages go next. In shell mode the key only queues. Esc interrupts without sending your draft, and sends what was queued.

Settings that change mid-turn. /model, /effort and /fast run immediately rather than queueing. /model and /effort apply to the next request in the current turn (after any cache warning). /fast keeps the turn's original setting and applies from the next turn, unless turning it on forces a model change, which applies from the next request.

Taking it back. Up from the first line pulls queued messages and commands back into the input, one per line ahead of your draft. Edit and press Enter to requeue as one entry, or clear to drop them. Queued shell commands are only taken back when the input is empty and nothing else is queued, and the input switches to shell mode when they are.

Messages that join a running turn do not get their own checkpoint.

Side questions with /btw

/btw asks something about the session without adding to the conversation:

/btw which migration file did we decide to keep?

Claude answers from what is already in context (your messages, its replies, tool results it gathered) and from your recent side questions, up to the newest 20 exchanges until you clear them. The exchange appears in a dismissible overlay and never enters history; the side thread lives in memory and disappears when you exit. In the VS Code extension (v2.1.227 or later), /btw opens a panel that supports follow-ups and survives window reloads.

• It works while Claude is mid-turn and does not interrupt; it sees everything except the reply still being written.
• It has no tools: no reading files, running commands or searching. If Claude writes tool calls as text anyway, the answer notes that nothing ran.
• It is one response. Ask another /btw to continue, or press f to fork the question and answer into a background subagent with full tools (local sessions only).
• With a warm prompt cache it costs little beyond the answer.

Your five newest earlier side questions show dimmed above the current answer. /btw alone reopens the overlay on the latest exchange.

In an attached background session, Left detaches to agent view even while the answer is arriving; the overlay reappears when you reattach.

Rule of thumb: /btw for what Claude already knows, a subagent for finding out something new.

Reviewing changes with /diff

/diff shows your working-tree changes, including Claude's edits and anything else uncommitted. Both views come from the built-in cc-plugin-diff mod; disabling it in /plugin brings back the older viewer.

Submodules appear as one entry, and only when their commit changes. Once Claude has edited files, a source picker offers per-turn views (T1, T2...) built from Claude's file edits rather than git, so changes Claude made via shell only appear under Current.

The panel (fullscreen)

In fullscreen rendering, in a git repository, in a terminal at least 110 columns wide, on v2.1.287 or later, /diff opens a panel beside the conversation that refreshes whenever Claude edits a file or runs a command. It also opens itself when Claude starts editing in a terminal 144 or more columns wide, and after you have opened it once, later sessions open it whenever there is room. Close it (/diff again or the ✕) and it stays closed until you reopen it.

• Click a file to jump to it; scroll with the wheel, and scroll a long file list with Alt+Up/Alt+Down or Ctrl+Up/Ctrl+Down.
• Click ask beside a file name to attach that diff to your next prompt (it reads asked ✓ until you send; asking on another file replaces it).
• Use the source picker for a single turn's edits.
• Test and generated files are hidden, and pre-session changes are collapsed into one line; click the counts to expand.
• Ctrl+X B cycles the comparison: this session's changes, all uncommitted changes, or everything since the branch left the default branch. The choice is remembered per repository.

The dialog (classic renderer)

A bordered list above the prompt, comparing against HEAD or whatever you last chose in the panel. Up/Down select a file, Enter opens its diff (scroll with arrows or PageUp/PageDown), Esc goes back or closes, and Tab moves to the source picker or, inside a diff, to the ask button.

Claude's task checklist

The task list is Claude's own to-do list for multi-step work, showing pending, in-progress and done items. It only exists in sessions with the task-tracking tools, which are on by default for Claude 3.x models, Opus 4 to 4.7, Sonnet 4 to 4.6 and Haiku 4.5. On other models (or unrecognised model ids), opt in with CLAUDE_CODE_ENABLE_TODO_TOOLS=1 or the other routes in the tools reference.

• Ctrl+T toggles it; up to five items show at once.
• An expanded list is restored when you resume a session that still has tasks; empty lists start collapsed.
• Ask Claude to "show all tasks" or "clear the task list" for anything beyond that.
• Tasks survive compaction.
• CLAUDE_CODE_TASK_LIST_ID=client-portal claude shares a named list in ~/.claude/tasks/ across sessions.

Prompt suggestions

A new session shows a greyed-out example prompt drawn from your recent git activity. After each response, Claude Code may suggest a next prompt. Tab or Right puts it in the input; typing dismisses it. Each suggestion is a small background request to the same model, mostly cache reads, and counts towards usage.

Suggestions are off by default (and the toggle hidden) in sessions that do not fetch feature flags, such as third-party providers or gateways, and in a first session after install or upgrade before flags arrive. Individual suggestions are skipped when the cache is cold, after the first turn in some sessions, after an error, in plan mode, near your usage limit (set CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=true to keep them), and in agent team teammates. Showing fewer prompt suggestions · use one to bring them back means you ignored a run of them.

In print mode, --prompt-suggestions with stream-json and --verbose emits prompt_suggestion messages.

To switch them off: the Prompt suggestions toggle in /config, promptSuggestionEnabled: false, or CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false (which wins over the setting). Organisations should set both the setting and the variable (under managed env) so users cannot turn them back on.

Emoji shortcodes

From v2.1.217, typing :tada: inserts the emoji on the closing colon, and : plus two or more letters opens suggestions (Tab or Enter to insert). The shortcode must start the input or follow a space, so URLs and a:b are left alone. emojiCompletionEnabled: false turns both behaviours off.

Spell checking

From v2.1.235, Claude Code can underline misspellings in the prompt box (never in replies or files, and not in shell mode, history search, dictation or screen reader mode). It is off by default and relies on an external checker: the first of aspell, hunspell or ispell found on your PATH (check with aspell --version and so on).

Enable it in user settings, a --settings file or managed settings. Project .claude/ files are ignored for this key. Only one source is used, in the order managed, --settings, user, with no merging of fields between them. Being British, mine looks like this:

{
  "spellcheck": {
    "enabled": true,
    "checker": "hunspell",
    "language": "en_GB",
    "color": "#d97706"
  }
}

• checker: aspell, hunspell or ispell. A named checker is never substituted; other values mean auto.
• language: a plain dictionary name such as en_GB; paths or names with spaces are ignored.
• color: a name, #rrggbb, #rgb, rgb(r,g,b), ansi256(n) or ansi:<name>; defaults to your theme's error colour.

It underlines unknown words shortly after you pause, leaves the word you are typing alone, and never changes text. It skips commands, @ mentions, URLs, paths, flags, words with digits, underscores or internal capitals, backticked text, and Chinese, Japanese, Korean, Thai, Lao, Khmer and Myanmar text. To accept a word, add it to your checker's personal dictionary and restart.

If nothing is ever underlined, the checker is missing, failed twice in a row, or took more than 15 seconds three times; checking then stops until restart. claude --debug and the [spellcheck] lines in ~/.claude/debug/<session-id>.txt say which, including missing-dictionary errors.

Invisible characters are stripped

Pasted text can carry characters a terminal draws as nothing (tag characters, bidirectional controls, zero-width spaces), which could smuggle in instructions you never see. When you press Enter, Claude Code strips them from the prompt and from any collapsed pasted-text references, keeping legitimate joiners used by Persian and Indic scripts and emoji selectors. If anything was removed, nothing is sent: the cleaned text returns to the input with a notice such as Removed 3 invisible characters · review and press Enter to send. A prompt passed on the command line is cleaned and sent straight away with a notice, unless the cleaned text starts with /, in which case it is placed in the input for you to check.

Session recap

Step away and come back, and a one-line recap of the session is waiting. It is generated in the background once three minutes have passed since the last turn and the terminal is unfocused, only after at least three turns, and never twice in a row. /recap produces one on demand (but only when you typed it yourself; relayed or routine-sent /recap gets a notice instead). Recaps are capped at 400 characters, never appear in non-interactive mode, and can be switched off with Session recap in /config.

Waiting out a usage limit

From v2.1.234, when a claude.ai usage limit stops Claude mid-task in an interactive subscription session, Claude Code waits and then carries on by itself once the limit resets. The footer shows something like:

Usage limit reached · limit resets 4:10pm
Continuing automatically at 4:10pm · esc to cancel

Keep the session open. At the reset, Usage limit reset · continuing automatically appears and Claude is prompted to resume where it stopped (your last message is not resent). After a sleep of more than about 30 minutes spanning the reset, you are asked to press Enter instead. Adding usage credits via /usage-credits, re-signing in after /upgrade, or switching model with /model triggers an immediate check and continues if usage is available (but not purchases made separately in a browser, and not under opusplan-style settings).

The resumed turn still asks for permissions, so it can stall on a prompt while you are away. If it hits the limit again it re-arms at most twice, then stops with a message pointing to /rate-limit-options.

Cancelling: Esc on an empty prompt, Ctrl+C, or Don't continue automatically in /rate-limit-options. No automatic wait starts again in that reset window. The wait also ends, without continuing, if you send a prompt, exit, switch account, clear, rewind, resume or teleport another session, relaunch with /tui, hand the session elsewhere, if the setting is turned off or the reset is more than 24 hours away (for automatic waits only), or if a UserPromptSubmit hook blocks the continuation.

Starting one yourself: automatic waits do not start in Remote Control or teammate sessions, for resets more than 24 hours away, or for an Opus or Sonnet limit while you are using a model outside that family. In those cases (and whenever the feature is off) you are shown the usage-limit menu once per reset window at your own terminal; pick Wait here, then continue automatically. Background sessions, -p runs, API keys, cloud providers, usage-based billing and gateways without a saved claude.ai login never offer it.

Turning it off: Continue automatically at usage limit in /config, or autoContinueAtUsageLimit: false in user settings. /config autoContinueAtUsageLimit=false works (even in -p), but the key=value form cannot turn it back on, because it grants unattended execution.

Pull request and merge request badges

On a branch with an open GitHub PR, the footer shows a clickable PR #N link underlined by review state: green approved, yellow pending, red changes requested, grey draft. Cmd+click or Ctrl+click opens it. It refreshes after a successful git push or a gh pr command that changes the PR, and disappears on merge or close.

GitHub status needs a token: for github.com, GH_TOKEN, GITHUB_TOKEN or a gh auth login token (otherwise the footer suggests installing or logging into gh); for a GitHub Enterprise host set as GH_HOST, GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN or gh auth login --hostname <host>; for any other GitHub host, only the gh hostname login, with no hint if missing.

For GitLab (v2.1.234), an MR !N badge appears in the same slot: green when mergeable, yellow otherwise, grey for drafts. It needs a remote on gitlab.com or a self-managed instance and an authenticated glab on your PATH; exported tokens such as GITLAB_TOKEN are ignored. glab and its login are detected once per session, so restart after setting them up.

Badges are rendered as hyperlinks even when support is not detected (common over SSH or tmux); FORCE_HYPERLINK=0 makes them plain text. With CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set, no PR or MR status is fetched.

Issue links

When Claude writes owner/repo#123, it becomes a clickable link if your terminal supports hyperlinks (FORCE_HYPERLINK=1 forces links on, 0 off). Bare #123, nested GitLab paths and anything in code stay plain. The link is built for the host of your repository's git remote:

Related

• Commands
• Keybindings
• Checkpointing
• Fullscreen
• Terminal configuration