Turtle

The AI terminal for Claude Code, Codex, and Gemini CLI.

Turtle is a macOS terminal built for agent-heavy coding sessions: select output and send it back to your agent, comment on scrollback like a code review, and tile up to six shells in one tab without losing the thread.

npm install -g turtle-terminal && turtle

Why Turtle?

Claude Code, Codex, and Gemini CLI already live in your terminal. The hard part is everything around them: scanning long output, feeding the right error back into the model, tracking side notes, and keeping multiple runs visible at once. Turtle makes those workflows first-class.

• Select -> send to agent. Highlight any error, diff, stack trace, or test failure and send it to the active agent as one clean prompt block.
• Comment on terminal output. Pin notes to scrollback, jump back to them later, and review a long agent run without losing context.
• Run a real split workspace. Use up to six panes per tab, drag dividers, zoom a pane, restore layouts, and keep separate agent/tool runs visible together.
• See failures faster. Errors, warnings, and passing tests get subtle overlays while output streams, without changing the underlying terminal bytes.
• Launch agents quickly. Start Claude Code, Codex, or Gemini CLI from the toolbar or command palette, then use quick actions for each tool's own commands.
• Stay local. No telemetry, no accounts, no hosted backend. Turtle talks to your shell through a system PTY and stores settings locally.

Agent Workflow

Turtle is designed around the loop most AI coding sessions fall into:

1. Launch claude, codex, or gemini from the toolbar, or open a normal shell.
2. Split the tab for tests, logs, a dev server, or another agent.
3. Select the exact output that matters and choose add to chat.
4. Add comments to important scrollback so you can return to decisions, errors, and follow-ups.
5. Use the status bar to jump back to running agents and see when background work finishes.

This makes Turtle useful as an AI terminal, an agent terminal, and a general macOS terminal emulator for developers who spend a lot of time in CLI coding tools.

Install

Requires macOS and Node.js 18+.

npm install -g turtle-terminal
turtle

Turtle is distributed as an npm CLI package, so there is no DMG, signing prompt, or app-store step. The turtle command launches the Electron app detached from the shell you started it from.

Update anytime:

npm update -g turtle-terminal

Run from source:

git clone https://github.com/nikhil-kapu/turtle-terminal.git
cd turtle-terminal
npm install
npm start

Features

| Feature | What it does | | --- | --- | | Select -> send | Send selected terminal output into Claude Code, Codex, or Gemini CLI as a clean prompt block. | | Terminal comments | Anchor notes to buffer lines and jump back to the relevant output later. | | Smart highlights | Highlight errors, warnings, and passing tests with a terminal-safe overlay. | | Split grid | Use up to 6 panes per tab, resize dividers, zoom panes, and restore layouts on relaunch. | | Agent awareness | See running-agent status, background completion notifications, and live status-bar timers. | | Agent quick actions | Send tool-native commands like model/status/MCP/compact from a status-bar menu. | | Click to place cursor | Click on the input line to move the cursor, with TUI mouse-mode handling. | | Themes and typography | Use built-in themes, auto-detected mono fonts, adjustable size, and line height. | | Background images | Add a local background image with adjustable dim and blur. | | Flexible tabs | Keep tabs on top, in a sidebar, or both. Reorder, rename, and restore them. | | Command palette | Search actions for splits, themes, tabs, launchers, settings, and panes. | | Drop files | Drop files into a pane to insert their shell-quoted paths. | | Terminal essentials | Find in buffer, clickable URLs, copy-on-select, 10k-line scrollback, and GPU rendering. |

Keyboard Shortcuts

| Keys | Action | Keys | Action | | --- | --- | --- | --- | | Cmd+T / Cmd+W | New tab / close | Cmd+D / Shift+Cmd+D | Split right / down | | Cmd+P | Command palette | Shift+Cmd+Enter | Zoom pane | | Cmd+1-9 | Switch tab | Cmd+[ / Cmd+] | Cycle panes | | Cmd+F | Find in buffer | Cmd+K | Clear buffer | | Cmd++ / Cmd+- / Cmd+0 | Text size | Cmd+, | Settings | | Cmd+C / Cmd+V | Copy / paste | Drag tab | Reorder |

How It Works

Turtle uses Electron, xterm.js, and prebuilt node-pty binaries. It opens your normal login shell with your existing aliases, PATH, git config, agent CLIs, and dotfiles.

The app does not send telemetry or terminal content to a server. Settings and restored layout state live in browser localStorage inside the local Electron app.

Contributing

Turtle is early and intentionally small. Useful contributions include bug reports, install edge cases, accessibility improvements, theme polish, agent-workflow ideas, and focused PRs.

• Read CONTRIBUTING.md before opening a PR.
• Open a bug report with your macOS version, Node version, install method, and the command you ran.
• Open a feature request with the agent workflow you want to improve, not just the UI control you want added.

Roadmap: scrollback restore across relaunches, font ligatures, per-agent profiles, broadcast input to all panes, richer shell integration, and Linux/Windows exploration.

If Turtle helps your AI coding workflow, star the repo so other Claude Code, Codex, and Gemini CLI users can find it.

License

MIT © Nikhil Kapu