How to use Claude Code inside Onda terminal

If you've tried running Claude Code in a generic terminal, you already know the small frustrations: text rendering with weird spacing in some emulators, no clean way to split a pane between the agent and your editor, no project-scoped sessions when you switch context. None of these are deal-breakers, but they add friction to a tool that's supposed to remove it.

Onda is a modern macOS terminal we built specifically for AI-first development workflows. This guide walks through installing Claude Code inside Onda, why the combination works well, and a few workflows that have become part of my daily routine.

What is Claude Code

Claude Code is Anthropic's CLI for Claude — an interactive agent that runs in your terminal, reads your codebase, edits files, runs commands, and helps you ship software. It's not a chatbot wrapper around git: it's a real engineering teammate that lives in your shell.

You install it once, run claude in any project directory, and it becomes available as a long-running session that understands context across many tool calls.

What is Onda

Onda is a macOS terminal emulator built on Electron with xterm.js and node-pty. It ships with features that make AI-first development noticeably nicer:

• Mosaic split panes — split horizontally and vertically, resize, focus by keyboard. Agent on the left, editor or logs on the right.
• Workspaces — group tabs and panes per project. Switching workspace switches the entire context.
• TUI-correct rendering — characters render with proper spacing. Tools like Claude Code, vim, htop, and lazygit look exactly as they should.
• Plugin system — extend the terminal with Web Workers (rendered status bars, AI autocomplete, task launchers).
• Git integration — branch and dirty status visible without re-running commands.

Onda is currently on macOS only (Apple Silicon + Intel), free with an optional Pro tier.

Step 1 — Install Claude Code

Claude Code installs globally via npm. From any terminal:

npm install -g @anthropic-ai/claude-code

Verify the install:

claude --version

The first time you run claude in a project, it asks you to authenticate against your Anthropic account. After that, it picks up the session token from ~/.claude/.

Step 2 — Install Onda

Download Onda from onda.mindfullabai.dev. It's a standard .dmg install — drag to Applications, launch.

On first launch, Onda asks for the usual macOS permissions (Accessibility for global shortcuts, optional). The default theme is dark, the default shell is whatever your $SHELL points to (zsh on most modern macOS setups).

Step 3 — Run Claude Code inside Onda

Open Onda, navigate to your project, and run:

cd ~/Projects/my-app
claude

That's it. The agent starts, reads your repo, and you can begin a session.

The first time you run Claude Code in Onda, you should notice something: the rendering is correct. There's no extra spacing between characters, the box-drawing characters in Claude's UI are aligned, and ANSI colors are accurate. This is because Onda uses xterm.js with full Unicode support and proper PTY handling — it sounds like a low bar, but several popular terminals get this subtly wrong with TUI applications.

Workflow 1 — Agent + editor split

The single most useful Onda feature for Claude Code is the split pane.

1. Open a tab in your project directory.
2. Press Cmd+D to split vertically (or Cmd+Shift+D for horizontal).
3. In the left pane, run claude.
4. In the right pane, run your editor (nvim, lazygit, or whatever you use), or tail -f your dev server logs.

The agent operates on the left, you read or edit on the right, and there's no context switching between application windows. When the agent edits a file, you see the change reflected in the right pane immediately if your editor watches the filesystem.

Workflow 2 — Multiple agents in parallel

Some refactors benefit from running two agents simultaneously: one researching the codebase, the other implementing. With Onda you split into four panes:

+-----------------+-----------------+
|  claude (lead)  | claude (worker) |
+-----------------+-----------------+
|  editor / logs  |  test runner    |
+-----------------+-----------------+

Each claude session is independent. The lead session investigates and plans, the worker implements based on the plan you paste over. The bottom panes give you immediate feedback (test output, dev server logs).

This workflow is much harder in a single-pane terminal — you'd alt-tab between windows or fight tmux. In Onda it's the default.

Workflow 3 — Workspaces per project

If you work on multiple projects, Onda's workspaces map naturally to project context:

• Workspace "client-app" → 2 tabs: claude + dev server, panes laid out for your usual flow.
• Workspace "infra" → 1 tab: claude running in your terraform/ansible repo.
• Workspace "writing" → no claude, just nvim + a notes pane.

Cmd+1, Cmd+2, Cmd+3 to switch. Each workspace remembers its tabs, panes, working directories, and font size. When you come back to "client-app" the next morning, the layout is exactly where you left it. You re-run claude and pick up where you stopped.

Workflow 4 — Plugin: Claude session indicator

Onda's plugin system runs Web Workers that can render small UI elements in the status bar. A useful one for Claude Code is a session indicator that shows whether claude is currently running in any pane and how long the session has been active. This is a 50-line plugin that subscribes to Onda's pane events.

The full plugin source will land in the Onda plugin gallery soon — for now, the API is documented in the Onda plugin docs.

A note on speed and resource usage

Claude Code is mostly network-bound. The local CPU cost is negligible, but Onda is an Electron app, which means a few hundred MB of RAM per window. On modern Apple Silicon Macs this is irrelevant; on older Intel machines with 8GB you'll feel it if you also run Slack, a browser with 50 tabs, and Docker.

If you're on constrained hardware and rendering correctness isn't a priority, lighter terminals like kitty or alacritty are reasonable alternatives — they don't have GUI splits or workspaces, but they're memory-efficient.

Why this combination works

Claude Code is at its best when you can react quickly to what it does: read the diff, run the test, decide the next prompt. The bottleneck isn't typing — it's context. A terminal that gives you split panes, persistent workspaces, and correct rendering removes the small frictions between you and the agent.

Onda was built around this assumption. Every design decision — from xterm.js for rendering, to workspace persistence, to the plugin system — is in service of staying in flow with an AI agent in your shell.

Getting started

• Download Onda (free, macOS only)
• Claude Code docs (official Anthropic documentation)
• Install both, run claude in your favorite project, see how it feels

If you build a useful Onda + Claude Code workflow worth sharing, write to me — the next post in this series will collect reader workflows.