Skip to content
AI Coding

Claude Code Guide: Terminal Agent That Actually Ships

Claude Code turns plain-English tasks into multi-file edits, tests, and commits in your terminal. Setup, thin CLAUDE.md rules, and the gotchas most guides skip.

6 min readBeginner

I used to paste a failing stack trace into chat, copy a suggested patch, miss a second file, and spend the next half hour chasing imports. That approach still works for one-liners. For anything that spans modules, tests, and git, Claude Code is the better path: an agent that sits in your project, reads the tree, edits files, runs commands, and only stops when the task is done or you pull the brake.

Here’s the story of how I stopped treating Claude like a snippet vending machine and started treating it like a junior who can open the repo.

When chat-paste collapses and Claude Code fits

You’re mid-bug. The UI dies only after a wrong password. Chat gives you a tidy if block for one file. Reality: the session cookie helper, the client error mapper, and a flaky test all need to move together. Copy-paste multiplies mismatch risk.

Claude Code flips that. It’s an agentic coding tool – reads the codebase, edits files, runs commands, hooks the tools you already use (Anthropic overview). Terminal CLI, VS Code/Cursor, JetBrains, desktop app, browser at claude.ai/code. Same engine. Different front door.

Not Free-tier. As of late 2026 it ships on paid Claude plans (Pro and up). Terminal sessions and chat draw from the same plan budget – details in the limits section below, because that trap bites after setup, not during it.

Practical setup: install, login, first real task

Native installer. Updates land in the background. Package managers work; they lag.

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# new terminal, then:
claude --version
cd /path/to/your/project
claude

Browser login on first run (Pro, Max, Team, Enterprise, or Console API). Native Windows? Install Git for Windows or the Bash tool falls back to PowerShell. Homebrew cask and WinGet skip auto-update – you run brew upgrade / winget upgrade yourself. Stale CLIs miss defaults like auto mode. That’s in the install notes on the same overview page.

Inside the session, start dumb and local:

  1. Ask what the project does and where the entrypoint lives – no edits yet.
  2. Press Shift+Tab until you’re in plan mode if you want exploration only.
  3. One concrete outcome: “fix empty form submit on registration; keep existing tests green.”
  4. Review the plan, switch to auto or acceptEdits, let it patch, run tests, propose a commit.

Auto is the usual start on recent CLI builds. A safety classifier screens tool calls so you’re not babysitting every mkdir. Manual still exists for sensitive trees – cycle with Shift+Tab; full matrix is in the permission modes docs.

Pro tip: Run /init once so Claude drafts a starter CLAUDE.md from the repo. Then delete every line it could learn by reading the code.

Advanced Claude Code usage: thin memory and state on disk

Most tutorials stop at “add a CLAUDE.md.” That’s where results quietly rot.

Turns out the memory docs are blunt about this: CLAUDE.md loads every session as context, not a hard policy engine (project memory). Target under ~200 lines. Always-on facts only – build/test commands, non-default style rules, branch etiquette. Multi-step playbooks belong in skills and path-scoped rules so they load on demand. Must-never-run actions? PreToolUse hook. A markdown bullet will not hold under pressure.

# CLAUDE.md (keep it mean)
## Commands
- test: npm test -- --run
- lint: npm run lint

## Rules
- Named exports only
- No default exports in src/
- Run the single failing test file before the full suite

Fat files burn tokens every session and adherence drops – official guidance and community threads both treat bloat as a reliability problem, not thoroughness.

Long tasks taught me a second habit. If the only record of “what’s done” lives in the chat transcript, compaction or a fresh session loses the thread. Keep a plan.md (or similar) with task rows, status, and a one-line evidence note after each step. The agent reads the file; the conversation can die. Resume helpers: claude -c / claude -r.

Pipe mode for ops glue:

git diff main --name-only | claude -p "flag security-sensitive changes only"

Composable. Scriptable. CI-friendly. The Unix angle Anthropic actually leans on.

Honest limits before you rearrange your workflow

Usage is shared. Heavy Claude Code days and heavy claude.ai chat days pull from one Pro/Max pool (see claude.com/pricing). Hit the wall and you wait, move to Max (from $100/mo at 5x or 20x Pro usage), or enable usage credits at API rates. Cost-doc framing for enterprise-style token billing averages around $13 per developer per active day – wide variance. Pilot before you promise finance a number. Track with /usage.

CLAUDE.md loses under competing goals. “Make it compile” beats “never use any” more often than people admit. Short verifiable bullets help. They don’t replace review. Auto mode cuts prompt fatigue; the classifier is still a classifier – auth and payments stay plan-first or Manual.

Is the agent always faster than you on a greenfield spike? Not always. For navigation, refactors, test backfill, and chore automation, it’s hard to go back.

FAQ

Do I need Pro to run Claude Code?

Yes – Free doesn’t include it. Pro is the usual on-ramp at $20/mo monthly or $17/mo annual on Anthropic’s pricing page; Console API billing is the pay-as-you-go path.

Plan mode vs auto mode – when do I use which?

Unfamiliar repo, risky refactor, or anything near auth? Stay in plan until the approach is boring – explore and propose, no source edits until you say go. Well-scoped bug with a plan you already like? Auto lets it execute while the safety classifier screens tool calls; that’s the default that fits after you’ve seen the outline. Shift+Tab cycles modes in the CLI.

Why does Claude keep breaking a rule I put in CLAUDE.md?

Context injection at session start – not a runtime firewall. Attention drifts. Codebase patterns compete. “Fix the error” outranks “never use any.” Keep the file short and concrete; restate the critical constraint in the prompt for high-stakes steps; use a PreToolUse hook when something must be impossible. Over ~200 lines? Split. Don’t re-litigate the whole style guide mid-incident.

Open your real project, run the native install, type claude, then /init. Trim the generated CLAUDE.md to commands and rules only – and give it one bug you were going to fix by hand this week.

Related Tutorials