AI Engineering

Claude Code accepts input through three distinct channels. They differ in when they are parsed, what parses them, and whether the input reaches the model at all.

flowchart TB
    subgraph T["Shell — before the process exists"]
        A["claude --model opus --add-dir ../api"]
    end
    subgraph S["Session — start of an input line"]
        B["/context   /compact   /doctor"]
    end
    subgraph P["Prompt — inside the text"]
        C["explain @src/auth.js and check !git log"]
    end
    T --> S --> P

Two of the three do not consume model calls. That is the practical consequence: work done through channels 1 and 2 is free of inference cost and latency.

Channel 1 — CLI arguments

These configure the session before it exists, so they control things no in-session command can — the starting permission mode, the working directory set, the system prompt.

Invocation forms

claude                          # interactive session
claude "fix the login bug"      # interactive, with an initial prompt
claude -p "explain this file"   # print mode: one response on stdout, then exit
claude -c                       # continue the most recent conversation in this directory
claude -r                       # resume: interactive picker
claude -r "auth-refactor" "..."  # resume by session ID or name, with a prompt

Print mode (-p) has no REPL and no session UI. It reads stdin and writes to stdout, which makes Claude Code composable with the rest of the shell:

cat error.log | claude -p "what went wrong?"
git diff main --name-only | claude -p "review these for security issues"
tail -200 app.log | claude -p "flag anything anomalous"

This is the mechanism behind every CI integration in Chapter 16.

Flags

Session and mode:

Model and reasoning:

Permissions and access:

System prompt and agents:

Output and scripting, for print mode:

Diagnostics:

--safe-mode and --bare isolate configuration problems in one command: if the behaviour disappears, the cause is something in your configuration rather than in Claude Code. Chapter 22 uses both.

Subcommands

Not all claude invocations start a session:

Channel 2 — slash commands

A / at the start of an input line opens the command menu. These are handled by Claude Code and mostly do not produce a model call.

The menu is the intended discovery mechanism — typing / lists everything currently available, including your own skills. The reference below is the subset in routine use.

Inspection:

Conversation state:

Configuration:

Workflow:

Channel 3 — sigils

Characters interpreted inside the input line.

File references

@path resolves to a file and passes its contents directly, instead of requiring a search:

Why do tokens expire early in @src/auth/middleware.ts?

Path completion is available as you type. Compared to describing the file in prose, this removes a search round trip and eliminates the possibility of Claude reading the wrong file.

Shell mode

A leading ! runs the rest of the line in your shell. Claude does not interpret, approve or select the command.

!npm test
!git status

Behaviour:

• Output is added to the conversation transcript.
• Tab completes from previous ! commands in this project.
• A token containing a forward slash (./src/, ~/) opens a file-path dropdown. On Windows the dropdown triggers on /, not \.
• Ctrl+B backgrounds a long-running command.
• Esc, Backspace or Ctrl+U on an empty prompt exits shell mode.
• In a regular interactive session, shell-mode commands run outside the Bash sandbox even when sandboxing is enabled, because the sandbox governs commands Claude runs. Background sessions with strict sandbox mode are the exception.

Cost — changed in v2.1.186. Older material states that shell mode consumes no tokens. That was true when output was added to context silently. Claude Code now responds to the command output automatically, and that response costs the same as sending a normal prompt. Set respondToBashCommands to false in settings.json to restore the silent behaviour.

The two paths to running a test suite differ by one model round trip and one permission check:

sequenceDiagram
    participant You
    participant CC as Claude Code
    participant Sh as Shell
    participant LLM
    You->>CC: !npm test
    CC->>Sh: npm test
    Sh-->>CC: 2 failing, 14 passing
    Note over CC: Enters transcript.
No tool call, no permission check.
    CC->>LLM: transcript including output
    LLM-->>You: analysis of the failures

sequenceDiagram
    participant You
    participant CC as Claude Code
    participant LLM
    participant Sh as Shell
    You->>CC: run the tests
    CC->>LLM: prompt
    LLM-->>CC: tool call — Bash(npm test)
    Note over CC: Permission check here
    CC->>Sh: npm test
    Sh-->>CC: 2 failing, 14 passing
    CC->>LLM: tool result
    LLM-->>You: analysis of the failures

