The Minimal IDE Setup for Claude Code

The best IDE setup for Claude Code is barely an IDE at all. Plain terminal for the agent. Cursor open separately for reading and reviewing. Git worktrees when you need parallel agents. That is the whole stack.

After months of running this setup daily - sometimes with five agents running simultaneously on the same codebase - I can say with confidence that adding more tooling makes things worse, not better. Here is exactly how to set it up, why each piece matters, and the specific configurations that make it work.

Why Plain Terminal Wins Over IDE-Integrated Terminals

Claude Code is a CLI tool. It does not need an IDE wrapper, a plugin system, or an integrated file browser. Running it in a plain terminal - iTerm2, Warp, Ghostty, or Kitty - gives you the cleanest interaction with the fewest failure modes.

The argument for a plain terminal over an IDE's integrated terminal comes down to three concrete advantages:

1. Full Screen Real Estate for Agent Output

Claude Code sessions produce a lot of output. When the agent reads files, runs commands, edits code, and explains its reasoning, you can easily generate hundreds of lines per task. An IDE's integrated terminal panel is typically 20-30 lines tall, which means you are constantly scrolling. A full-height terminal window on a 1440p display gives you 50-60 visible lines - enough to see the agent's current reasoning and the last few tool calls without scrolling.

2. Native Scrollback and Search

Terminal emulators like iTerm2 give you proper scrollback buffers (configurable up to unlimited lines), native Cmd+F search through the entire conversation, and keyboard shortcuts that work predictably. VS Code's integrated terminal has a default scrollback of 1,000 lines, and the search behavior is clunkier because it competes with the editor's own search overlay.

3. Independent Process Lifecycle

When Claude Code runs in a standalone terminal, it is completely decoupled from your editor. If Cursor crashes, your agent keeps running. If you need to restart your editor to load new extensions, the agent session continues uninterrupted. This independence matters more than it sounds - agent tasks can run for 10-15 minutes on complex refactors, and losing that session because your editor needed a restart is genuinely painful.

Terminal Configuration That Matters

Before you start using Claude Code heavily, configure these settings in your terminal of choice:

Shift+Enter for multi-line input. This works natively in iTerm2, WezTerm, Ghostty, and Kitty. For other terminals, run /terminal-setup inside Claude Code to configure it automatically. Alternatively, type \ followed by Enter for a newline - this works everywhere with no setup.

Enable passthrough for tmux users. If you run tmux (and you should for the worktree setup below), add this to your ~/.tmux.conf:

set -g allow-passthrough on

Without this, tmux intercepts escape sequences that Claude Code uses for notifications and progress bars. You will miss completion alerts and the terminal status line will not update.

Set up desktop notifications. When an agent finishes a task and waits for your input, you want to know immediately - especially if you have switched to another window. In iTerm2:

1. Open Settings, then Profiles, then Terminal
2. Enable "Notification Center Alerts"
3. Click "Filter Alerts" and check "Send escape sequence-generated alerts"

Kitty and Ghostty handle this without configuration. The default macOS Terminal.app does not support notification escape sequences at all, which is one reason to switch away from it.

Increase scrollback buffer. In iTerm2, go to Settings, then Profiles, then Terminal, and set "Scrollback Lines" to at least 10,000. For long agent sessions, unlimited scrollback is better. The memory cost is negligible.

Consider Vim mode. If you are a Vim user, enable it with /vim or set editorMode to "vim" in ~/.claude.json. Claude Code supports a solid subset of Vim keybindings including mode switching, navigation with h/j/k/l and w/e/b, editing with d and c operators, yank/paste, and text objects. It is not full Vim, but it covers the muscle-memory basics.

Cursor for Reading and Reviewing

While Claude Code writes the code, you need a way to review what it wrote. Cursor fills this role perfectly. Keep it open in a separate window or monitor with the project directory loaded.

Why Cursor Specifically

You could use VS Code, Zed, or any other editor for this role. But Cursor has a specific advantage: its built-in AI features let you interrogate the code the agent just wrote. When Claude Code finishes a task, you can:

• Highlight a function the agent created and ask Cursor's inline AI "what edge cases does this miss?"
• Use Cmd+K to ask about architectural decisions in the diff
• Use tab completion to quickly extend or modify what the agent wrote

This creates a two-layer AI review process. The agent writes the code, then a separate AI instance reviews it from a fresh perspective. The two models catch different categories of mistakes because they approach the code with different contexts.

The Review Workflow in Practice

Here is the actual workflow I follow after every agent task:

1. Claude Code finishes and prints its summary
2. Switch to Cursor (Cmd+Tab or click on second monitor)
3. Open the Git panel to see the list of changed files
4. Review each diff - Cursor highlights additions and deletions inline
5. For anything non-obvious, select the code and ask Cursor to explain it
6. If something needs fixing, switch back to the terminal and tell Claude Code
7. If everything looks good, commit from either Cursor or a separate terminal

The key insight is that steps 2-5 happen in a different mental mode than the agent interaction. In the terminal, you are directing - telling the agent what to build. In Cursor, you are reviewing - reading critically and looking for problems. Keeping those in separate windows reinforces the mode switch.

What to Watch For During Review

After hundreds of agent-assisted sessions, these are the patterns I catch most often during the Cursor review step:

• Overly broad error handling. The agent wraps things in try/catch but catches generic errors instead of specific ones.
• Missing cleanup. The agent creates resources (files, connections, listeners) without corresponding cleanup in error paths.
• Style drift. The agent is good at matching project conventions when explicitly told, but sometimes drifts toward its training data patterns. A quick visual scan in Cursor catches this faster than reading in the terminal.
• Import organization. The agent sometimes adds imports in inconsistent positions. Cursor's linting integration flags this immediately.

Git Worktrees for Parallel Agents

When you need multiple agents working simultaneously and they might touch overlapping files, git worktrees give each agent its own working directory while sharing the same repository.

This is where the setup transitions from "convenient" to "force multiplier." Running parallel agents is how you turn a 4-hour feature sprint into a 45-minute one.

Understanding Git Worktrees

A git worktree is a linked working directory that shares the same .git metadata as your main checkout. Each worktree has its own files, its own branch, and its own index - but commits made in any worktree are immediately visible to all others because they share the same object database.

This is fundamentally different from cloning the repo multiple times. Clones are independent copies with separate histories that need to be synced. Worktrees are part of the same repository, just with different checkouts.

Setting Up Your First Worktree

The basic commands:

# Create a worktree for a feature branch
git worktree add ../myproject-feature-auth -b feature/auth

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../myproject-feature-auth

The convention I follow is to name worktree directories as {project}-{branch-short-name} and place them as siblings to the main checkout. So if your project is at ~/code/myproject, the worktrees go at ~/code/myproject-feature-auth, ~/code/myproject-fix-perf, etc.

The Parallel Agent Workflow Step by Step

Here is the complete workflow for running three agents in parallel on a feature, a bug fix, and a refactor:

Step 1: Create worktrees and branches.

# From your main project directory
git worktree add ../myproject-feature-search -b feature/search-improvements
git worktree add ../myproject-fix-memory -b fix/memory-leak-dashboard
git worktree add ../myproject-refactor-api -b refactor/api-response-format

Step 2: Open a terminal for each worktree.

If you use tmux, create a session with three panes:

# Create a new tmux session
tmux new-session -s agents -c ~/code/myproject-feature-search

# Split into panes (run these from within tmux)
# Ctrl+b % for vertical split
# Ctrl+b " for horizontal split

# Or create all three in one shot:
tmux new-session -s agents -c ~/code/myproject-feature-search \; \
  split-window -h -c ~/code/myproject-fix-memory \; \
  split-window -v -c ~/code/myproject-refactor-api

Without tmux, just open three terminal windows or tabs and cd into each worktree directory.

Step 3: Launch Claude Code in each terminal.

# In terminal 1 (feature/search-improvements)
cd ~/code/myproject-feature-search
claude

# In terminal 2 (fix/memory-leak-dashboard)
cd ~/code/myproject-fix-memory
claude

# In terminal 3 (refactor/api-response-format)
cd ~/code/myproject-refactor-api
claude

Step 4: Give each agent its task.

Each agent gets a focused prompt. The key is making tasks independent - each agent should own a distinct set of files to avoid merge conflicts later.

Step 5: Monitor, review, and merge.

As each agent finishes, review its changes in Cursor (you can have multiple Cursor windows for different worktrees), then merge branches back:

# From main branch
git checkout main
git merge feature/search-improvements
git merge fix/memory-leak-dashboard
git merge refactor/api-response-format

# Clean up worktrees
git worktree remove ../myproject-feature-search
git worktree remove ../myproject-fix-memory
git worktree remove ../myproject-refactor-api

Agent Teams vs. Manual Worktrees

Claude Code now has an experimental agent teams feature (enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). Agent teams let the lead session spawn teammates that coordinate through a shared task list and direct messaging. This is more automated than the manual worktree approach.

When to use which:

My default is still manual worktrees for most development work. I reach for agent teams when the task involves exploration or research where agents benefit from debating each other - like investigating a tricky bug with multiple possible root causes, or doing a parallel code review where different agents focus on security, performance, and correctness.

Avoiding Merge Conflicts Between Agents

