AgentHub/INSTALL.md

Installation

A step-by-step guide to get AgentHub — the local control surface for Claude Code agents — up and running on your machine, with optional sections for importing history and running in a container.

Fastest path — install it as a Claude Code plugin

If all you want is a working dashboard, skip every step below. From Claude Code:

/plugin marketplace add https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
/plugin install agenthub@agenthub

The next session start installs the hooks, boots the server, puts the agenthub CLI on PATH — no clone, no npm run setup, no npm run install-hooks, no manual npm start. Run /agenthub-doctor to check the result and /agenthub-open to build the UI and get the URL.

Requires Node >= 22.5 (a plugin install has no native better-sqlite3, so the server stores data through node:sqlite). Full behavior, including the uninstall cleanup, is in docs/PLUGINS.md.

Follow the steps below instead when you want a checkout — to develop the dashboard, run it from source, or stay on Node 20.

Requirements

Requirement	Version	Notes
Node.js	20+ (22+ recommended)	Required for server and client
npm	9+	Comes with Node.js
Claude Code	2.x+	Required for hook integration
Git	Any	Cloning the repository, and every lane operation (worktrees, branch/status reads)
tmux	3.x	Required for the run console — the browser terminal, agenthub lanes shell, typing /reload-plugins into a live pane, and the Codex nudge. See Step 0
Codex CLI	Any	Optional — only for lanes whose tool is codex
GitHub CLI (gh)	Any	Optional — only for agenthub lanes ci status and the PR stages of /agenthub:ship-full
Python	3.6+	Optional — only for scripts/expand-ts-module-docs.py (doc generation)
superpowers plugin	Any	Optional — required only by /agenthub:ship-feature and /agenthub:ship-feature-lane, which drive its skills step by step (and which the built-in pipeline templates name as their per-node commands). Nothing else in AgentHub needs it; /agenthub-doctor reports it as WARN when absent. Installed automatically by the plugin's SessionStart bootstrap (opt out with AGENTHUB_AUTO_INSTALL_PLUGINS=0); by hand: claude plugin install superpowers@claude-plugins-official

---

Step 0 — System packages

Node and npm are not enough: git backs every lane operation, and tmux backs the run console. The dashboard shells out to the tmux binary and has no bundled fallback, so without it Start Run and agenthub lanes shell fail while everything else keeps working.

sudo apt install git tmux        # Debian / Ubuntu
sudo dnf install git tmux        # Fedora / RHEL
brew install git tmux            # macOS
sudo pacman -S git tmux          # Arch

Windows has no native tmux. Run AgentHub under WSL2 and install it inside the WSL distro — a tmux from Git Bash or MSYS is not what the server executes.

Check it:

tmux -V          # e.g. tmux 3.4
git --version
node -v          # v20.x / v22.x / v24.x

Once the server is up you can ask it directly — this is the same probe the dashboard uses:

curl -s localhost:4820/api/run/tmux      # {"available":true}

No configuration is needed. AgentHub creates its own session per lane, named agenthub-lane-<id>, and never reads your ~/.tmux.conf for anything it depends on (mouse mode is set on the session explicitly). You can attach to the exact same pane from a normal terminal:

agenthub lanes shell             # from inside the lane's directory
tmux attach -t agenthub-lane-7   # or by name
tmux ls                          # every dashboard session is prefixed agenthub-lane-

Detaching is Ctrl-b d — it leaves the run alive, which is the whole point: the browser terminal and your local terminal are two clients on one pane, and restarting the dashboard never stops a run.

---

Step 1 — Clone the repository

git clone https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
cd AgentHub

---

Step 2 — Install dependencies

npm run setup

This installs all server and client dependencies, plus the VS Code extension, and links the agenthub CLI.

A plain root install already covers server and client — a postinstall hook installs the client dependencies automatically, so this alone is enough to build and run the dashboard:

npm install

