Guide
The Best Terminal for Claude Code on macOS
Claude Code runs anywhere a shell runs, but the terminal you host it in decides how painful crashes, context switches, and multi-pane orchestration feel. This guide walks through why Onda is the best-fit terminal for Claude Code and how to set it up in five minutes.
Why the terminal matters for Claude Code
Claude Code spawns as a CLI process, holds context over long sessions, and benefits from programmatic terminal control. A terminal that exposes MCP lets Claude open panes and run commands directly; one that detects interrupted sessions lets you resume without re-typing the prompt.
If your terminal is a dumb text pane, Claude Code still works — but every crash costs you context, every new pane is a manual click, and Claude cannot orchestrate layouts on its own.
With MCP-enabled terminals, Claude calls `onda_pane_split` or `onda_workspace_create` the same way it calls any other tool. The loop tightens: Claude plans, acts, verifies — without you shuffling windows.
Install Onda and Claude Code together
Download Onda from onda.mindfullabai.dev, install Claude Code via `npm install -g @anthropic-ai/claude-code`, then run `claude` inside any Onda pane. Session detection starts automatically.
Onda has no Claude-specific setup — it detects the CLI by process name. Install both independently, then run Claude from any pane. Within a few seconds Onda attaches a "Claude Code" badge to the pane and starts tracking lifecycle events.
- Download Onda.dmg, drag to /Applications, launch (macOS 12+, Apple Silicon)
- Install Claude: `npm install -g @anthropic-ai/claude-code`
- Run `claude` in any Onda pane — no Onda config needed
- Session resume banner appears automatically when Claude exits unexpectedly
Enable MCP so Claude can control Onda
Onda exposes a Unix-socket MCP server with 21 tools. Add the server to your Claude Code config and Claude can open panes, run commands, and manage workspaces on your behalf.
In your Claude Code configuration (`~/.claude/mcp.json` or equivalent), add Onda as an MCP server pointing to the Unix socket. Claude then discovers tools like `onda_pane_split`, `onda_terminal_run`, `onda_workspace_create`. Ask Claude "open three panes for frontend, backend, and tests" and watch it happen.
The full tool list lives at /docs/mcp — 21 tools covering ping, status, app info, workspace CRUD, tab management, pane split/focus/close, terminal run/send/kill, and context snapshotting.
Session resume — the killer feature
When Claude Code crashes mid-task, Onda detects the exit, preserves the prompt and working directory, and offers a one-click "Resume Claude Code" banner. Restart time drops from 30+ seconds to under 2.
This is not rare. Claude Code sessions crash on network hiccups, OS sleep, and occasional process errors. Each manual recovery costs roughly 30-60 seconds of repeating yourself plus mental context switching. Over a week of agentic coding, that compounds.
Onda watches the pane's PTY exit code, detects the Claude process, and surfaces a resume action. The relaunch restores cwd, shell, and passes a resume flag if Claude Code supports it.
Workspaces for multi-Claude sessions
Running Claude Code across multiple projects? Create an Onda workspace per project. Each workspace has its own panes, cwds, and environment — swap in one keystroke, no tab soup.
Color-code workspaces by project (purple for the mobile app, green for backend). Each workspace remembers its panes, layouts, and last Claude Code session state. Switch with Cmd+number or from the workspace switcher.
Pair this with MCP: ask Claude to "create a workspace called 'refactor-auth' and split into three panes" and it does. The workspace persists across app restarts.
Troubleshooting common Claude + terminal issues
Most friction in Claude + terminal setups comes from three places: Node version mismatches, shell PATH issues, and cwd confusion when Claude opens new panes.
Use `nvm use --lts` before `npm install -g @anthropic-ai/claude-code` to avoid permission errors. Make sure your shell profile (`.zshrc`, `.bashrc`) exports the global npm bin on PATH. When Claude opens panes via MCP, cwd defaults to workspace root unless you pass an explicit path in the tool call.
- Claude command not found → check `npm bin -g` is on PATH
- Claude opens panes in wrong cwd → pass `cwd` param in MCP `onda_pane_split` call
- Session resume banner never appears → confirm the pane's process is named `claude` (not aliased)
- MCP tools not discovered → restart Onda after editing `~/.claude/mcp.json`
Frequently asked questions
Which terminal is officially recommended for Claude Code?
Anthropic does not endorse a specific terminal. Claude Code runs in any POSIX terminal. Onda is recommended by the Onda team because of native MCP integration and session resume — features Anthropic has not shipped for iTerm2 or Terminal.app. Use whatever fits your workflow.
Do I need a paid Claude plan to use Onda?
No. Onda and Claude Code are separate. Claude Code has its own pricing (Claude Pro or API key). Onda is free, with optional Pro at $3/month for unlimited workspaces and premium themes. You can use the Free tier of Onda with any Claude plan.
Can Claude control multiple terminals across multiple projects in Onda?
Yes, through MCP. Claude calls `onda_workspace_create` to spin up a project workspace, then `onda_pane_split` for layout, then `onda_terminal_run` to execute commands per pane. All 21 MCP tools are composable for multi-project orchestration.
Is there a latency penalty running Claude inside Onda vs iTerm2?
None perceivable. Both run Claude as a subprocess over a PTY. Onda uses xterm.js + node-pty; iTerm2 uses its own renderer. For Claude Code's interactive output, both stay comfortably above 60fps on Apple Silicon.
Does Onda work with Claude Code in headless mode?
Yes. Claude Code's headless and non-interactive modes run in any Onda pane. Onda detects the process the same way. If you run Claude in CI-style non-interactive mode, session resume is less relevant but MCP is still useful for orchestrating panes from outside.
Can I use Cursor or Windsurf with Onda instead of Claude Code?
Yes. Onda's MCP server is agent-agnostic — any MCP-speaking client works. Cursor and Windsurf both support MCP. Session resume currently detects Claude Code, Codex CLI, and Gemini CLI by process name; Cursor/Windsurf run as IDE extensions so session resume does not apply to them.
What about Claude Code running on Linux or Windows via WSL?
Claude Code itself runs on Linux and Windows, but Onda does not (yet). If you use Claude Code on Linux/WSL, the best terminals today are Ghostty, Alacritty, or Windows Terminal — none have Onda's MCP+resume combo. Onda cross-platform is on the roadmap.