The single most important rule for parallel agents: plan the file ownership before you start. If two agents both modify src/utils/helpers.ts, you are going to have merge conflicts. Before launching agents in parallel:

1. Break the work into tasks where each task touches a distinct set of files
2. If two tasks need to modify the same file, run them sequentially instead
3. For shared types or interfaces, have one agent create them first, then start the others

When conflicts do happen (and they will, occasionally), resolve them from your main checkout. Do not try to have an agent resolve merge conflicts from within a worktree - it gets confused about which version is "correct."

The CLAUDE.md File - Your Agent's Project Manual

One piece of the setup that is invisible but critical: the CLAUDE.md file in your project root. This is a markdown file that Claude Code reads at the start of every session, giving the agent project-specific context it cannot infer from the code alone.

A good CLAUDE.md for this workflow includes:

# Project Setup

## Build and Test
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Single test: `npm test -- --grep "test name"`

## Conventions
- Use named exports, not default exports
- Error handling: always catch specific error types
- Imports: group by stdlib, external, internal (with blank lines between groups)

## Architecture
- API routes: src/api/ (Express handlers)
- Business logic: src/services/ (pure functions, no HTTP)
- Database: src/db/ (Drizzle ORM, Postgres)
- See src/services/README.md for the service layer patterns

Keep it concise. Anthropic's own best practices emphasize: for each line in CLAUDE.md, ask "would removing this cause Claude to make mistakes?" If not, cut it. Bloated files cause the agent to deprioritize your actual instructions.

When running parallel agents in worktrees, each agent reads the same CLAUDE.md from the project root. This is another advantage of worktrees over clones - you maintain one source of truth for agent configuration.

The Full Layout

Three things on screen:

1. Primary terminal - Claude Code running in the main agent session (or a tmux session with multiple worktree panes)
2. Cursor - secondary window or second monitor, project directory loaded, Git panel visible
3. Utility terminal - small window for git commands, quick file checks, running the dev server, or tailing logs

This layout scales from one agent to five without any changes to the tooling. With one agent, the primary terminal is a single Claude Code session. With five, it is a tmux grid with five panes, each running Claude Code in a separate worktree. The Cursor window and utility terminal stay the same regardless.

Monitor Setup Recommendations

If you have a single monitor, tile the terminal on the left (60% width) and Cursor on the right (40%). The utility terminal can be a tab in your main terminal app or a small floating window.

With dual monitors, put the terminal(s) on your primary monitor and Cursor on the secondary. This matches the natural workflow - you look at the primary monitor most of the time (where the agent is working), and glance at the secondary for review.

With an ultrawide, split it into thirds: terminal left, Cursor center, utility/browser right. This is the most comfortable setup I have found for extended parallel agent sessions.

Common Pitfalls and How to Avoid Them

Running Claude Code inside Cursor's terminal. It works, but you lose the mental separation between action and review. You also lose screen space to Cursor's sidebar and tab bar. If you must run it this way, at least collapse all panels except the terminal.

Not using /clear between tasks. Every time you start a new task in Claude Code, clear the conversation with /clear. Leftover context from previous tasks pollutes the agent's reasoning and causes it to reference old code or outdated plans.

Forgetting to set up notifications. Without notifications, you will compulsively check the agent terminal every few seconds to see if it is done. This defeats the purpose of agent-driven development. Set up notifications and trust them.

Using file-based input for long prompts. If your task description is more than a few paragraphs, write it to a file and tell Claude Code to read it instead of pasting it directly. Long pastes can get truncated, especially in VS Code's terminal. Something like "Read the task description in /tmp/task.md and implement it" works reliably.

Not committing before starting agents. Always commit (or at least stash) your current work before launching agents in worktrees. If an agent goes sideways, you want a clean state to reset to. Git makes this trivially easy - there is no excuse for skipping it.

Comparison to Other Setups

Some developers run Claude Code inside the Cursor extension, using a single window for everything. This works for single-agent usage on small tasks. The disadvantage is that you lose the parallel capability and the action/review separation.

Others use Claude Code's VS Code extension alongside Copilot. This can create confusion when two AI systems try to assist simultaneously - Copilot suggests completions while you are typing prompts to Claude Code, or Claude Code's inline diffs conflict with Copilot's ghost text.

The minimal setup described here avoids both problems by keeping the AI writing tool (Claude Code in terminal) and the AI review tool (Cursor's features) in separate processes that never interfere with each other.

More on This Topic

• Terminal IDE for Multiple AI Agents
• Claude Code vs Copilot - Parallel Agents Advantage
• tmux Worktree Parallel Agent Management

Fazm is an open source macOS AI agent. Open source on GitHub.