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 terminal. It replaces the tab bar with a sidebar built for long-running coding agents and keeps the rest of Warp as it is.
|
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. 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. |
|
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. 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 |
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.
Download: grab the latest Harp-<version>.dmg from Releases 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):
./script/bootstrap # one-time: toolchain and build dependencies
./script/run # builds target/debug/bundle/osx/Harp.app and launches itscript/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).
The rings are on by default and show the agents you use:
- Codex: read from the
rate_limitsCodex 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.jsonhas nostatusLineyet, Harp adds one that sav 8B93 es the status line's input to~/.harp/claude-statusline.jsonand 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); its entries replace Harp's own readings of the same name.
The other extras are off by default. Turn them on in ~/.harp/settings.toml; the app reloads the
file when it changes.
[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: <script> rename <shell_pid> <group> <title>, <script> group <session_id> <old_group> <new_group>. |
appearance.vertical_tabs.full_tab_menu |
true |
false shrinks the tab and group menus to the essentials. Also in Settings > Appearance > Tabs. |
agents.third_party.should_render_cli_agent_toolbar |
false |
true brings back upstream's toolbar under CLI agent sessions. Harp doesn't need it for Claude Code's status (see below). |
Claude Code status needs no setup. Harp ships its own Claude Code plugin (based on Warp's,
MIT) in Harp.app/Contents/Resources/bundled/claude-plugin/harp and points every shell it opens
at it with CLAUDE_CODE_PLUGIN_DIRS, so each Claude Code started in Harp loads it for that session.
Nothing is installed into ~/.claude, and Claude Code in other terminals is not affected. If you
also have Warp's plugin installed, Harp uses its own plugin's reports and ignores the duplicates.
The plugin uses jq, which macOS 15 and later include.
Without a plugin (Codex, a Claude Code older than 2.1.280, or one started outside a Harp shell) the row still shows working and done, read from the spinner the agent puts in its own terminal title; "needs you" and the background dot need Claude Code's plugin. An agent that reports nothing at all, such as one in a tmux server that was running before Harp, says "Restart the agent here for status" in the card header.
Details for contributors
Removed on purpose: the tab bar's search field, view options and tab-config buttons in the sidebar layout (new tabs come from Cmd+T, a double-click or the right-click menu on empty sidebar space), the sidebar divider option and the title-strip panel toggles.
Development switches (environment, at launch): WARPOSS_STATUS_TRACE=1 logs every change of a
row's shown status to ~/Library/Logs/harp.log as a [status-check] line, for regression checks
against an agent's transcript. WARPOSS_SKIP_LOGIN=1 starts with a test user and fails every
authenticated request, for automated runs without a login. WARP_DATA_PROFILE=<name> (debug
builds) keeps settings and data in ~/.harp-<name>.
Identity: the name comes from app_display_name!() in app/src/lib.rs. Bundle id, URL scheme
and settings folder are set in app/Cargo.toml, app/src/bin/oss.rs,
crates/warp_core/src/channel/state.rs, crates/warp_core/src/paths.rs, script/macos/bundle,
script/macos/run, crates/warpui/src/browser.rs, app/channels/oss/com.dominikmartn.Harp.desktop
and flake.nix. Internal names stay Warp's: the warp-oss binary, the crates, the WARPOSS_*
switches and the @warp_* tmux options other tmux clients read.
Run ./script/presubmit (format, clippy, tests) before sending changes.
Harp is an unofficial fork of warpdotdev/warp and is not made, endorsed or supported by Warp (Denver Technologies, Inc.) or affiliated with them. "Warp" is their name. Please report issues with Harp here, not to Warp.
- Warp, the terminal Harp is built on, and the open-source projects it depends on (list).
- Sidebar icons from the Hugeicons free set (MIT) and
Phosphor (MIT); the licenses are in
app/assets/bundled/svg/hugeicons/andapp/assets/bundled/svg/phosphor/.
Like upstream, the code is under the GNU AGPL v3, except the warpui and
warpui_core crates, which are MIT. If you run a modified version for others over a
network, the AGPL asks you to offer them its source.