Use ! when the command is already determined. Use natural language when selecting the command is part of the task.

The # sigil

Older documentation lists # as a prefix for writing to memory. It is no longer documented. The current mechanism is a plain-language instruction, which auto memory captures:

remember that we use pnpm, not npm

/memory browses and edits what was saved. Chapter 7 covers the storage format and configuration.

Channel classification

Nine real inputs, shuffled:

Input handling

The prompt is a readline-style editor.

General controls:

Line editing follows readline: Ctrl+A / Ctrl+E for line start and end, Ctrl+K / Ctrl+U to delete forward and back, Ctrl+W to delete a word back, Ctrl+Y to yank, Alt+B / Alt+F to move by word, Alt+D to delete to end of word. On macOS the Alt/Option bindings require Option configured as Meta in your terminal. A full vim mode is also available, with normal, insert and visual modes, motions and text objects.

Multiline input, four equivalent methods:

If Shift+Enter does not produce a newline, the cause is terminal key handling rather than Claude Code; the terminal configuration guide has per-terminal settings.

Message queueing

Pressing Enter while Claude is mid-turn does not interrupt. The message is queued, listed above the input box, and sent when the current turn completes. ! shell commands and most slash commands can be queued the same way; commands Claude Code executes immediately, such as /status, cannot.

Combined with the interrupt semantics from Chapter 1, there are three ways to redirect a running turn:

Voice dictation

/voice enables dictation. Speech is transcribed into the prompt input, so voice and typing can be mixed within one message.

Hold mode is push-to-talk: hold Space, speak, release. Detection relies on terminal key-repeat events, so there is a short warm-up — the footer shows keep holding… then listening…. Warm-up characters typed during detection are removed automatically. Tap mode has no warm-up: tap Space to start, tap again to stop and send. Recording stops automatically after 15 seconds of silence or two minutes total. In tap mode the transcript auto-submits only at three words or more, so a stray tap does not send.

Requirements:

• A Claude.ai account. Dictation is unavailable when Claude Code is configured with an Anthropic API key directly, or through Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry.
• A local microphone. It does not work over SSH or on Claude Code on the web.
• WSLg if running under WSL. Included with WSL2 installed from the Microsoft Store.

Audio is streamed to Anthropic’s servers for transcription; nothing is processed locally. Transcription does not consume messages or tokens and does not count toward the limits reported by /usage.

Configuration: persist it in settings rather than running /voice each session.

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

Twenty languages are supported, selected by the same language setting that controls Claude’s response language; it defaults to English. The key is bound to voice:pushToTalk in the Chat context and is rebindable in ~/.claude/keybindings.json — a modifier combination such as meta+k starts recording on the first keypress with no warm-up. Setting "autoSubmit": true in the voice object submits on key release in hold mode.

Channel selection

Three tests, applied in order:

1. Does the session exist yet? No → CLI argument.
2. Is the operation performed by Claude Code or by Claude? Claude Code → slash command.
3. Is the exact command or file path already determined? Yes → ! or @.

The failure mode this avoids is issuing a natural-language prompt for an operation a slash command performs locally, which costs a model round trip and returns a less precise answer.

Summary

• Three channels: CLI arguments parsed before the process starts, slash commands parsed at the start of an input line, sigils parsed inside the prompt. Only the third mixes with prose.
• claude -p reads stdin and writes stdout, making Claude Code usable as a shell filter and as a CI step.
• @path passes file contents directly, removing a search round trip.
• Shell mode is not free as of v2.1.186. Claude responds to ! output automatically at the cost of a normal prompt; respondToBashCommands: false restores silent behaviour.
• Shell-mode commands run outside the Bash sandbox in regular interactive sessions.
• # for memory is no longer documented; use a plain-language instruction.
• Enter during a turn queues rather than interrupts.
• Voice dictation is free of token cost, requires a Claude.ai account and a local microphone, and has hold and tap modes.

Chapter 3 covers the six permission modes, the auto-mode classifier’s rules, and the thresholds at which it falls back to prompting.