# Harnss: a desktop shell for Claude Code, Codex and ACP agents > Harnss is an Electron desktop client that runs several AI coding agents side by side, rendering their tool calls as cards instead of raw JSON. It ships as a signed desktop build, and its own README warns that a large rewrite is pending. **OpenSource03/harnss** — Open-source, desktop client/UI build to harness Claude Code, Codex and any other Agent accepting Agent Client Protocol. Run multiple AI coding agents side by side with rich tool visualization, MCP integrations, built-in terminal, git, browser and just about anything else you may need. - Repository: https://github.com/OpenSource03/harnss - Website: https://harnss.app - Stars: 379 · Forks: 44 - Language: TypeScript - License: MIT - Published: 2026-09-14 · Updated: 2026-09-14 · Language: en - Canonical page: https://hysenlabs.com/projects/opensource03-harnss ## The problem Harnss targets: agent sprawl across terminals Running Claude Code in one terminal, Codex in another, and a third ACP agent somewhere else means three sets of scrollback, three sets of context, and no shared view of what each agent touched on disk. Harnss is built for that specific mess. The README frames it as "one interface to run, manage, and switch between AI coding agents," with each session keeping its own state, history and context, and switching between them described as instant. The audience is narrow and identifiable: developers who already have accounts or API keys for more than one agent and who work on several repositories at once. A single-agent user gets little from the multi-engine premise. The README also describes organizing projects into spaces with custom icons and colors, and scoping sessions, history and panel settings per project, which suggests the intended user juggles client work or several repos in parallel. ## How the Electron shell connects engines, MCP servers and panels The repository is a TypeScript monorepo-style layout: src/ for the renderer, electron/ for the main process, shared/ for code used by both, plus build/, public/ and scripts/. package.json points main at electron/dist/main.js, so the Electron main process is compiled separately from the Vite-built frontend. Two build configs confirm that split: tsup.electron.config.ts for the main process and vite.config.ts for the renderer. Three engines sit behind one UI. Claude Code runs through the Anthropic Agent SDK, Codex through a JSON-RPC app-server, and other agents through the Agent Client Protocol SDK (the @agentclientprotocol/sdk dependency). The engine table in the README states the requirements plainly: Claude Code needs a Claude account, either subscription or API key; Codex needs the Codex CLI in PATH plus an OpenAI API key. MCP servers are attached per project over stdio, SSE or HTTP, with OAuth handled by the app and server status plus tool counts surfaced in the UI. Rendering is the second half of the design: tool calls become interactive cards, file edits show word-level diffs with syntax highlighting, bash output appears inline, and subagent tasks nest with step-by-step progress. The README notes that Jira, Confluence and other integrations render with dedicated UIs rather than raw JSON. That rendering layer is the real product; the engines themselves are external processes. ## Installing Harnss and opening your first project The README does not document a source build for end users. Quick Start begins with downloading a release for your platform, so the supported path is the Releases page rather than a package manager. ```bash # from the README Quick Start: download the latest release, then # 1. open a project (point Harnss at any folder on disk) # 2. choose an engine: Claude Code, Codex, or an installed ACP agent ``` After that, the app asks you to point at a folder. Projects map to folders on disk, and each one keeps its own sessions, history and panel settings. Expect to see the project listed alongside any spaces you create. Developers who want to build from source have the scripts in package.json. The package manager is pinned, and the postinstall step rebuilds native Electron modules, which is where a source build usually fails first. ```bash pnpm install pnpm dev ``` pnpm dev runs Vite, a watch build of the Electron main process, and Electron itself concurrently. The repository also exposes pnpm dist, pnpm dist:mac, pnpm dist:win and pnpm dist:linux for packaged builds via electron-builder. Note that the README's engine table makes Codex conditional on the Codex CLI being in PATH, so selecting that engine without the CLI installed is not a supported configuration. ## Where Harnss gets in your way The README opens with a caution block stating 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 is the maintainer's own assessment, and it should govern how you treat the app: as a tool you try on real work, not one you build a team workflow around. The engine requirements are the second constraint. Claude Code needs a Claude account; Codex needs the Codex CLI in PATH and an OpenAI key. If you have neither, the multi-engine premise collapses to whatever ACP agents you can find, and the README does not enumerate them beyond pointing at the community registry. The release history reinforces the maturity point. The most recent release listed is v0.22.0-beta.2 from 2026-04-14, preceded by v0.22.0-beta.1 on 2026-04-05, while the last stable-looking tag, v0.21.5, dates to 2026-03-19. The repository's last push was on 2026-08-10, so work has continued after the last tagged release, but the newest published artifact is a beta. Anyone who needs a frozen, well-tested build should treat the beta tags as the current state and check what changed between them. Finally, the app is Electron with a Monaco-based editor component and a native PTY terminal. That is a heavy desktop footprint for what is, at bottom, a launcher and a renderer for external agent processes. If your workflow is one agent in one repository, a terminal and the agent's own CLI already do this with less surface area. ## Harnss compared with running the agent CLIs directly The honest alternative is not another GUI; it is the agent CLIs themselves. Claude Code and Codex both run in a terminal, and the ACP protocol means any agent can be driven by a client that speaks it. Choosing Harnss means choosing a client over the raw CLI. The difference is what the client adds. In the terminal, a tool call is text in scrollback. In Harnss it is a card with a diff, a syntax-highlighted file view, inline bash output, and nested subagent progress. The terminal has no per-project MCP server panel with OAuth handling and tool counts, no Changes panel summarizing file edits per turn, no git worktree management, no embedded browser, and no session search across titles and message content. Harnss also claims import and resume of conversations previously started in the Claude Code CLI, which is the bridge between the two approaches. The cost of that layer is indirection. Every agent runs as a child process the app manages, so a bug in the shell is a bug in your ability to talk to the agent. The README's early-development warning applies to exactly that layer. A reasonable split: keep the CLI for scripted or CI work, where a GUI has nothing to offer, and use Harnss for interactive sessions where you are reading diffs and switching between agents. ## Licence, releases and the cost of upgrading Harnss is MIT-licensed, with the author listed in package.json as Dejan Zegarac. MIT is permissive: you can fork it, ship it internally, or bundle it, provided the copyright notice and permission notice travel with it. This article is not legal advice, and the LICENSE file in the repository is the text that governs. Upgrade cost is the more practical question, and the material points to a specific answer. The pending rewrite described in the README means the current UI and codebase are not the long-term ones. If you adopt now, expect a migration at some point, and expect the release cadence to stay in beta tags until that rewrite lands. The gap between the newest beta (2026-04-14) and the last push (2026-08-10) suggests development continued without a tagged release, so watching the Releases page is more informative than watching the tag list. Configuration is a smaller cost. The README states that agent configuration, including custom agents with a command, arguments, environment variables and an icon, is managed through Settings rather than config files. That makes the app easy to set up and harder to version-control or reproduce across machines. The .harnss/ directory in the repository root hints at on-disk state, but the README does not document its contents, so treat per-machine setup as manual until you check. ## Conclusion Harnss fits engineers who already run several coding agents and want their sessions, MCP servers and git state in one window per project, and who can tolerate the early-development warning and a pending rewrite. It is the wrong choice if you want a stable, long-lived toolchain around a single agent, or if you cannot install Codex CLI and provide an OpenAI key for that engine. Before adopting it, check the Releases page for the current build, confirm which of the three engines you actually have credentials for, and read the open Issues to see whether the bugs described match your workflow. ## FAQ ### What is Harnss? Harnss is an MIT-licensed, cross-platform Electron desktop app that runs Claude Code, Codex and other ACP-compatible agents behind one interface, with per-project sessions, MCP server management, a terminal, git and a browser panel. The README describes it as a way to run and switch between agents without losing context or tool state. ### How do I install Harnss? The README's Quick Start says to download the latest release for your platform from the Releases page, then open a project and choose an engine. Building from source uses pnpm install followed by pnpm dev, with pnpm dist:mac, pnpm dist:win and pnpm dist:linux for packaged builds. ### Which agents does Harnss support? Three engines are listed: Claude Code via the Anthropic Agent SDK, Codex via a JSON-RPC app-server, and any ACP-compatible agent through the Agent Client Protocol SDK. The README states that Codex requires the Codex CLI in PATH plus an OpenAI API key or account, and Claude Code requires a Claude account. ### Is Harnss production ready? The README carries a caution that Harnss is pending a large rewrite toward a more production ready app, and a warning that it is in early development with issues to be expected. The most recent release listed is v0.22.0-beta.2 from 2026-04-14. ## Sources - [License: MIT](https://github.com/OpenSource03/harnss/blob/master/LICENSE) - [OpenSource03/harnss on GitHub](https://github.com/OpenSource03/harnss) - [Project website](https://harnss.app) - [README](https://github.com/OpenSource03/harnss/blob/master/README.md) - [Releases](https://github.com/OpenSource03/harnss/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/opensource03-harnss