Harp: the app icon and name above a Harp window with sessions grouped in the sidebar and a Claude Code session at work, with agents working, waiting for you, done and set aside

Run many Claude Code and Codex agents side by side, in one calm sidebar that tells you which one needs you.

Harp is an unofficial fork of the open-source [Warp](https://github.com/warpdotdev/warp) terminal. It replaces the tab bar with a sidebar built for long-running coding agents and keeps the rest of Warp as it is. ## What it adds

Sidebar rows showing needs you, background work, working, done and inactive

Working rings turning next to sessions whose agents are running

Agent states at a glance

Each row shows whether its Claude Code or Codex session is working, waiting for you or done, with an unread mark until you look. A dot means background work is still running; a moon marks a tab you set aside. Cmd+R renames a tab.

Groups that stay put

Put tabs into named groups. With the tmux integration on, the group and the order are stored on the tmux sessions, so they survive a restart and other tmux clients see the same layout.

Limit rings

Two rings per provider in the footer: the 5 hour window and the weekly limit. Hover one for the numbers and reset times. Codex's come from its own session logs, Claude's from Claude Code's status line (see below). Harp fetches nothing and reads no credentials.

Phone-friendly tmux

Tabs attached to tmux follow their session: name, group, read and inactive flags. A session started elsewhere, for example from your phone over ssh, can ask for a tab with tmux set-option @warp_adopt 1.

Everything else is upstream Warp, including its AI and cloud features (agents, Warp Drive, session sharing, login). They talk to Warp's servers exactly as upstream does; Harp adds no servers of its own. Logging in through Harp is untested. ## Install **Download:** grab the latest `Harp-.dmg` from [Releases](../../releases/latest) and drag Harp into Applications. Harp has its own bundle id (`com.dominikmartn.Harp`), URL scheme (`harp://`) and settings folder (`~/.harp`), so it runs next to Warp without sharing anything. **Updates:** Harp checks the latest GitHub release every 10 minutes, the same way Warp checks its own server. When the release's version is newer than `version` in `app/Cargo.toml` of the running build, Harp downloads its DMG in the background, checks that it is signed by Harp's Developer ID team, and offers to restart into it. To try this on an installed build, launch it with an older version: `open --env HARP_UPDATE_PRETEND_VERSION=0.0.1 /Applications/Harp.app`. **Build from source** (macOS, Rust toolchain from `rust-toolchain.toml`): ```sh ./script/bootstrap # one-time: toolchain and build dependencies ./script/run # builds target/debug/bundle/osx/Harp.app and launches it ``` `script/macos/run` signs with the first "Apple Development" identity in your keychain and falls back to an ad-hoc signature. A signed, notarizable release DMG comes from `script/release_macos` (see `--help`). ## Settings ### Limit rings The rings are on by default and show the agents you use: - **Codex:** read from the `rate_limits` Codex logs into `~/.codex/sessions` (or `$CODEX_HOME`). They appear once Codex has answered at least once. - **Claude Code:** Claude Code hands its plan limits only to its status line. On first start, if `~/.claude/settings.json` has no `statusLine` yet, Harp adds one that saves the status line's input to `~/.harp/claude-statusline.json` and prints nothing. A status line you already have is left alone; to keep yours and get the rings, save the input first, for example `"command": "tee ~/.harp/claude-statusline.json | your-command"`. The rings appear after Claude Code's next answer, for Claude.ai plans (not API keys). More providers can come from a JSON file another tool keeps current ([format](docs/limit-rings.md)); its entries replace Harp's own readings of the same name. ### Other extras The other extras are off by default. Turn them on in `~/.harp/settings.toml`; the app reloads the file when it changes. ```toml [integrations.limit_rings] enabled = true file = "~/.cache/limit-rings.json" [integrations.tmux] enabled = true ``` | Setting | Default | Effect | |---|---|---| | `integrations.limit_rings.enabled` | `true` | Shows the limit rings in the sidebar footer. | | `integrations.limit_rings.file` | `""` | Optional JSON file with more providers; `~` is your home folder. | | `integrations.tmux.enabled` | `false` | Tmux sync (names, groups, order, flags, adopting sessions) and agent detection inside tmux. Polls every 10 s. | | `integrations.tmux.session_script` | `""` | Optional script that renames and regroups instead of the built-in tmux commands: `