Claude Code: The Terminal-First Coding Agent

Cursor and Windsurf are separate editor apps you must switch to (Topics 269–270). But ask a different question:

You already have everything an agent needs on your machine:

• files on disk,
• a terminal (the text window where you type commands),
• git, tests, and build tools.

An agent that can read files, write files, and run commands can work in any project, on any machine, even one with no monitor attached — like a server in a data center.

That is the bet behind Claude Code, Anthropic's coding agent: research preview in May 2024, generally available with Claude 3.5 Sonnet in October 2024. You open a terminal in your repo, type claude, and a conversation starts — but the assistant has real tool access: it reads and edits files, executes bash, searches code, fetches URLs, and drives git.

Anthropic deliberately skipped building an IDE fork — instead of moving you into a new app, the agent meets developers where they already work. The same loop also runs inside VS Code and JetBrains as an extension, and inside GitHub Actions and CI pipelines. One engine, many places.

Claude Code is best summed up as

The loop is the familiar plan → act → read results → repeat (Topic 269). The control surfaces are the soul of the product — core concepts every practitioner should know:

• CLAUDE.md — the agent's onboarding handbook. A plain text file you commit to the repo (project root, subdirectories, or ~/.claude/ for personal global notes). It is loaded into the model's context at the start of every session: build commands, code conventions, "never touch /generated". Effectively your repo's README written for the agent.
• Plan mode. Press Shift-Tab to lock the agent into read-only: it researches and proposes a plan, and only starts editing once you approve. Think "architect before construction."
• Subagents. Named specialist agents (e.g., code-reviewer, researcher) defined in .claude/agents/. Each runs in its own context window — its own scratch pad — and returns only a summary. This is the primary mechanism for keeping long tasks from blowing out the main window (more in section 4).
• Hooks. Shell or LLM-judge callbacks fired on lifecycle events. A PreToolUse hook can block an edit or command before it runs; a PostToolUse hook can auto-run tests after every file write. Because hooks are code, not requests, behavior becomes deterministic and policy-enforceable — the agent cannot "forget" a hook the way it can forget a reminder in a prompt.
• Skills, slash commands, and MCP. Reusable procedures, custom commands, and third-party tools through MCP servers (the standard plug for external systems like issue trackers and databases; Topic 269).

Terminal, in a repo. Watch the five surfaces appear:

code
Copy
  $ claude "the payment webhook test is flaky, fix it"

  [session start]  loads CLAUDE.md:
      "pnpm test runs the suite · never edit mocks/ ·
       flaky-test policy: find the root cause, do not retry"

  [plan mode]      reads test + webhook handler, greps logs,
                   proposes: race in the mock server, edit 1 file

  [act]            edits webhooks.test.ts
  [hook: PostToolUse]  automatically runs pnpm test   ← not optional
  [hook result]    1 passed, 0 failed

  [permission]     wants: git commit → asks you → you approve

Three small things to notice:

1. The handbook was already in context — you did not explain the project.
2. The test-after-edit rule ran as code, not as a hope that the model would remember.
3. You gated the git write. Default permissions prompt for consequential actions; you can widen or narrow what needs asking.

A model's context window is its working memory — everything in front of it right now (conversation, file contents, tool outputs). Claude-class models in 2025–2026 carry 200K to 1M tokens, but fill it with raw exploration and quality rots: old and relevant facts get buried under 400 grep outputs.

Subagents fix this with a division of labor:

code
Copy
   WITHOUT SUBAGENTS                WITH SUBAGENTS
   ┌──────────────────┐             ┌──────────────┐
   │ main conversation│             │ main agent   │ ← keeps the plan
   │ 40 file dumps    │             │  clean thread│
   │ 60 tool outputs  │             └──────┬───────┘
   │ your original ask│                    │ delegates
   │ ...now where was│             ┌───────┴───────┐
   │ that point?     │             │ subagent:     │ own window,
   └──────────────────┘             │ researcher    │ does the 40
    everything in ONE head          │  ...digs...   │ dumps ITSELF,
                                    └───────┬───────┘ returns 10 lines
                                            v
                                     "summary: root cause is X,
                                      files A and B" → main agent

The pattern in one line: exploration happens in someone else's memory; only conclusions come home.

Carry one analogy through: Claude Code is a new engineer hired into your repo.

• CLAUDE.md is the onboarding handbook on their desk. A good one is short and current; a bloated one they skim and half-remember. This is why Anthropic's own guidance says keep it terse.
• Plan mode is requiring a design doc before code — they wander the codebase with eyes only, then pitch.
• Subagents are sending an assistant to the library: they read forty books and return you a one-page summary, not forty books dumped on your desk. Your desk (context window) stays usable.
• Hooks are the building's fire inspections: they happen automatically whether the hire remembers them or not. "Run tests after editing" as a hook is a policy; "please run tests" in a prompt is a wish.
• Permissions are keycard access: file reads are the open hallway; git pushes and shell commands are doors that need your badge tap.
• Headless mode (below) is the same employee working the night shift when nobody is in the office.

Most "the agent went off the rails" stories are really stories about a messy handbook, a cluttered desk, and no inspections — not about a dumb model.

Claude Code's biggest differentiator among agents is that the same engine runs unattended:

• claude -p "fix lint errors" — the -p (print) flag makes it a one-shot command: no conversation, it streams a single result (JSON output available), and git guardrails still apply. Drop it into scripts like any CLI tool.
• GitHub Actions integration: the workflow triggers when someone comments @claude on an issue or PR — the agent investigates in CI and opens a PR.
• Permission modes bound what a CI agent may do: default asking, allowlists of pre-approved commands, or full sandboxed containers.

The economics matter too. Because Claude Code is model-vendor-native (Anthropic runs both the model and the agent), long-context Claude models — Sonnet-class at 200K–1M tokens in 2025–2026 — plus prompt caching make whole-repo sessions economical. Caching means the stable prefix (system prompt + CLAUDE.md + file reads you keep re-sending) is not re-paid every turn: repeated-turn cost drops dramatically, which is what makes hour-long agent sessions affordable.

Pricing is usage-based: bundled with Claude Pro/Max subscriptions for interactive use, or API token billing for programmatic/headless use. Heavy agentic teams typically find Max plans far cheaper than raw API — the agent loop hammers the model dozens of times per task, and per-token billing feels that.

Place the tools by what they optimize for:

code
Copy
   interactive, human reviews every diff .... Cursor / Windsurf (IDEs)
   platform delegation, issue → PR .......... Copilot coding agent
   autonomous + scriptable, CI-friendly ..... Claude Code  ← here
   fully remote, queued tickets ............. Devin (Topic 273)

Claude Code occupies the autonomous, scriptable layer. IDE agents optimize for watching each change with a human; Claude Code optimizes for terminal-native engineers, CI automation, and multi-hour unattended jobs — because there is no GUI it depends on, it runs fine where no human is watching (with permissions tightened accordingly).

One more reason engineers pick it: the Claude Agent SDK (renamed from Claude Code SDK in 2025) exposes the same tool harness — loop, filesystem/bash tools, permissions, subagents — so you can build your own custom agents rather than only using Anthropic's.

And the honest cons: no diff-first GUI by default (IDE-fluent users miss inline review), it is tied to Anthropic model quality/availability (mitigated by Bedrock/Vertex deployment), agentic loops burn tokens fast without a Max plan, and hooks/permissions require deliberate setup — interactive-mode defaults are permissive until you tighten them.