Debugging with Claude Code in the terminal

Debugging with Claude Code is a four-step terminal loop: pipe the error in with its context, investigate in plan mode so nothing is edited while the cause is unknown, prove the root cause with a test that fails, then fix until that test and the full suite pass. git bisect run and headless claude -p cover regressions and CI failures.

This page is for developers who debug in the terminal with Claude Code, and for tech leads who decide what a bug-fix pull request must prove. The situation: CI is red with Cannot read properties of undefined (reading 'map'), the stack trace crosses six files in two services, and the last merge touched 40 files. You paste the error and ask for a fix. Claude adds a null check, CI goes green, and the same crash returns next week from a different caller.

The agent did not fail at coding. It was asked to edit before anyone knew the cause. The workflow below keeps it searching until the cause is proven, and makes the proof a test you can check without reading every line of the fix.

What you’ll walk away with from terminal debugging

A pipe-first way to hand Claude Code test, server, log and CI output without copy-paste
A read-only investigation step in plan mode, and a rule for when to leave it
Ten copy-paste prompts: the bug report, the constrained fix, production stack traces, type errors, race conditions, memory growth, CI-only failures, suspect commits without a known-good one, parallel investigation with subagents, and CI triage
A git bisect run recipe that survives flaky tests
An evidence checklist a reviewer can approve without reading the whole diff
Recovery steps for the six ways Claude Code debugging goes wrong

How does the Claude Code debugging loop work?

Each phase limits what Claude may change. The limit, not the model, is what stops the fix-break-fix cycle.

Phase	Claude Code mode	Claude may change	Leave the phase when
1. Hand over the failure	`claude -p` with a pipe, then `claude -c`	nothing	the error, trigger and recent changes are in context
2. Investigate	plan mode (`claude --permission-mode plan`, or `/plan` in a session)	nothing	Claude names one cause, with the file, line and condition
3. Prove the cause	your normal mode, test files only	a new test	the test fails for the reason Claude named
4. Fix and verify	your normal mode	the files the diagnosis named	the new test and the full suite pass

Hand over the failure with its context

Pipe the output straight in. Claude Code reads standard input together with the prompt, so the error never passes through your clipboard:

npm test -- --run tests/services/order.test.ts 2>&1 | \
  claude -p "This test fails. Read the test and the source it imports. \
Name the most likely root cause and the file to open first. Do not edit anything."

Then run claude -c to continue the same conversation interactively, with the output still loaded. When you know more than the log shows, spend 30 seconds on a structured report:

I have a bug. Here is everything I know.

Error and stack trace: [paste them in full]
Trigger: [the user action, request or job that causes it]
Frequency: [always / about 1 in 10 / only in production]
Recent changes: [deploys, dependency bumps, config changes, with dates]

Do not edit any file yet. Read every file in the stack trace and follow
the imports from the entry point to the line that throws. Show me the
data shape at each hop and the first hop where it differs from what the
code expects. End with one root cause, stated as file:line plus the
condition that triggers it, and how confident you are.

Investigate in plan mode

Start the session in plan mode, or press Shift+Tab until the mode indicator shows plan mode. Claude can read and search files, but it cannot edit them:
Terminal window
```
claude --permission-mode plan
```
Ask for the trace, not the fix: “Trace the request from src/routes/orders.ts line 47 through the service layer into the query. Where does items become undefined?” Challenge the answer before you accept it: “Prove it. Show the line where the value originates and explain why it only happens for users with expired sessions.” Two plausible causes means you are still in phase 2.
Prove the cause with a failing test

A diagnosis is a claim. A test that fails for the stated reason is evidence. Ask Claude to write the reproduction first, run it, and show you the failure message. If the test fails for a different reason, the diagnosis is wrong: go back to step 2 rather than fixing forward.

Fix, then run everything

Leave plan mode and give Claude a fix it cannot widen:

The root cause is the one we proved with the new failing test.
Fix it in the files the diagnosis named and nowhere else.

Rules:
- Do not edit the new test or any existing test.
- Do not add a null check or try/catch that hides the symptom;
  fix the place where the bad value is produced.
- Run the new test, then the full suite (npm test), and paste
  the summary lines of both runs.
- Finish with `git diff --stat` and one sentence per changed file
  explaining why it had to change.

Then ask one more question: “Search the codebase for other callers that make the same assumption, and list them with file:line. Do not change them.” That list becomes the next ticket, not part of this diff.

How do you pipe logs and CI output into Claude Code?

The pipe works wherever the error already prints. Filter before you pipe: a hundred relevant lines let Claude group errors by cause, while a hundred thousand raw lines get paraphrased.

Production logs:

grep -E "ERROR|WARN" /var/log/app/production.log | tail -100 | \
  claude -p "Group these errors by root cause. For each group give the count, \
the source file and line, and whether it relates to the payment timeout we are \
investigating. Order by count."

A failed GitHub Actions run (the gh CLI prints only the failing steps’ logs with --log-failed):

gh run view RUN_ID --log-failed | \
  claude -p "Identify the failing test, read its source and the code it tests, \
and explain what broke. Check the commits in this run for the change that caused it." \
  --allowedTools "Read,Grep,Glob,Bash(git show:*),Bash(git log:*)"

Replace RUN_ID with the number from gh run list.

Production errors straight from Sentry. When the trace lives in an error tracker rather than a log file, connect the Sentry MCP server so Claude reads the issue, its breadcrumbs and the release it started in:

claude mcp add -s project --transport http sentry https://mcp.sentry.dev/mcp
claude mcp login sentry

Setup for Grafana, Datadog and PostHog, and the read-only scopes to grant, are on the observability MCP page.

Which Claude Code prompts fix recurring bug types?

Production stack traces

The generic prompt gets a generic answer. This one forbids the generic fix and ends on a passing test:

Analyze this production error:

[paste the stack trace]

Do not suggest a generic fix. Instead:
1. Read the source files named in the trace, at the deployed commit
   (git log -1 --format=%H on the release tag if you need it).
2. Identify the exact line and the condition that triggers the error.
3. Explain why it happens: timing, data shape or an edge case.
4. Write a test that reproduces it and run it to show it fails.
5. Stop and wait for me before implementing the fix.

Type errors that point at the wrong file

This TypeScript error points at src/api/orders.ts, but I think the cause
is elsewhere:

[paste the tsc output]

Trace the type through every transformation from where it is declared
to where the error fires. Tell me the first place it diverges from what
the caller expects. That is the file to fix.

Race conditions and intermittent failures

A vague prompt gets a vague theory. Name the failure precisely and give Claude the checklist of what actually causes it:

tests/services/payment.test.ts fails about 1 run in 10 with
"expected 'processing' but received 'completed'".

Do not edit anything yet. Read the test and src/services/payment.ts.
List every async operation whose order could change between runs, and check for:
1. shared mutable state between tests or between requests
2. a missing await
3. code that assumes two async calls finish in order
4. cleanup (afterEach, finally) that runs before pending work completes

Then write a loop that runs this test 50 times
(for i in $(seq 50); do npx vitest run tests/services/payment.test.ts || break; done)
and tell me which of your hypotheses the failure output supports.

For races that resist the first pass, raise the reasoning depth before you change the model. From v2.1.280 (the latest channel), Claude Code’s default model is Claude Opus 5.5, and it runs at medium effort; /model shows what your install uses. Put ultrathink in one prompt to deepen a single turn, or run /effort high (or start with claude --effort xhigh) for the session. The trade-offs are on the deep reasoning page, and current defaults and prices on the models hub.

Memory growth

Heap snapshots are often hundreds of megabytes of JSON, and reading one floods the context. Compare them yourself first: load both in Chrome DevTools, open the Memory panel’s Comparison view, and paste the top retainers into the prompt.

Our Node.js service grows from 200 MB to 1.2 GB over six hours, then
dies with an out-of-memory error. Do not open the .heapsnapshot files;
here is the comparison summary (start vs 4h, top retainers):

[paste the Comparison view rows]

Read src/handlers/ and look for listeners added without removal, maps or
arrays that grow without a bound, closures that hold request objects,
and streams that are opened but never closed. Rank the candidates by how
well each one explains growth that is steady rather than stepped and
matches the retainers above. Then write a load test or script that
reproduces the steady growth, and show before/after heap numbers.

Passes locally, fails in CI

This test passes locally and fails in CI. CI output:

[paste the output, or pipe it in with gh run view --log-failed]

Compare the environments before reading the code: run node --version and
print the TZ and LANG variables here, then read .github/workflows/ and
.node-version for what CI uses. Then check the test for timezone and
locale assumptions, absolute paths, timing-sensitive assertions, missing
fixtures, and dependence on a test that runs before it. Name the
difference that explains the failure and show how to reproduce it
locally (for example TZ=UTC npm test).

How do you find the commit that broke it?

When you have a good commit and a test that reproduces the bug, let git do the search and Claude do the reading. Run this in your terminal:

git bisect start HEAD GOOD_SHA
git bisect run npx vitest run src/api/search/search.test.ts
git bisect log | claude -p "Read this bisect log. Name the first bad commit, \
read its diff, and explain which change breaks /api/search." \
  --allowedTools "Read,Grep,Glob,Bash(git show:*),Bash(git log:*)"
git bisect reset

Replace GOOD_SHA with the last commit you know worked. git bisect run treats exit code 0 as good and 1–127 (except 125) as bad, so any test command works.

Without a known-good commit, start from time instead:

This bug appeared after last Tuesday's deploy. Run
git log --oneline --since="10 days ago" -- src/services/
and read the diff of each commit. Which one could produce
"TypeError: Cannot read properties of null (reading 'id')" in order
processing? Rank the top three with the line that makes each suspect.

How do subagents help with a bug that spans services?

When a bug crosses several parts of the system, subagents investigate in parallel, each in its own context, and return a summary. Your main session keeps only the findings, which leaves room for the fix. Claude Code ships a built-in Explore subagent for this kind of search; you can also define your own in .claude/agents/ (see custom subagents).

Use three subagents in parallel. None of them may edit files.

1. Trace a request from the API gateway through the auth middleware into
   the order service. Find where the user object loses organization_id.
2. Read the migration history for the organizations table. Was a column
   renamed or made nullable in the last month?
3. Find every read of user.organization_id and report which ones handle
   undefined and which do not, as file:line.

Each subagent returns at most 15 lines of findings with file:line
references. Then combine them into one root-cause statement.

To have this loop available without prompting for it each time, install a debugging skill. Claude loads it whenever a bug report matches the skill’s description:

npx skills add obra/superpowers --skill systematic-debugging
# or
npx skills add mattpocock/skills --skill diagnosing-bugs

The portable npx skills add copy of Superpowers has no SessionStart bootstrap, so the full Superpowers method does not fire on its own. For that, install the plugin in a Claude Code session instead: /plugin install superpowers@claude-plugins-official.

How to check that a skill actually changed the agent’s behaviour is on testing and debugging skills.

How do you triage CI failures headlessly?

claude -p runs without a person at the keyboard, and --output-format json wraps the answer in JSON that a later step can post as a pull request comment. For triage, keep the job read-only: allow only the file-reading tools and deny every permission prompt instead of waiting for one.

# Tests run the branch's code: keep ANTHROPIC_API_KEY out of this command's environment.
npm test 2>&1 | tail -300 > test-output.txt
# The agent only reads: no hooks, settings or .mcp.json from the branch.
claude -p --bare --setting-sources "" --strict-mcp-config \
  --allowedTools "Read,Grep,Glob" \
  --permission-prompts none \
  --output-format json \
  "Classify each failure in this test output as a flaky test (timing or order
dependent), a real bug (logic error), or an environment problem (config,
versions, missing service). For real bugs give the root-cause file and line.
For flaky tests say what makes them nondeterministic. Do not propose edits." \
  < test-output.txt > triage.json

