Claude Code Quick-Start Guide

Personalized for: JAX/CT reconstruction work, PyCharm user, multi-GPU focus

This is a living document — edit it as you learn. Last updated: 2026-02-15

1. Core Concepts

Claude Code is not a chatbot you copy/paste with. It operates directly on your files — reading, editing, running commands, and committing. Think of it as a capable colleague who sits in your terminal with full access to your project.

Key mental model shift from ChatGPT + PyCharm:

You don't paste code in and out — you describe what you want
Claude reads your files itself, runs your tests, checks its own work
Git is your safety net — commit before risky changes, rewind if needed

2. Getting Started (First Session)

# Navigate to your project
cd ~/path/to/your-ct-project

# Start Claude Code
claude

# Your first questions — let Claude explore the codebase
> what does this project do?
> how is GPU parallelism currently handled?
> explain the reconstruction pipeline at a high level

Essential commands:

Command	Purpose
`claude`	Start interactive session
`claude -c`	Continue most recent conversation
`claude -r`	Resume a specific past conversation
`/help`	Show all commands
`/clear`	Reset context (do this between unrelated tasks)
`/compact`	Summarize context to free space
`Esc`	Stop Claude mid-action
`Esc Esc` or `/rewind`	Undo — restore conversation + code to a checkpoint
`Shift+Tab`	Toggle Plan Mode (explore without editing)

3. Set Up Your Project (CLAUDE.md)

Create a CLAUDE.md file in your project root. Claude reads this at the start of every session. Run /init to auto-generate a starting point, then refine.

Example for a JAX/CT project:

# Project: CT Reconstruction

## Build & Run
- Python 3.11+, JAX with CUDA
- Install: `pip install -e .`
- Run tests: `pytest tests/ -x`
- Run single test: `pytest tests/test_forward.py::test_name -x`

## Architecture
- `src/forward/` — forward projection operators
- `src/recon/` — reconstruction algorithms (FBP, iterative)
- `src/sharding/` — multi-GPU sharding utilities
- `tests/` — pytest tests

## Code Style
- Use jax.numpy (jnp), not numpy, for array operations in GPU code
- Type annotations on all public functions
- Prefer jax.sharding / shard_map over deprecated pmap for new multi-GPU code
- Use pytrees for parameter containers

## GPU/Sharding
- Target: [your GPU setup, e.g., "4x A100 80GB"]
- Default mesh: [your preferred device mesh layout]
- Always test with single-GPU before multi-GPU

## Conventions
- Commit messages: imperative mood, concise
- Branch naming: feature/description, fix/description

Key rules for CLAUDE.md:

Keep it short — only things Claude can't infer from reading code
If Claude keeps ignoring a rule, the file is probably too long
Check it into git so it evolves with the project

4. The Multi-Resolution Workflow

This maps to your stated preference for high-level understanding + fine-grained detail where it matters.

Level 1: Explore (Plan Mode)

Press Shift+Tab to enter Plan Mode. Claude reads files but won't edit anything.

> explain the overall reconstruction pipeline
> how does data flow from raw sinogram to reconstructed image?
> what sharding strategy is used for the forward projector?

Level 2: Targeted Deep Dive

> explain the sharding logic in src/sharding/mesh.py lines 40-80
> what are the tradeoffs between shard_map and manual pjit here?
> trace a single forward projection call through the full stack

Level 3: Implement

Press Shift+Tab again to exit Plan Mode, then:

> add gradient checkpointing to the iterative reconstruction loop
> write a test that verifies forward projection against a known Shepp-Logan phantom

Level 4: Verify + Commit

> run the tests and fix any failures
> commit with a descriptive message

5. Effective Prompting Patterns

Be specific — reference files, constraints, examples

# Vague (works but may go wrong)
> optimize the forward projection

# Specific (much better)
> the forward projection in src/forward/project.py is slow for large volumes.
> profile it, identify bottlenecks, and optimize. keep the API unchanged.
> the input is a 512x512x512 volume, output is 360 sinogram views.
> run tests after changes.

Point to patterns

> look at how FBP is implemented in src/recon/fbp.py.
> follow the same structure to implement SIRT in a new file src/recon/sirt.py

Let Claude verify its own work

> implement the adjoint operator and write a dot-product test
> (<Ax,y> = <x,A^T y>) to verify correctness. run it.

Use subagents for research (keeps your context clean)

> use a subagent to investigate how jax.experimental.shard_map handles
> collective operations like all-gather, then summarize the findings

6. Multi-GPU JAX — Where Claude Code Shines

This is your highest-leverage use case. Multi-GPU JAX code is complex and error-prone; Claude can help with the tedious parts while you focus on the math.

Productive workflow:

Describe the problem at the math/algorithm level
Ask Claude to propose a sharding strategy with rationale
Review, discuss, iterate
Ask for implementation
Have Claude write correctness tests (e.g., compare single-GPU vs multi-GPU)

Example session:

> I need to distribute a 3D forward projection across 4 GPUs.
> The volume is 512^3 and I'm computing 360 projection views.
> The volume doesn't fit on a single GPU.
>
> What are the options for sharding this computation?
> Consider: sharding the volume along z, sharding the views,
> or a hybrid approach. What are the communication costs?

7. Checking Usage Limits & Reset Times

In Claude Code:

/usage — shows remaining capacity, current limits, and reset times
/cost — shows token usage and cost (for API users; not relevant for Pro/Max subscriptions)

In browser:

Visit claude.ai/settings/usage to see remaining prompts, weekly limits, and reset schedule

How resets work:

5-hour rolling window — resets 5 hours after your first request in the window (not at a fixed clock time)
Weekly limits — 7-day cap; if you hit it, you wait up to 7 days even if the 5-hour window resets sooner

8. Session Management Tips

/clear between unrelated tasks — this is the #1 habit to build. Context pollution is the most common cause of degraded performance.
Commit before risky changes — Claude won't push without asking, but having a clean git state lets you rewind easily.
Use /rewind liberally — if Claude goes down a wrong path, rewind rather than trying to correct. A clean restart with a better prompt beats accumulated failed attempts.
Name sessions with /rename — e.g., "shard-map-migration" so you can resume later with claude -r.

9. Claude Code + PyCharm: Using Both

	Claude Code (CLI)	JetBrains Plugin / Claude Agent
Best for	Multi-file tasks, refactoring, exploration, running tests	Quick edits, inline questions, code completion
Context	Reads whole project, runs commands	Scoped to open files / IDE context
Workflow	Terminal alongside PyCharm	Inside PyCharm

JetBrains Claude Code plugin (separate from the AI Chat Claude Agent):
Install from JetBrains Marketplace: search "Claude Code" in Settings > Plugins. This gives you a Claude Code panel inside PyCharm.

JetBrains AI Chat "Claude Agent" (what you asked about):
Requires PyCharm 2025.2+, JetBrains AI subscription (or Anthropic API key), and updated AI Assistant plugin. If grayed out, check these three things.

Recommended approach for now: Use Claude Code in a terminal next to PyCharm. This is the most powerful and flexible setup.

10. Things to Try in Your First Week

Run /init in a project to generate a starter CLAUDE.md
Ask Claude to explain your codebase structure
Ask Claude to explain a specific complex function
Use Plan Mode (Shift+Tab) to explore without editing
Ask Claude to write a test, run it, and fix failures
Ask Claude to propose a sharding strategy for a computation
Practice /clear between tasks
Try /rewind after a change you don't like
Ask Claude to commit changes (/commit or "commit with a descriptive message")
Resume a previous session with claude -c

11. Quick Reference Links

Notes & Lessons Learned

Add your own notes here as you learn: