To debug Python scripts on Claude Code, open your terminal in the project directory, run `claude`, and either paste your traceback directly or use the `/debug` slash command on a specific file. Claude Code reads your local files, interprets the full stack trace, and proposes targeted fixes in context — no copy-pasting between browser tabs required. Designed for developers who want to stay in their editor flow, it works best on Python 3.8+ projects with a virtual environment already activated.

- Claude Code can read local files directly — no need to copy-paste code into a chat window
- Debugging sessions consume tokens from your plan's usage limit; a complex multi-file debug can use a significant chunk of your 5-hour usage window
- The `/usage` command shows your current consumption so you're never surprised mid-session

## What is Claude Code and why use it for Python debugging?

Claude Code is Anthropic's [agentic CLI tool](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) that runs directly in your terminal. Unlike the web interface, it can read, edit, and execute files in your local environment. For Python debugging, this means it sees your full project structure: `requirements.txt`, virtual environments, test files, and multi-module imports that would be tedious to reproduce in a browser chat.

The key advantage is context. When a traceback references `src/utils/parser.py:line 42`, Claude Code can open that file, read the surrounding logic, and suggest a fix that accounts for the actual codebase — not a hypothetical snippet.

## How to start a Python debugging session in Claude Code

### Step 1: Open Claude Code in your project root

Navigate to your Python project and start the CLI:

```bash
cd my-python-project
claude
```

Make sure your virtual environment is active before launching. Claude Code will pick up the correct Python interpreter and installed packages from the local context.

### Step 2: Paste or describe the error

The most direct path: run your script, copy the full traceback, and paste it into the Claude Code prompt. Be explicit:

```
I'm getting this error when running `python main.py`:

Traceback (most recent call last):
  File "main.py", line 18, in <module>
    result = parse_config("config.yml")
  File "src/parser.py", line 42, in parse_config
    return yaml.safe_load(f)
yaml.scanner.ScannerError: mapping values are not allowed here
```

Claude Code will read `src/parser.py` and `config.yml` directly to diagnose the issue.

### Step 3: Use slash commands to target specific files

Claude Code's [slash commands](/content/blog/how-to-use-claude-code-slash-commands/index.html) streamline the debugging workflow. Useful patterns:

- **/debug**: Attach a file and ask Claude to find the bug (e.g., `/debug src/parser.py — why does safe_load fail on this config?`)
- **/review**: Ask for a code review focused on error handling and edge cases
- **/test**: Generate or run unit tests to isolate the failing logic
- **/fix**: Apply a targeted patch to a specific file after diagnosis

A full reference of available commands is in the [Claude Code slash commands list](/content/blog/claude-code-slash-commands-list/index.html).

### Step 4: Iterate with targeted follow-ups

Debugging is rarely one-shot. After Claude proposes a fix, test it and bring back the new output:

```
Fixed the YAML issue, but now I'm getting:
AttributeError: 'NoneType' object has no attribute 'get'
on line 61 of src/processor.py
```

Because Claude Code retains session context, it connects the original parser bug to this downstream `None` propagation without you re-explaining the project structure.

## Python-specific debugging techniques that work well in Claude Code

### Traceback analysis for import errors

Import errors and circular dependencies are common in larger Python projects. Paste the full `ModuleNotFoundError` or `ImportError` traceback. Claude Code can inspect your `__init__.py` files, `pyproject.toml`, or `setup.cfg` to trace where the module resolution breaks.

### Type errors and None checks

Python's dynamic typing means `AttributeError` and `TypeError` often surface at runtime rather than at write-time. Describe the expected type and the actual behavior; Claude Code can add targeted `isinstance` guards or suggest migrating a function signature to use type hints for earlier detection.

### Test-driven debugging with pytest

Ask Claude Code to write a minimal pytest case that reproduces the bug before fixing it. This creates a regression test as a side-effect of the debugging session:

```
Write a pytest test that reproduces the ScannerError in parse_config,
then fix the function so the test passes.
```

### Environment and dependency issues

If the bug is version-related (e.g., a deprecated API in a newer library version), share the output of `pip freeze` or `poetry show`. Claude Code can cross-reference known breaking changes and suggest a pinned version or a migration path.

## How to reduce token usage during long debugging sessions

Complex multi-file debugging sessions consume tokens faster than simple Q&A. A few strategies to stay efficient:

- **Scope the context**: Reference only the files relevant to the bug rather than asking Claude to "look at the whole project"
- **Be specific in prompts**: "Why does `parse_config` return None on line 42?" uses fewer tokens than "find all bugs in my codebase"
- **Batch fixes**: Group related bugs in one prompt instead of separate back-and-forth turns
- **Use `/usage` to check your balance**: Run `/usage` at any time in the Claude Code session to see where you stand in your current usage window

## Key takeaways

1. Start Claude Code in your project root with your virtual environment active
2. Paste the full traceback — Claude Code reads local files to give context-aware fixes
3. Use `/debug`, `/fix`, and `/test` slash commands to target specific files and actions
4. Ask Claude Code to write a pytest regression test before applying the fix
5. Scope prompts narrowly to conserve tokens during long sessions
6. Run `/usage` periodically or use Usagebar to avoid a mid-session lockout