--bare --setting-sources "" --strict-mcp-config keeps the branch’s own hooks, settings and .mcp.json from loading next to the key; --bare authenticates only with ANTHROPIC_API_KEY or an apiKeyHelper, not with a subscription login. In a workflow, run the tests and the claude -p call in separate jobs and pass test-output.txt as an artifact, as the test-triage workflow does: a test step can write to GITHUB_ENV or GITHUB_PATH and so reach every later step of its own job, including the one that holds the key.

Two rules for running this in a workflow. Run it only on your own branches (push, or pull_request from the same repository), never with secrets on a pull_request_target or workflow_run trigger that checks out contributor code. And let a person or a separate, reviewed job apply fixes: a triage job that can edit and push turns a flaky test into an unreviewed commit. The full workflow, permissions block included, is on the Claude Code CI/CD page.

How do you verify a Claude Code bug fix without reading every line?

Review the evidence, not the diff. A bug-fix pull request is ready when it carries these five items, and the reviewer checks them in this order:

Root-cause statement: one sentence naming file, line and triggering condition.
Red before green: the new test’s failure output on the unfixed code, then its pass. Check it yourself: stash only the fix with git stash push -- <the files the diagnosis named>, run the new test and see it fail, then git stash pop. A plain git stash also stashes a test added to an existing test file, so the red run exercises the old tests and proves nothing.
Full suite: the summary line of the complete test run after the fix, not only the new test.
Scope: git diff --stat lists only the files the diagnosis named, and no existing test changed.
Similar callers: the list of other places with the same assumption, filed as follow-up work.

The developer who ran the session signs off on items 1–3. The reviewer signs off on items 4 and 5, and reads the diff in full only when item 4 shows files outside the diagnosis. The same items fit the team-wide evidence bundle format.

What breaks when you debug with Claude Code?

Claude fixes the symptom. It adds a null check and the crash moves elsewhere. Cause: it was asked to fix before the cause was known. Recovery: undo the edit with /rewind (or Esc twice), return to plan mode, and use the bug-report prompt. Say what you want fixed: “the value is null because the fetch races the render; fix the race, not the null check.”

The fix breaks something else. Only the new test was run. Recovery: make “run the full suite and paste the summary” part of every fix prompt, and have CI run the complete suite as a required check.

The new test passes before the fix. The test does not reproduce the bug, so it proves nothing. Recovery: run it on the unfixed code (git stash push -- <the fix files>, not a plain git stash, which can stash the test too), and if it passes, tell Claude “this test passes without the fix, so it does not reproduce the bug; make it fail for the reason you named.”

Claude edits the test to make it pass. A weakened assertion or a new .skip turns red into green without fixing anything. Recovery: check git diff --stat for test files, add the deny rule from the caution above, and re-run the original test from the commit where you wrote it.

Bisection blames the wrong commit. A flaky test marks commits good or bad at random. Recovery: git bisect reset, then make each step run the test several times so one failure marks the commit bad: git bisect run sh -c 'for i in 1 2 3 4 5; do npx vitest run test.ts || exit 1; done'.

The context fills with logs. Long sessions accumulate file reads and test output until early findings drop out. Recovery: run /compact keep the root-cause statement, the failing test and its output, or start a fresh session with only the diagnosis and the test name. Piping filtered output, not whole logs, prevents it.

Where to go next after fixing the bug

Testing with Claude Code Turn the regression test into a habit: generate suites, run the red-green loop, and wire it into CI.

Test-driven bug fixing The strict red-test-first protocol, with the test locked before the fix starts.

Debugging in Codex The same reproduction-first loop across the Codex app, CLI, IDE and cloud.

Debugging in Cursor Mode-per-phase bug hunting in Cursor's agent, with an evidence checklist.

Troubleshooting Claude Code itself When the problem is the tool, not your code: installation, auth, MCP and performance.

Refactoring with Claude Code When the bug exposes a structural problem, refactor it away behind the tests you just wrote.