npm run setup additionally installs the VS Code extension and links the agenthub CLI. (If you install with --ignore-scripts, the postinstall hook is skipped — run cd client && npm install manually in that case.)

Or via Makefile:

make setup

---

Step 3 — Start the dashboard

npm run dev

This starts two processes concurrently:

Process	URL	Description
Express server	http://localhost:4820	API, WebSocket, SQLite
Vite dev server	http://localhost:5173	React frontend with HMR

Open http://localhost:5173 in your browser.

Tip

When you run the dashboard directly on the host with npm run dev or npm start, the server automatically writes the Claude Code hook configuration to ~/.claude/settings.json. If you run the dashboard inside a container, install hooks from the host with npm run install-hooks instead — a hook path written from inside a container points at the container filesystem.

---

Step 4 — Start a Claude Code session

Start a new Claude Code session from any directory after the dashboard server is running. The hooks will fire automatically and your sessions, agents, and events will appear in real-time.

# In a separate terminal, from any project directory:
claude

---

Verification

After starting a Claude Code session, you should see:

• Sessions page — your session listed with status Waiting (a fresh CLI sitting at the prompt) or Active (mid-turn)
• Agent Board — a Main Agent card in the Waiting column until you type your first message; it flips to Working on UserPromptSubmit / PreToolUse and back to Waiting after each Stop
• Activity Feed — events streaming in as Claude Code uses tools
• Dashboard — stats updating in real-time
• Settings page — model pricing rules, hook configuration status, data export and cleanup tools

If nothing appears after 30 seconds, see SETUP.md.

PWA install (optional)

The dashboard is a Progressive Web App. After opening it in a supported browser (Chrome, Edge, Firefox), you can install it to your dock / home screen:

1. Look for the install icon (⊕) in the browser address bar, or open the browser menu → "Install app"
2. Once installed, the dashboard launches in its own window with no browser chrome
3. Offline support: previously visited pages and assets are served from the Service Worker cache when the network is unavailable

---

Step 5 — (Optional) Import existing Claude Code history

The server automatically imports every session under ~/.claude/projects/ on startup, so if you've used Claude Code on this machine before, your historical sessions, agents, events, token counts, and cost totals should already be visible in the Sessions list.

To bring in history from another machine, a backup, or a .tar.gz archive a teammate sent you, use Settings → Import History in the UI. It supports three modes:

flowchart LR
    UI["Settings →<br/>Import History"] --> M1["Rescan default folder<br/>~/.claude/projects"]
    UI --> M2["Scan a folder<br/>any absolute path"]
    UI --> M3["Upload files<br/>.jsonl / .zip / .tar.gz / .gz"]
    M1 --> P["Same parser as live<br/>hook ingestion"]
    M2 --> P
    M3 --> P
    P --> DB[("SQLite<br/>sessions + tokens + cost")]

    style UI fill:#a855f7,stroke:#c084fc,color:#fff
    style P fill:#f59e0b,stroke:#fbbf24,color:#000
    style DB fill:#10b981,stroke:#34d399,color:#fff

Re-imports are idempotent: sessions are deduplicated by UUID and compaction baselines preserve pre-compaction token totals, so running the importer twice never double-counts tokens or cost.

Verify it worked by opening the Analytics page and checking that per-model token totals and estimated cost look correct. Full walkthrough with per-OS archive commands in SETUP.md → Importing existing Claude Code history.

Optional: tune import limits

If you regularly import very large archives, these environment variables can be raised (the defaults are generous for typical use):

Variable	Default	Purpose
AGENTHUB_IMPORT_MAX_BYTES	1 GB	Maximum size per uploaded file
AGENTHUB_IMPORT_MAX_FILES	2000	Maximum files per upload request
AGENTHUB_IMPORT_MAX_EXTRACT_BYTES	4 GB	Ceiling on uncompressed bytes per archive (zip-bomb guard)

Set them before npm run dev or npm start:

AGENTHUB_IMPORT_MAX_EXTRACT_BYTES=17179869184 npm start   # allow 16 GB extraction

---

Production mode

To run as a single process serving the built client:

npm run build   # Build the React client
npm start       # Start Express serving client/dist on port 4820

Open http://localhost:4820 in your browser.

npm start (and agenthub start, its backgrounded form) only run while that process is alive — a reboot loses it. On Linux, run the server as a systemd --user service instead so it comes back on its own after every reboot, with no manual step and no Claude Code (or any other tool) needed to trigger it:

agenthub service install       # writes + enables ~/.config/systemd/user/agenthub.service
agenthub service status        # systemctl --user status agenthub
agenthub service uninstall     # disable and remove it

See README.md → Run as a service and, for plugin installs, docs/PLUGINS.md → Auto-start on boot.

---

Optional: Agent extension packs

This repository includes extension packs for both Claude Code and Codex.

• Claude Code loads project extensions from:
  • CLAUDE.md
  • .claude/rules/
  • skills/ (shipped as the agenthub plugin's skills)
  • agents/ (shipped as the agenthub plugin's agents)
• Codex project packs live under .codex/:
  • AGENTS.md
  • .codex/rules/
  • .codex/agents/
  • .codex/skills/

See .codex/README.md for Codex extension details.

---

Troubleshooting

npm run setup shows better-sqlite3 errors

This is expected and non-fatal. better-sqlite3 is a native C++ module listed as an optional dependency. If prebuilt binaries are not available for your Node version or platform, npm will print gyp/compilation errors but still complete successfully.

At runtime the server uses this fallback chain:

1. better-sqlite3 — used when prebuilt binaries are available (Node 20/22/24 on Windows x64, macOS arm64/x64, Linux x64/arm64)
2. node:sqlite — Node.js built-in SQLite module, used automatically on Node 22+ when better-sqlite3 is unavailable

If you see an error box at startup saying "SQLite backend not available", either:

• Upgrade to Node.js 22+ (recommended — zero native dependencies needed), or

• Install build tools so better-sqlite3 can compile from source:

  • Windows: npm install -g windows-build-tools or install Visual Studio Build Tools with the C++ workload
  • macOS: xcode-select --install
  • Linux: sudo apt install python3 make g++ (Debian/Ubuntu) or equivalent

  Then run: npm rebuild better-sqlite3

npm run dev fails immediately

Ensure both server and client dependencies are installed:

npm run setup

If the error mentions a missing module like express or react, dependencies may be incomplete. Delete node_modules in both root and client/, then re-run setup:

rm -rf node_modules client/node_modules
npm run setup

Server starts but client shows a blank page

The Vite dev server and Express server run on different ports. Make sure both are running (npm run dev starts both). Open http://localhost:5173, not http://localhost:4820, during development.

"Start Run" fails, or the terminal never attaches

The run console is tmux-backed. Check, in this order:

tmux -V                                   # not installed → see Step 0
curl -s localhost:4820/api/run/tmux       # {"available":false} → the SERVER cannot see tmux
curl -s "localhost:4820/api/run/binary?tool=claude"   # {"found":true,"path":"…"}

{"available":false} while your own shell finds tmux means the server runs with a different PATH — most often a systemd --user service, which does not read your shell profile. Fix it by installing tmux system-wide (/usr/bin/tmux) rather than into a shell-managed prefix, then agenthub service uninstall && agenthub service install.

The same PATH rule applies to claude and codex: a run starts the binary by name, so a claude installed only through an interactive shell's profile is invisible to a service-managed server. {"found":false} for the lane's tool is that case.

No sessions appearing after starting Claude Code

See SETUP.md — Troubleshooting for detailed hook debugging steps.

---

Ports

Service	Default	Override
Dashboard server	4820	DASHBOARD_PORT=xxxx npm run dev
Client dev server	5173	Edit client/vite.config.ts