Web UI for your live AI CLI agents.
Run Claude Code and Codex agents in tmux and drive them from a browser on your desktop or phone,
without giving up the real terminal.
AgentHarbor is a modified version of CloudCLI UI (https://github.com/siteboon/claudecodeui). It is not the original CloudCLI UI and is not affiliated with or endorsed by Siteboon AI B.V.
Claude Code is at its best as an interactive TUI: slash commands, /model, Shift+Tab permission
modes, menus, hooks. Web front-ends usually replace that TUI with an SDK or stream-json process,
so the agent you chat with in the browser is not the one you can attach to from a terminal, and it
dies with the web server.
AgentHarbor runs each Claude Code or Codex TUI in its own tmux window and puts a chat UI on top of it:
- the same agent is reachable from the browser and over ssh/mosh +
tmux attach; - agents survive server restarts, browser reloads and dropped mobile connections;
- nothing is emulated: what you type in the web composer is typed into the TUI.
Choose OpenAI Codex in the model picker. The picker lists the models and reasoning effort levels from the local Codex catalog. The web composer pastes into the same tmux pane you see in Terminal. Codex records the conversation in its native rollout file, which AgentHarbor follows for replies, tool activity and token usage. Stop sends Escape.
The Conversations tab includes sessions started in Codex CLI or the editor. AgentHarbor indexes the native rollout files and follows new activity. Sessions held by another Codex process can be read in the browser while that process owns the thread.
Install Codex CLI 0.169.0 or a compatible version. AgentHarbor launches codex --no-daemon
and resumes existing conversations by their exact native ID. Run codex login under
the account that runs Codex. For Windows Codex
through WSL, set AH_CODEX_CMD to the absolute WSL path of codex.exe and
AH_CODEX_HOME to the WSL path of its Codex home.
ah new --provider codex --project P "task"
ah read <session>
ah send <session> "follow-up"Set "provider": "codex" in the CLI configuration or AH_PROVIDER=codex to use Codex
by default for ah new and ah models. Follow-ups go into the active TUI. Finish any
pending dialog or terminal draft before sending another message from the chat.
AgentHarbor starts Codex with on-request approvals and its automatic reviewer. Routine
commands run in the session's sandbox. The reviewer evaluates requests for additional
access and can deny destructive actions. Set AH_CODEX_SANDBOX_MODE=workspace-write
or read-only to choose the sandbox for new conversations. To grant the CLI full access
under the host account, set AH_CODEX_SANDBOX_MODE=danger-full-access. This passes
--dangerously-bypass-approvals-and-sandbox when AgentHarbor starts or resumes a TUI.
An already running TUI keeps the permissions it was launched with.
- Chat view of a live TUI - markdown, code blocks, diffs, tool cards and thinking blocks, rendered
live from the session's
.jsonltranscript. - TUI menus as buttons - permission prompts,
AskUserQuestionquestions and the folder-trust dialog show up as buttons in the chat. - Terminal tab - attaches to the very same tmux window, for anything the chat does not cover.
- Many agents at once - every session is its own tmux window; the sidebar shows which agents are busy, waiting for input or idle. The Running tab includes live Claude and Codex sessions.
- Subagents and background commands - panels above the composer show which subagents work right now (with their own steps) and which shell commands run in the background; both can be stopped.
- Images and files - paste or attach images (they reach the TUI as
[Image #N]); every file path an agent writes in the chat gets a download button, images preview inline and PDF, video, audio, markdown and text open in a viewer. - Sessions from other terminals - a Claude session already running in another terminal is shown read-only and can be moved into tmux from the chat; a session is never resumed twice.
- Idle agents close themselves after a time set in Settings -> Agents -> Runtime (the conversation stays and resumes on the next message).
- Shut down when all agents finish - a one-shot switch waits for Claude and Codex to finish. Active turns, running background work, and Codex sessions with unknown activity or a pending retry hold off shutdown. After two quiet minutes it starts a 60-second OS countdown that can be cancelled in Runtime.
- File tree and editor, git panel (stage, commit, branches, worktrees), MCP server and skills management, plugins. A bundled optional plugin, Pages, adds a sidebar button that shows a folder of HTML reports and dashboards as live thumbnails and opens them in place.
- Responsive / PWA - usable from a phone; the chat composer, menus and terminal all work on a small touch screen.
- Login required - single-user account stored in a local SQLite database.
The Claude permission mode picker sends Shift+Tab to its TUI. For Codex, the model picker
applies model and effort to the current conversation. You can also type /model in Terminal.
- The server launches Claude as
claude --settings <AH_STATE_DIR>/hook-settings.json ...in new windows of a tmux session (defaultmain). ASessionStarthook from that settings file records which tmux pane runs which Claude session. - Messages from the web are typed into the pane (
tmux send-keys); menus are parsed from the pane and answered the same way. - The chat is rendered from the session transcript (
<CLAUDE_CONFIG_DIR>/projects/**/<session>.jsonl), which is polled (inotify does not work on/mnt/c). - Claude's own status files (
<CLAUDE_CONFIG_DIR>/sessions/<pid>.json: busy / waiting / idle) drive the activity indicators. - For Codex, the tmux pane title identifies the native thread. AgentHarbor reads its rollout
from
<CODEX_HOME>/sessionsand its current activity from the terminal. - AgentHarbor retains indexed Codex and Claude conversation transcripts under
agentharbor-historyin each provider's local profile. It uses hard links where available, so both filenames share the same contents. If the CLI removes a transcript during cleanup, AgentHarbor can restore its native file for reading and resuming the chat. Deleting a conversation from disk in AgentHarbor also deletes its retained transcript. - The server never runs Claude in SDK or
stream-jsonmode.
- Linux, or Windows via WSL 2
- tmux >= 3.3
- Node.js 22
- A signed-in Claude Code or Codex CLI for the provider you use
git clone https://github.com/vitalto/AgentHarbor.git
cd AgentHarbor
npm ci
npm run build
npm run server # serves the built UI and API on http://<HOST>:3001Open the URL, create the account on first visit, pick a project folder and start an agent.
Make sure the tmux session exists (tmux new -d -s main) before starting agents.
For development with hot reload: npm run dev (Vite on port 5173 plus the API server).
The package also exposes an agentharbor command (agentharbor status, agentharbor --port 8080,
agentharbor help) when installed with npm link or npm install -g ..
ah (bin/ah.mjs, plain Node 18+, no dependencies) lets an agent, or you, work with other
sessions: hand a task over to a project the current one depends on, or continue a long job in a fresh
session when the context fills up.
ah projects # registered projects
ah ls [--project P] [--recent N] # live agents with busy/idle, or recent conversations
ah new [--project P] [--model M --effort E] "task" # project defaults to the current directory
ah send <session> [--model M --effort E] "text" # a busy session queues it
ah read <session> [--last N] # last N messages
ah usage [session] # context use; default: the calling agent session
ah models # values for --model / --effort
ah notify [--title T] "text" # push to subscribed browsers; opens the caller's chatWithout the text argument new and send read the message from stdin. Create a key in
Settings -> API keys and save it as ~/.agentharbor/cli.json:
{"url": "http://localhost:3001", "apiKey": "ck_..."} (AH_URL / AH_API_KEY override it).
skills/agentharbor is a Claude Code skill that teaches agents these commands; copy or link it into
~/.claude/skills/.
Settings -> Notifications subscribes the current browser to Web Push. AgentHarbor watches every Claude
process on the machine, in tmux or not, and pushes when an agent finishes a turn (with the last thing
it wrote) or stops on a question or menu; agents can push their own messages with ah notify or
POST /api/notifications/send ({"message", "title"?, "sessionId"?}). Each browser picks its own
categories: agent finished, agent waits for an answer, messages from agents, system. A push about a
chat that is open and focused on that device is not shown.
Browsers allow push only on a secure origin: https, or http://localhost. For plain http on a LAN or
VPN address, mark it as secure in Chrome once per device with
chrome://flags/#unsafely-treat-insecure-origin-as-secure (the settings page shows the steps).
Set variables in the environment or in a .env file in the repository root (see .env.example).
| Variable | Default | Meaning |
|---|---|---|
AH_TMUX_SESSION |
main |
tmux session whose windows hold the agents |
AH_CLAUDE_CMD |
claude |
Claude Code command. A path ending in .exe means the Windows claude.exe via WSL interop and turns on Windows <-> WSL path translation |
AH_CLAUDE_ARGS |
(empty) | Extra flags for every launch, e.g. --permission-mode default |
CLAUDE_CONFIG_DIR |
~/.claude |
Claude Code's config directory (projects, sessions) |
AH_STATE_DIR |
~/.agentharbor |
AgentHarbor state (hook settings, pane registry). Must be writable by the Claude process |
AH_IDLE_CLOSE_MINUTES |
60 |
Close unattended idle Claude and Codex terminals after this many minutes. Set to 0 to keep them open. Runtime settings override these environment defaults for both providers. |
AH_ATTACHMENT_RETENTION_DAYS |
7 |
Keep temporary copies of attachments staged for Windows for this many days. Conversation history is stored separately. |
AH_BACKGROUND_REMINDER_MINUTES |
60 |
Remind an idle agent about background work after 1, 3, 7… intervals. For Codex, timing starts when AgentHarbor first observes a running background terminal. Set to 0 to disable. |
AH_API_ERROR_RETRY_ATTEMPTS |
3 |
Maximum consecutive continuation prompts after transient API or connection errors. Set to 0 to disable. |
AH_API_ERROR_RETRY_DELAY_MINUTES |
1 |
Delay before the first retry. Subsequent delays grow by a factor of three. |
AH_PROJECTS_DIR |
(none) | Folder the New Project wizard lists first, to open a project from it or create one by typing a name (an absolute path; with a Windows Claude also D:\Develop). Default only: choosing another folder in the wizard overrides it |
WORKSPACES_ROOT |
home folder | Projects must lie under this folder. With a Windows Claude every mounted drive (/mnt/c, /mnt/d...) is allowed as well; Windows system folders never are |
AH_WINDOWS_RIPGREP |
(none) | WSL path to a Windows rg.exe (ripgrep release). Conversation search then reads transcripts on /mnt/<drive> with it instead of through the slow 9p mount, about 10x faster |
CONTEXT_WINDOW |
by model | Context window the token counter measures against. Unset: 1M for Claude 5 models and [1m] variants, 200k for older ones |
SERVER_PORT |
3001 |
HTTP / WebSocket port |
HOST |
0.0.0.0 |
Address to bind to |
DATABASE_PATH |
~/.agentharbor/auth.db |
SQLite database with the login account and app settings |
You can drive Claude Code for Windows from tmux in WSL, so the agents work on Windows paths with Windows tooling while AgentHarbor and tmux run in WSL:
AH_CLAUDE_CMD=/mnt/c/Users/<you>/.local/bin/claude.exe
CLAUDE_CONFIG_DIR=/mnt/c/Users/<you>/.claude
AH_STATE_DIR=/mnt/c/Users/<you>/.agentharbor
AH_WINDOWS_RIPGREP=/mnt/c/<path>/rg.exe # optional, faster conversation searchAH_STATE_DIRmust live on/mnt/cso the Windows Claude process can read the hook settings and write the pane registry.- Start the tmux server from a long-lived WSL session (for example a systemd user service or a
terminal you keep open). Windows binaries launched through WSL interop die together with the
wsl.exeprocess that started them, so a tmux server spawned from a short-livedwsl.exe -e ...call takes its Claude agents down when that call returns.
- There is no TLS built in. Bind
HOSTto a LAN or VPN address (or127.0.0.1behind a reverse proxy with TLS); do not expose the port to the internet. - A login is required for the UI, the API and the WebSocket. Anyone who logs in controls your agents and, through them and the terminal tab, your shell account.
See SECURITY.md for the threat model and how to report a vulnerability.
AgentHarbor started from CloudCLI UI and keeps its chat rendering, file tree, git panel, settings
and plugin system. It replaces the SDK-based Claude runtime with the tmux/TUI runtime described above
and removes: the Cursor, OpenCode and Gemini providers, voice input, TaskMaster / PRD editor,
browser use, scheduled messages, /api/agent, the Electron desktop app, the Docker sandbox, edit and
resend, fork, the model / effort / permission pickers and AI commit messages.
See CONTRIBUTING.md. Bug reports and pull requests: https://github.com/vitalto/AgentHarbor/issues
GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), see LICENSE for the full text, including the additional terms under Section 7, and NOTICE.
AgentHarbor is a modified version of CloudCLI UI (https://github.com/siteboon/claudecodeui), copyright Siteboon AI B.V. and contributors. Modifications copyright 2026 vitalto. If you run a modified version as a network service, you must offer its source code to its users.