Harnss: a desktop client for running Claude Code, Codex and ACP agents side by side

The problem Harnss targets: agent sprawl across terminals

Running one coding agent in a terminal is fine. Running Claude Code for one repository, Codex for another, and a custom ACP agent for a third is where the friction starts. Each tool keeps its own session history, its own permission model, and its own idea of what the working directory is. Switching means closing a terminal, remembering which conversation held the relevant context, and re-establishing state that the previous tool had already built.

Harnss is a desktop app aimed at that specific situation. The README describes it as "one interface to run, manage, and switch between AI coding agents", and the pitch is explicitly about not losing context, sessions or tool state when you move between them. The intended user is someone who already runs multiple agents, not someone looking for a first agent. If you use exactly one agent, the app mostly adds a graphical layer over something a terminal already does.

The repository is TypeScript, licensed MIT, and the package metadata names Dejan Zegarac as author. The last push to the default branch was on 2026-08-10. The README opens with a caution that Harnss is "pending a large rewrite to improve usability, performance and overall codebase into a more production ready app", and a warning that it is in early development with issues to be expected. That framing matters more than any feature list. You are evaluating a moving target, and the maintainer says so before you scroll.

How the multi-engine architecture works

The README lists three execution engines and the protocol each one speaks. Claude Code runs through the Anthropic Agent SDK and needs a Claude account, either a subscription or an API key. Codex runs over a JSON-RPC app-server and requires the Codex CLI in PATH plus an OpenAI API key or an equivalent. Everything else goes through the Agent Client Protocol, which is why the project depends on @agentclientprotocol/sdk in package.json.

That dependency list is the clearest view of the architecture available. Alongside the ACP SDK sit @anthropic-ai/claude-agent-sdk, @modelcontextprotocol/sdk for MCP servers, and @huggingface/transformers, which is presumably what backs the on-device Whisper option for voice input. The app is Electron, and the README badge pins Electron 40.

Sessions are the unit of isolation. Each engine session carries its own state, history and context, and the README states that sessions, history and panel settings are all scoped per project. Projects map to folders on disk, and spaces group projects into named collections with custom icons and colors. Tool calls are not dumped as raw JSON: the README says file edits render as word-level diffs with syntax highlighting, bash output appears inline, and subagent tasks nest with step-by-step progress. A separate Changes panel summarizes file changes per turn. How much of that rendering is generic and how much is MCP-specific is not spelled out; the README claims dedicated UIs for Jira, Confluence and "other integrations", which implies per-integration work rather than a universal renderer.

Installing Harnss and opening a first project

The README does not document a package-manager install. Its Quick Start points at the Releases page and asks you to download the build for your platform. The repository does contain a full build pipeline, so building from source is possible, but treat that as a maintainer path rather than a supported one.

Step one is the download. Step two is pointing the app at a folder, and step three is choosing an engine.

# No install command is documented in the README.
# Download the build for macOS, Windows or Linux from:
# https://github.com/OpenSource03/harnss/releases/latest

If you build from source instead, the scripts in package.json are the entry points. Note the packageManager field, which pins pnpm 10.26.0.

pnpm install
pnpm dev
pnpm build
pnpm dist

pnpm install triggers a postinstall step that runs electron-rebuild, skipping electron-liquid-glass on non-macOS platforms. pnpm dev runs Vite, the Electron build in watch mode, and Electron itself concurrently. pnpm build produces the Electron bundle and the Vite front end, and pnpm dist packages it with electron-builder using electron-builder.config.js. Platform-specific variants exist as dist:mac, dist:win and dist:linux.

Before any of that is useful, the engine has to be reachable. Codex needs the Codex CLI in PATH; Claude Code needs a Claude account. The README says custom agents are added by specifying a command, arguments, environment variables and an icon through Settings, and that all configuration is managed there rather than in config files. The repository does contain a .harnss/ directory at the top level, so state does land on disk somewhere, but the README does not document its contents.

Where Harnss gets in the way

The rewrite notice is the first limitation and the largest one. A pending rewrite of the codebase means the current version is not the version the maintainer intends to support long term. Anything you configure now, including custom agents and per-project settings, may not carry across. The README does not describe a migration path, and it does not document rollback between versions.

Engine support is narrower than the tagline suggests. Claude Code and Codex have explicit requirement rows in the README table. ACP agents are supported in principle, but the README does not enumerate which ones are known to work, so the honest answer for any specific ACP agent is that you have to try it. Custom agents are configured by hand.

The release history is another signal. The most recent releases listed are v0.22.0-beta.2 and v0.22.0-beta.1, both beta builds, with v0.21.5 as the last non-beta entry. Beta releases as the newest artifacts are consistent with the early-development warning, and they mean the newest features are also the least settled.

Finally, this is a desktop Electron app with a broad surface: PTY terminal, embedded browser, git operations, MCP transports over stdio, SSE and HTTP, plus OAuth flows. Each of those is a place where platform differences can surface. The README lists macOS, Windows and Linux, and the postinstall script already special-cases macOS, which tells you the platform paths are not identical. If your work is one agent in one repository, a terminal plus the agent's own CLI is the smaller and more predictable tool.

Harnss versus running the agent CLIs directly

The real alternative is not another GUI. It is the combination you already have: the Claude Code CLI, the Codex CLI, and a terminal multiplexer or a few terminal tabs. That setup has one advantage Harnss cannot match, which is that it is the interface the agent vendors build and test against first. New agent capabilities appear in the CLI before any third-party client can render them.

The difference in approach is what each one optimizes for. The CLI path optimizes for fidelity and low overhead: one process, one session, no intermediate layer. Harnss optimizes for parallel sessions and visibility. It keeps multiple agent sessions alive at once, renders each tool call as an interactive card instead of a JSON blob, and keeps a terminal, a browser, git and MCP servers mounted in the same window so you are not alt-tabbing between them.

That trade is real in both directions. With Harnss you get a Changes panel that summarizes file edits per turn and word-level diffs without leaving the chat, plus background task agents that keep running while you work in another session. With the CLIs you get the raw output, which is harder to read but never lags behind the agent's own feature set. The README also notes that Harnss can import and resume conversations previously started in the Claude Code CLI, which softens the switch but does not eliminate the layer.

There is a middle option worth naming: keep the CLIs and add a terminal workspace manager. You lose the tool-call visualization and the unified MCP panel, and you keep full protocol fidelity.

Licence, maintenance and what an upgrade costs

Harnss is MIT licensed, stated in both the README badge and the license field in package.json. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the plain reading of the licence text, not legal advice, and it says nothing about the licences of the agents you connect to or the MCP servers you install, which are separate agreements you accept when you configure them.

Maintenance is the harder question. The last push was on 2026-08-10, and the repository is not archived. The README's own caution about a pending rewrite is the most useful maintenance fact available, because it tells you the maintainer's attention is directed at a future version rather than incremental polish of this one. The release list supports that reading: the two newest entries are beta builds of the same minor version.

Upgrade cost has two components. The first is the Electron and dependency surface. The app depends on the Anthropic Agent SDK, the ACP SDK, the MCP SDK and Hugging Face Transformers, each versioned independently in package.json. When an upstream protocol changes, the app has to follow, and the README documents no compatibility matrix for older agent versions. The second is your own configuration. Because custom agents and MCP servers are configured through Settings rather than config files, there is no obvious file to diff or version-control before an upgrade. The README does not document export or backup of that configuration, so plan on re-entering it if something goes wrong.

Editorial conclusion

Adopt Harnss if you already run more than one coding agent and want their sessions, terminals, MCP servers and git state in a single window, and if you can tolerate the early-development warning and the announced rewrite. Do not adopt it if you need a stable tool for a team, or if you only use one agent, since a terminal already covers that case. Before installing, verify that your agent CLI is on PATH and that your account type is supported, check the release page for a build for your platform, and read the rewrite notice in the README to decide whether you want to invest in the current version.

Frequently asked questions

Official sources

1. License: MIT
2. OpenSource03/harnss on GitHub
3. Project website
4. README
5. Releases