dominikmartn/harp

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.

What it adds

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 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 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); 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.

[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: rename <shell_pid> , 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= (debug builds) keeps settings and data in ~/.harp-.

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.

Based on Warp

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.

Credits

• 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/ and app/assets/bundled/svg/phosphor/.

License

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.