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`](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 (3.7+ for pane scrollbars) | **Required for the run console** — the browser terminal, `agenthub workspace shell`, and typing `/reload-plugins` into a live pane. See [Step 0](#step-0--system-packages) |
| Codex CLI | Any | Optional — only for lanes whose tool is `codex` |
| GitHub CLI (`gh`) | Any | Optional — only for `agenthub workspace ci status` |
| Python | 3.6+ | Optional — only for `scripts/expand-ts-module-docs.py` (doc generation) |

---

## 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 workspace shell`
fail while everything else keeps working.

```bash
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.
On a native Windows install, workspace terminals are unavailable, but Settings →
Agents still detects each AI CLI through `PATHEXT` (`claude.exe`, `codex.cmd`)
and runs a `.cmd` updater or npm through `cmd.exe`.

A terminal pane gets a draggable scrollbar only on **tmux 3.7+** — older
versions work, just without it, and `/agenthub-doctor` warns. Homebrew ships the
latest (`brew upgrade tmux`); Ubuntu 24.04's apt has 3.4, so build the release:

```bash
sudo apt install build-essential pkg-config libevent-dev libncurses-dev bison
curl -fsSL https://github.com/tmux/tmux/releases/download/3.7c/tmux-3.7c.tar.gz | tar xz
cd tmux-3.7c && ./configure && make && sudo make install   # into /usr/local/bin
```

A tmux server already running keeps its old version until every tmux session
has closed (or the machine reboots) — only then do the scrollbars appear.

Check it:

```bash
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:

```bash
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, the hidden status bar and the scrollbar are set on the
session explicitly). You can attach to the
exact same pane from a normal terminal:

```bash
agenthub workspace 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.

### macOS

Status: **code-audited, untested on a Mac.** The Mac-specific paths below are
covered by Linux-side unit tests only; the checklist at the end of this section
is what a Mac user runs to confirm them.

```bash
brew install node git tmux       # Node >= 22.5 for the plugin install (nvm works too)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # where the plugin puts `agenthub`
```

- **Node:** a plugin install needs **>= 22.5** (it stores data through
  `node:sqlite`); a checkout still runs on Node 20. The `agenthub` launcher
  pins the node that installed it and falls back to `node` on `PATH` when a
  `brew upgrade` or `nvm` switch deletes that binary.
- **Starts at login once you turn it on (LaunchAgent).** Off by default; with
  Settings → About → **Start AgentHub automatically** on, the plugin bootstrap
  installs `~/Library/LaunchAgents/io.smartgift.agenthub.plist` (a checkout:
  the same switch, or `agenthub service install`), so the dashboard comes back after every login with no
  Claude Code session, and launchd restarts it if it dies. Lane panes survive
  a restart of the server. Its output goes to `~/Library/Logs/agenthub.log`.
  A LaunchAgent needs a login at the Mac itself; over SSH only, or when
  `launchctl` fails, the server is a detached process started by the next
  Claude Code session (within about 10 s) or by `agenthub start`, as before. A
  discovery entry left over from before the reboot is ignored, so a recycled
  pid can never pass for a live dashboard.
- **Started from a Claude Code session.** The server drops the variables that
  describe that session (`CLAUDECODE`, `CLAUDE_CODE_SESSION_ID`,
  `CLAUDE_PLUGIN_ROOT`, …) before anything else runs, so lane panes do not
  inherit them. Your own configuration (`CLAUDE_CONFIG_DIR`,
  `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_*`) passes through. A tmux server that
  an older build started keeps its dirty global env until it exits
  (`tmux kill-server` once, with no run you care about open).
- **Paths.** A lane's directory is stored by its real path, so a typed `/tmp/x`
  becomes `/private/tmp/x` and a differently-cased path on a case-insensitive
  volume becomes the one on disk — that is what sessions report, so they bind.
  Lanes created before this change keep the string they were created with.
- **Account switching** uses the login Keychain item `Claude Code-credentials`;
  macOS may ask once for permission the first time.
- **Option key** in the browser terminal types special characters (it is not
  sent as Meta).

**Mac checklist** — please run it and report the result on issue #22:

1. Fresh plugin install from a Terminal `claude` session: the dashboard answers on `http://localhost:4820`, `~/Library/LaunchAgents/io.smartgift.agenthub.plist` exists, and `/agenthub-doctor`'s launchd row says the LaunchAgent is current and running.
2. `tmux show-environment -g | grep -i claude` prints nothing.
3. Add a Repo lane by typing its path in a different case: sessions bind to it, and `agenthub stage plan` inside it moves the map.
4. **Start Run** in the browser: the terminal attaches, typing works, an image paste into `claude` works, and `exit` returns to the workspace home.
5. Changes panel: diff, stage and commit on a lane.
6. Switch profile and check `claude /status` shows the new account. Repeat with a non-default `CLAUDE_HOME`, which also checks the Keychain service name.
7. `brew upgrade node && brew cleanup`, then `agenthub status` still works.
8. Reboot and log in WITHOUT opening `claude`: the dashboard answers within about 10 s (`agenthub service status` shows `state = running`).
9. `kill <server pid>` (from `agenthub status`): it is back within a few seconds.
10. With a lane run open, `/agenthub-update` completes, the server restarts on the new version, the plist names the new cache directory, and the run's terminal is still alive.
11. `agenthub service uninstall`: the plist is gone and nothing restarts the server after a `kill`.

---

## Step 1 — Clone the repository

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

---

## Step 2 — Install dependencies

```bash
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:

```bash
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:

```bash
make setup
```

---

## Step 3 — Start the dashboard

```bash
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` — unless the `agenthub` plugin is enabled there, whose own hooks already run; then it removes any copies a checkout wrote instead, since two sets post every event twice. 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.

```bash
# 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** — data export and cleanup tools on the Dashboard tab; Claude Code's model pricing rules, hook configuration status and CLAUDE_HOME on **Settings → Claude Code → Overview**

If nothing appears after 30 seconds, see [SETUP.md](./SETUP.md#troubleshooting).

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

```mermaid
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](./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`:

```bash
AGENTHUB_IMPORT_MAX_EXTRACT_BYTES=17179869184 npm start   # allow 16 GB extraction
```

---

## Production mode

To run as a single process serving the built client:

```bash
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. Run the server as a systemd `--user`
service (Linux) or a LaunchAgent (macOS) 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:

```bash
agenthub service install       # Linux: ~/.config/systemd/user/agenthub.service
                               # macOS: ~/Library/LaunchAgents/io.smartgift.agenthub.plist
agenthub service status        # systemctl --user status / launchctl print
agenthub service uninstall     # disable and remove it
```

See [`docs/OVERVIEW.md` → Run as a service](./docs/OVERVIEW.md#run-as-a-service-auto-start-on-boot)
and, for plugin installs, [`docs/PLUGINS.md` → Auto-start on boot](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)
- Codex project packs live under `.codex/`:
  - `AGENTS.md`
  - `.codex/rules/`
  - `.codex/agents/`
  - `.codex/skills/`

See [`.codex/README.md`](./.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](https://visualstudio.microsoft.com/visual-cpp-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:

```bash
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:

```bash
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:

```bash
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](./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` |