Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,038 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AgentHarbor

AgentHarbor

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.


Why

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.

Codex chat

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.

Features

  • Chat view of a live TUI - markdown, code blocks, diffs, tool cards and thinking blocks, rendered live from the session's .jsonl transcript.
  • TUI menus as buttons - permission prompts, AskUserQuestion questions 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.

How it works

  • The server launches Claude as claude --settings <AH_STATE_DIR>/hook-settings.json ... in new windows of a tmux session (default main). A SessionStart hook 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>/sessions and its current activity from the terminal.
  • AgentHarbor retains indexed Codex and Claude conversation transcripts under agentharbor-history in 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-json mode.

Requirements

  • 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

Install and run

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>:3001

Open 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 ..

Driving sessions from a shell: ah

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 chat

Without 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/.

Notifications

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

Configuration

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

Windows + WSL

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 search
  • AH_STATE_DIR must live on /mnt/c so 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.exe process that started them, so a tmux server spawned from a short-lived wsl.exe -e ... call takes its Claude agents down when that call returns.

Security

  • There is no TLS built in. Bind HOST to a LAN or VPN address (or 127.0.0.1 behind 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.

What is different from CloudCLI UI

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.

Contributing

See CONTRIBUTING.md. Bug reports and pull requests: https://github.com/vitalto/AgentHarbor/issues

License

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.

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages