perf: lighter, louder local install — vendored ReDoc, bootstrap failures shown in the session
- Plugin bootstrap: a failed npm install, a Node older than 22.5 or a failed UI build is recorded in runtime/last-failure.json; the next SessionStart prints it once as a systemMessage naming the log and /agenthub-doctor (a different failure is reported again; a successful bootstrap clears it). The foreground pass checks the Node version itself and spawns no worker on an old Node. - ReDoc: the standalone bundle (redoc 2.5.4, MIT, licence files kept) is vendored under server/vendor/redoc/ and the `redoc` dependency dropped — a runtime install (npm ci --omit=dev --ignore-scripts) goes 126 MB -> 45 MB. vendor/ is excluded from the header audit and prettier. - git missing from PATH: lane git actions answer 503 EGITMISSING with the install command instead of a bare ENOENT. - package.json engines: node >=22.5.0 (node:sqlite), matching MIN_NODE. - Docs: INSTALL.md is the one install/setup guide (SETUP.md merged in and now a pointer); no VS Code extension claim, one client-install hint, no windows-build-tools, better-sqlite3 notes scoped to checkouts, new "Plugin bootstrap never comes up" troubleshooting entry.
This commit is contained in:
+407
-82
@@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
The one install-and-setup guide for AgentHub — the local control surface for Claude Code agents: the plugin install, a checkout install, configuration, the database, importing history, and troubleshooting. (`SETUP.md` is only a pointer here now.)
|
||||
|
||||
## Fastest path — install it as a Claude Code plugin
|
||||
|
||||
@@ -17,17 +17,20 @@ on PATH — no clone, no `npm run setup`, no
|
||||
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 (`agenthub uninstall`), is in [`docs/PLUGINS.md`](docs/PLUGINS.md).
|
||||
the server stores data through `node:sqlite`), plus `git` and `tmux` from
|
||||
[Step 0](#step-0--system-packages). Full behavior, including the uninstall
|
||||
cleanup (`agenthub uninstall`), is in [`docs/PLUGINS.md`](docs/PLUGINS.md). If
|
||||
the dashboard never comes up, see
|
||||
[Plugin bootstrap never comes up](#plugin-bootstrap-never-comes-up).
|
||||
|
||||
Follow the steps below instead when you want a checkout — to develop the
|
||||
dashboard, run it from source, or stay on Node 20.
|
||||
dashboard or run it from source.
|
||||
|
||||
## Requirements
|
||||
|
||||
| Requirement | Version | Notes |
|
||||
|---|---|---|
|
||||
| Node.js | 20+ (22+ recommended) | Required for server and client |
|
||||
| Node.js | **22.5+** | Required for server and client (`node:sqlite`). Node 20 is end-of-life and unsupported |
|
||||
| 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) |
|
||||
@@ -76,7 +79,7 @@ Check it:
|
||||
```bash
|
||||
tmux -V # e.g. tmux 3.4
|
||||
git --version
|
||||
node -v # v20.x / v22.x / v24.x
|
||||
node -v # v22.5+ / v24.x
|
||||
```
|
||||
|
||||
Once the server is up you can ask it directly — this is the same probe the
|
||||
@@ -113,8 +116,8 @@ brew install node git tmux # Node >= 22.5 for the plugin install (nvm work
|
||||
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
|
||||
- **Node:** **>= 22.5** (the plugin stores data through `node:sqlite`; a
|
||||
checkout needs the same). 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
|
||||
@@ -172,24 +175,20 @@ cd AgentHub
|
||||
## Step 2 — Install dependencies
|
||||
|
||||
```bash
|
||||
npm run setup
|
||||
npm run setup # or: make setup
|
||||
```
|
||||
|
||||
This installs all server and client dependencies, plus the VS Code extension, and links the `agenthub` CLI.
|
||||
This runs `npm install` (whose `postinstall` hook installs the client's
|
||||
dependencies in `client/`), installs `client/` once more explicitly, and links
|
||||
the `agenthub` CLI (`npm link`; if that has no permission it prints how to link
|
||||
it by hand). A plain `npm install` is enough to build and run the dashboard —
|
||||
only the CLI link is missing.
|
||||
|
||||
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:
|
||||
With `--ignore-scripts` the `postinstall` hook is skipped; install the client
|
||||
yourself with `npm --prefix client install`.
|
||||
|
||||
```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
|
||||
```
|
||||
`better-sqlite3` gyp/compile warnings here are harmless — see
|
||||
[Troubleshooting](#better-sqlite3-errors-during-npm-install--npm-run-setup).
|
||||
|
||||
---
|
||||
|
||||
@@ -234,7 +233,7 @@ After starting a Claude Code session, you should see:
|
||||
- **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).
|
||||
If nothing appears after 30 seconds, see [Troubleshooting](#no-sessions-appearing-after-starting-claude-code).
|
||||
|
||||
### PWA install (optional)
|
||||
|
||||
@@ -246,57 +245,110 @@ The dashboard is a Progressive Web App. After opening it in a supported browser
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — (Optional) Import existing Claude Code history
|
||||
## Step 5 — (Optional) Importing 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.
|
||||
The dashboard automatically imports sessions from `~/.claude/projects/` on
|
||||
**every startup**, so if Claude Code has been used on this machine, you'll
|
||||
see history immediately after the first launch. If you need to bring in
|
||||
history from another machine, from a backup, or just force a rescan, use
|
||||
**Settings → Import History** in the UI — it's a guided, drag-and-drop
|
||||
experience with live progress.
|
||||
|
||||
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:
|
||||
### Pick the right mode
|
||||
|
||||
```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")]
|
||||
flowchart TD
|
||||
Q["Where is the history?"] --> Q1{Is it on this machine<br/>under ~/.claude/projects?}
|
||||
Q1 -->|yes, and I just want<br/>to re-scan| M1["Mode: Rescan default folder<br/>one click"]
|
||||
Q1 -->|yes, but in another folder<br/>on this machine| M2["Mode: Scan a folder<br/>paste the absolute path"]
|
||||
Q1 -->|no — it's on another machine<br/>or in an archive file| M3["Mode: Upload files<br/>drag-drop JSONL or archive"]
|
||||
|
||||
style UI fill:#a855f7,stroke:#c084fc,color:#fff
|
||||
style P fill:#f59e0b,stroke:#fbbf24,color:#000
|
||||
style DB fill:#10b981,stroke:#34d399,color:#fff
|
||||
M3 --> PREP["Archive source:<br/>tar -czf claude-history.tar.gz<br/>-C ~/.claude projects"]
|
||||
|
||||
style M1 fill:#10b981,stroke:#34d399,color:#fff
|
||||
style M2 fill:#f59e0b,stroke:#fbbf24,color:#000
|
||||
style M3 fill:#a855f7,stroke:#c084fc,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.
|
||||
### Step-by-step: moving history from one machine to another
|
||||
|
||||
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
|
||||
**On the source machine**, bundle the projects folder:
|
||||
|
||||
If you regularly import very large archives, these environment variables
|
||||
can be raised (the defaults are generous for typical use):
|
||||
```bash
|
||||
# macOS / Linux
|
||||
tar -czf claude-history.tar.gz -C ~/.claude projects
|
||||
|
||||
| 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) |
|
||||
# Windows (PowerShell, via built-in tar)
|
||||
tar -czf claude-history.tar.gz -C "$env:USERPROFILE\.claude" projects
|
||||
```
|
||||
|
||||
Set them before `npm run dev` or `npm start`:
|
||||
Transfer the resulting `claude-history.tar.gz` to the destination machine
|
||||
however you like — AirDrop, `scp`, USB, cloud storage.
|
||||
|
||||
**On the destination machine**, in the dashboard:
|
||||
|
||||
1. Open **Settings → Import History**.
|
||||
2. Pick **Upload files** (the third tab).
|
||||
3. Drag the archive onto the drop zone.
|
||||
4. Click **Upload & Import** and watch the progress.
|
||||
5. When the green result card appears, open **Analytics → Cost** to confirm
|
||||
per-model token totals and estimated cost.
|
||||
|
||||
### Supported inputs
|
||||
|
||||
Any of the following can be dropped onto the upload zone or found inside a
|
||||
folder given to **Scan a folder**:
|
||||
|
||||
- `.jsonl` — session transcripts
|
||||
- `.meta.json` — subagent metadata sidecars
|
||||
- `.zip` — extracted with path-traversal protection
|
||||
- `.tar`, `.tar.gz`, `.tgz` — extracted via the `tar` package
|
||||
- `.gz` — single gzipped JSONL (streaming-decompressed)
|
||||
|
||||
### Accuracy guarantees
|
||||
|
||||
- **Idempotent** — re-importing never double-counts. Sessions are
|
||||
deduplicated by UUID.
|
||||
- **Cost-preserving** — the `token_usage` table uses `baseline_*` columns
|
||||
to preserve pre-compaction token totals, so re-ingesting a compacted
|
||||
transcript never erases historical cost.
|
||||
- **Same parser as live** — `parseSessionFile` + `importSession` is the
|
||||
single source of truth for both hook-driven ingestion and manual
|
||||
import, so imported numbers match captured numbers exactly.
|
||||
|
||||
### Safety
|
||||
|
||||
Archive extraction is hardened against path traversal and archive bombs.
|
||||
The defaults are generous for real-world transcripts but tight enough to
|
||||
stop obvious attacks. If you regularly import very large archives, raise them
|
||||
before `npm run dev` or `npm start` (also listed under
|
||||
[Environment variables](#environment-variables)):
|
||||
|
||||
| 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) |
|
||||
|
||||
```bash
|
||||
AGENTHUB_IMPORT_MAX_EXTRACT_BYTES=17179869184 npm start # allow 16 GB extraction
|
||||
```
|
||||
|
||||
### CLI alternative
|
||||
|
||||
For scripts and automation, the same logic runs from the terminal:
|
||||
|
||||
```bash
|
||||
# Import (or re-import) everything under ~/.claude/projects
|
||||
npm run import-history
|
||||
|
||||
# Dry run — show what would be imported without writing
|
||||
node scripts/import-history.js --dry-run
|
||||
|
||||
# Scope to a single project dir
|
||||
node scripts/import-history.js --project my-project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Production mode
|
||||
@@ -328,44 +380,260 @@ and, for plugin installs, [`docs/PLUGINS.md` → Auto-start on boot](docs/PLUGIN
|
||||
|
||||
---
|
||||
|
||||
## Optional: Agent extension packs
|
||||
## How it works
|
||||
|
||||
This repository includes extension packs for both Claude Code and Codex.
|
||||
AgentHub integrates with Claude Code through its native hook system. When Claude Code performs any action (session start, tool use, turn completion, subagent finish, session exit), it fires a hook that calls a small Node.js script bundled with this project. That script forwards the event over HTTP to the dashboard server, which stores it in SQLite and broadcasts it to the browser over WebSocket.
|
||||
|
||||
- Claude Code loads project extensions from:
|
||||
```
|
||||
Claude Code → hook fires → hook-handler.js → POST /api/hooks/event
|
||||
↓
|
||||
Browser ← WebSocket broadcast ← Express server ← SQLite
|
||||
```
|
||||
|
||||
No extra Claude Code configuration is required in the normal host-run path — when you start the dashboard with `npm run dev` or `npm start`, the server configures the hooks automatically on startup (or, with the `agenthub` plugin enabled in `~/.claude/settings.json`, removes the checkout's copies — the plugin's own hooks already run, and both would post every event twice). Container deployments are the exception: after the container is up, run `npm run install-hooks` on the host so Claude Code points at `http://localhost:4820`.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Hook auto-installation
|
||||
|
||||
When the dashboard is running directly on the host, the server writes the following to `~/.claude/settings.json` every time it starts:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionStart" }] }],
|
||||
"PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PreToolUse" }] }],
|
||||
"PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PostToolUse" }] }],
|
||||
"Stop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Stop" }] }],
|
||||
"SubagentStop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SubagentStop" }] }],
|
||||
"Notification": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Notification" }] }],
|
||||
"SessionEnd": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionEnd" }] }]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Note: `SessionStart` and `SessionEnd` hooks do not support the `matcher` field — they fire unconditionally on every session start and exit.
|
||||
|
||||
Existing hooks in that file are preserved. The dashboard only adds or updates entries that contain `hook-handler.js`.
|
||||
|
||||
To re-run hook installation manually:
|
||||
|
||||
```bash
|
||||
npm run install-hooks
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> Container note: if you run the dashboard inside a container (a Dev Container, Codespaces, or your own image), do not install hooks from in there — the hook path a container writes points at the container filesystem, not the host. Run `npm run install-hooks` on the host instead. As a safeguard (issue #193) the installer **detects container execution and refuses to run** (exiting non-zero) so it can never poison a bind-mounted host `~/.claude`. If Claude Code itself genuinely runs inside that container, override with `AGENTHUB_ALLOW_CONTAINER_HOOKS=1 npm run install-hooks`.
|
||||
|
||||
> [!NOTE]
|
||||
> Prefer a ready-made dev environment? This repo ships an **optional** Dev Container (`.devcontainer/`) for VS Code / GitHub Codespaces — Node 22, native build tools for `better-sqlite3`, Python, and ports `4820`/`5173` preconfigured. It's purely opt-in and changes nothing for host-based development. See [`.devcontainer/README.md`](.devcontainer/README.md). (Hooks remain host-side there too.)
|
||||
|
||||
### Environment variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `DASHBOARD_PORT` | `4820` | Port the Express server listens on |
|
||||
| `CLAUDE_DASHBOARD_PORT` | `4820` | Port the hook handler uses when posting events to the dashboard |
|
||||
| `DASHBOARD_DB_PATH` | `data/dashboard.db` | Path to the SQLite database file |
|
||||
| `NODE_ENV` | `development` | Set to `production` to serve built client |
|
||||
| `DASHBOARD_CLIENT_DIST` | `client/dist` | Directory the built UI is served from in production. Set by the `agenthub` plugin bootstrap to its own runtime dir, because the plugin cache is replaced on every update |
|
||||
| `AGENTHUB_IMPORT_MAX_BYTES` | `1073741824` (1 GB) | Maximum size per uploaded file on `/api/import/upload` |
|
||||
| `AGENTHUB_IMPORT_MAX_FILES` | `2000` | Maximum number of files per upload request |
|
||||
| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES` | `4294967296` (4 GB) | Maximum uncompressed bytes any single archive is allowed to expand to (zip-bomb defense) |
|
||||
| `DASHBOARD_DATA_DIR` | `~/.claude/agenthub` | AgentHub's data dir; a plugin install keeps its runtime (deps, UI build, logs) in `runtime/` under it |
|
||||
|
||||
Example with a custom port:
|
||||
|
||||
```bash
|
||||
DASHBOARD_PORT=9000 npm run dev
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> You usually do **not** need to set `DASHBOARD_PORT` manually. `npm run dev` is wrapped by `scripts/dev.js`, which probes both `127.0.0.1` and `::1` (so an SSH `LocalForward` bound to one loopback can't slip past) and picks the first free port in `4820–4859` automatically. The chosen port is propagated to the Vite dev proxy via `DASHBOARD_PORT`, and the Express server writes it to `~/.claude/.agenthub.json` so the Claude Code hook handler discovers it without any env var.
|
||||
>
|
||||
> Multiple dashboards can run side by side — for example two `npm run dev` checkouts, or `npm run dev` alongside `npm start`. Each one appends its `{port, pid, startedAt}` entry to the discovery file, and `scripts/hook-handler.js` fan-outs every hook event to every live entry, so both UIs keep their real-time stream.
|
||||
>
|
||||
> Setting `CLAUDE_DASHBOARD_PORT=N` overrides discovery entirely and forces the hook handler to a single port — useful for tests and container setups where the in-process discovery file isn't reachable from the host.
|
||||
>
|
||||
> If you bypass the picker (e.g. `npm run dev:raw`, container builds, or anything else that calls `node server/index.js` directly), make sure your client is built / proxied against the port the server actually bound.
|
||||
|
||||
### Agent extension setup (Claude Code + Codex)
|
||||
|
||||
This repository ships extension files for both agent ecosystems:
|
||||
|
||||
- Claude Code:
|
||||
- `CLAUDE.md`
|
||||
- `.claude/rules/`
|
||||
- `skills/` (shipped as the `agenthub` plugin's skills)
|
||||
- Codex project packs live under `.codex/`:
|
||||
- `.claude/rules/*`
|
||||
- `skills/*` (the `agenthub` plugin's own skills)
|
||||
- Codex:
|
||||
- `AGENTS.md`
|
||||
- `.codex/rules/`
|
||||
- `.codex/agents/`
|
||||
- `.codex/skills/`
|
||||
- `.codex/config.toml`
|
||||
- `.codex/rules/default.rules`
|
||||
- `.codex/agents/*`
|
||||
- `.codex/skills/*`
|
||||
|
||||
See [`.codex/README.md`](./.codex/README.md) for Codex extension details.
|
||||
|
||||
### PWA configuration (optional)
|
||||
|
||||
The dashboard ships as a Progressive Web App. No configuration is required — its manifest and service worker are included out of the box.
|
||||
|
||||
**Customising the manifest:** Edit `client/public/manifest.json`. Common fields to change:
|
||||
|
||||
- `name` / `short_name` — displayed on the home screen / dock
|
||||
- `theme_color` — address bar / title bar tint (default: `#6366f1`)
|
||||
- `background_color` — splash screen background
|
||||
- `start_url` — entry point when launched from home screen
|
||||
|
||||
**Updating the service worker cache:** The SW has a `CACHE_NAME` constant (e.g. `dashboard-v2`). After deploying new assets, bump the version string to force browsers to re-fetch — though for the dashboard this is rarely needed: hashed `/assets/*` URLs are immutable per build, everything else is fetched network-first with cache fallback, and a `controllerchange` listener in the client reloads the page exactly once when a new SW takes over, so a rebuild propagates without a hard refresh.
|
||||
|
||||
**Browser support:** PWA install prompts appear in Chrome 107+, Edge 107+, and Firefox 110+ (desktop and Android). Safari supports `apple-mobile-web-app-capable` for iOS home-screen mode but does not show an install banner.
|
||||
|
||||
**Verifying PWA status:** Open DevTools → Application → Manifest to confirm the manifest loads. Check the Service Workers section to verify the SW is registered and active. The Lighthouse PWA audit should pass all core checks.
|
||||
|
||||
---
|
||||
|
||||
## Database
|
||||
|
||||
The SQLite database is created automatically on first run (`data/dashboard.db` in a checkout, unless `DASHBOARD_DB_PATH` says otherwise). The directory is created if it does not exist. The database uses WAL mode for concurrent reads and foreign keys for referential integrity.
|
||||
|
||||
### Clear all data
|
||||
|
||||
To remove all sessions, agents, events, and token usage (useful after running seed data or for a clean start):
|
||||
|
||||
```bash
|
||||
npm run clear-data
|
||||
```
|
||||
|
||||
### Data management via Settings page
|
||||
|
||||
The Settings page (`/settings`) provides a UI for the following. **Model Pricing**
|
||||
and **Hook Configuration** are not on its Dashboard tab: they sit under the
|
||||
Claude Code tab's **Overview** (Settings → Claude Code → Overview), beside
|
||||
CLAUDE_HOME; Codex (its Overview) and Antigravity have their own pricing and
|
||||
hooks in their own tabs.
|
||||
|
||||
- **Model Pricing** — view and edit per-model cost rates, reset to defaults, add custom models
|
||||
- **Hook Configuration** — check which hooks are installed and reinstall them
|
||||
- **Data Export** — download all sessions, agents, events, and pricing as a JSON file
|
||||
- **Session Cleanup** — abandon stale active sessions after N hours, purge old completed sessions after N days
|
||||
- **Clear All Data** — remove all sessions, agents, events, and token usage
|
||||
- **Data Management** and **About** sections render with loading placeholders while server info is being fetched, so the page is always fully navigable
|
||||
|
||||
### Seed demo data
|
||||
|
||||
To populate the dashboard with sample sessions, agents, and events for UI exploration:
|
||||
|
||||
```bash
|
||||
npm run seed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scripts reference
|
||||
|
||||
| Script | Command | Description |
|
||||
|---|---|---|
|
||||
| `setup` | `npm run setup` | Install all dependencies (server + client) |
|
||||
| `dev` | `npm run dev` | Start server + client in development mode |
|
||||
| `start` | `npm start` | Start server in production mode |
|
||||
| `build` | `npm run build` | Build the React client to `client/dist/` |
|
||||
| `install-hooks` | `npm run install-hooks` | Write Claude Code hooks to `~/.claude/settings.json` |
|
||||
| `clear-data` | `npm run clear-data` | Delete all data from the database |
|
||||
| `seed` | `npm run seed` | Insert demo sessions/agents/events |
|
||||
| `import-history` | `npm run import-history` | Import legacy sessions from `~/.claude/` (also runs on startup) |
|
||||
| `claude` | Claude CLI | Uses `CLAUDE.md`, `.claude/rules`, and `.claude/skills` automatically |
|
||||
| `test` | `npm test` | Run all server and client tests |
|
||||
| `test:server` | `npm run test:server` | Run server integration tests only |
|
||||
| `test:client` | `npm run test:client` | Run client unit tests only |
|
||||
| `format` | `npm run format` | Format all files with Prettier |
|
||||
| `format:check` | `npm run format:check` | Check formatting without writing |
|
||||
|
||||
---
|
||||
|
||||
## Makefile targets
|
||||
|
||||
All npm scripts are mirrored as `make` targets for convenience. Run `make help` to list them:
|
||||
|
||||
```bash
|
||||
make help
|
||||
```
|
||||
|
||||
Commonly used targets:
|
||||
|
||||
| Make target | Equivalent npm command | Description |
|
||||
|---|---|---|
|
||||
| `make setup` | `npm run setup` | Install all dependencies (root + client) |
|
||||
| `make dev` | `npm run dev` | Start server + client in watch mode |
|
||||
| `make build` | `npm run build` | Build the React client for production |
|
||||
| `make start` | `npm start` | Start the production server |
|
||||
| `make prod` | `npm run build && npm start` | Build then start in one step |
|
||||
| `make test` | `npm test` | Run all tests (server + client) |
|
||||
| `make test-server` | `npm run test:server` | Run server tests only |
|
||||
| `make test-client` | `npm run test:client` | Run client tests only |
|
||||
| `make format` | `npm run format` | Format all files with Prettier |
|
||||
| `make format-check` | `npm run format:check` | Check formatting without writing |
|
||||
| `make seed` | `npm run seed` | Load demo data |
|
||||
| `make clear-data` | `npm run clear-data` | Delete all data rows |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `npm run setup` shows `better-sqlite3` errors
|
||||
### Plugin bootstrap never comes up
|
||||
|
||||
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.
|
||||
The plugin's `SessionStart` hook only checks a fast path and hands the real
|
||||
work (npm install, UI build, server start) to a detached background worker, so
|
||||
a failure there does not show in the session. When the worker's last run
|
||||
failed, the next session start prints a one-time **AgentHub:** message naming
|
||||
the log to read. Everything is logged under `~/.claude/agenthub/runtime/`:
|
||||
|
||||
At runtime the server uses this fallback chain:
|
||||
| File | What it holds |
|
||||
|---|---|
|
||||
| `bootstrap.log` | Each bootstrap step and why it stopped (Node too old, install failed, superseded build, …) |
|
||||
| `npm-install.log` | npm's output for the runtime dependency install |
|
||||
| `client-build.log` | The dashboard UI build (the API still works when only this fails) |
|
||||
| `server.log` | The server's own output, when it was started detached |
|
||||
| `last-failure.json` | The last failure the session-start message reports (removed once a bootstrap succeeds) |
|
||||
|
||||
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
|
||||
Then run `/agenthub-doctor` from Claude Code — it checks Node, the runtime
|
||||
dependencies, the server and the service unit, and names the fix for each
|
||||
failing row. `/agenthub-update` re-runs the bootstrap in the foreground with its
|
||||
output visible. The most common causes: Node older than 22.5 (`node -v` in the
|
||||
shell Claude Code was started from), no network or a proxy blocking the npm
|
||||
registry (`npm-install.log`), and a port held by another program (`server.log`,
|
||||
see [Port 4820 already in use](#port-4820-already-in-use)).
|
||||
|
||||
If you see an error box at startup saying *"SQLite backend not available"*, either:
|
||||
### `better-sqlite3` errors during `npm install` / `npm run setup`
|
||||
|
||||
- **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
|
||||
Only a **checkout** install sees these — the plugin installs with
|
||||
`--ignore-scripts` and never builds `better-sqlite3`. They are **harmless**:
|
||||
`better-sqlite3` is an optional dependency, and when it cannot be built npm
|
||||
skips it and the server uses Node's built-in `node:sqlite` (Node 22.5+). You do
|
||||
**not** need Python, Visual Studio Build Tools or a C++ compiler.
|
||||
|
||||
Then run: `npm rebuild better-sqlite3`
|
||||
To build it anyway (it is used when present), install a toolchain and run
|
||||
`npm rebuild better-sqlite3`:
|
||||
|
||||
- **Windows:** [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
|
||||
|
||||
### "SQLite backend not available" error on startup
|
||||
|
||||
Neither `better-sqlite3` nor `node:sqlite` could be loaded — almost always a
|
||||
Node older than 22.5. Upgrade Node.
|
||||
|
||||
### Database is locked / busy errors
|
||||
|
||||
The SQLite database uses WAL mode with a 5-second busy timeout. If you see lock errors:
|
||||
|
||||
- Ensure only one dashboard server instance is running
|
||||
- Check for zombie `node server/index.js` processes: `ps aux | grep server/index`
|
||||
- Delete `data/dashboard.db-wal` and `data/dashboard.db-shm` if the server was killed uncleanly, then restart
|
||||
|
||||
### `npm run dev` fails immediately
|
||||
|
||||
@@ -375,7 +643,7 @@ 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:
|
||||
If the error mentions a missing module like `express` or `react`, dependencies may be incomplete. Delete `node_modules` in both the root and `client/`, then re-run setup:
|
||||
|
||||
```bash
|
||||
rm -rf node_modules client/node_modules
|
||||
@@ -409,9 +677,66 @@ that case.
|
||||
|
||||
### No sessions appearing after starting Claude Code
|
||||
|
||||
See [SETUP.md — Troubleshooting](./SETUP.md#troubleshooting) for detailed hook debugging steps.
|
||||
**Check 1 — Is the server running?**
|
||||
|
||||
---
|
||||
```bash
|
||||
curl http://localhost:4820/api/health
|
||||
# Expected: {"status":"ok","timestamp":"..."}
|
||||
```
|
||||
|
||||
**Check 2 — Are hooks installed?**
|
||||
|
||||
With the plugin, its hooks come with it — run `/agenthub-doctor` instead. For a
|
||||
checkout, open `~/.claude/settings.json` and confirm it contains a `hooks`
|
||||
section with entries referencing `hook-handler.js`. If not, run:
|
||||
|
||||
```bash
|
||||
npm run install-hooks
|
||||
```
|
||||
|
||||
**Check 3 — Did you start a new Claude Code session after the server started?**
|
||||
|
||||
Hooks only apply to sessions started after installation. Restart Claude Code.
|
||||
|
||||
**Check 4 — Is Node.js in PATH when Claude Code runs hooks?**
|
||||
|
||||
On some systems, the shell environment when Claude Code fires hooks may not include the full PATH. Test with:
|
||||
|
||||
```bash
|
||||
node --version
|
||||
```
|
||||
|
||||
If Node.js is not found, use the full path to `node` in the hook command. Edit `scripts/install-hooks.js`, replace `node` with the absolute path (e.g. `/usr/local/bin/node`), and re-run `npm run install-hooks`.
|
||||
|
||||
### Dashboard shows "Disconnected" in the sidebar
|
||||
|
||||
The WebSocket connection to the server failed. Ensure the server is running:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The client will automatically reconnect every 2 seconds once the server is available.
|
||||
|
||||
### Port 4820 already in use
|
||||
|
||||
When another program holds the port, the server stops with
|
||||
`Port 4820 is already in use by another program…` (a running AgentHub there is
|
||||
detected and simply reused). Pick another port:
|
||||
|
||||
```bash
|
||||
DASHBOARD_PORT=4821 npm start # or: DASHBOARD_PORT=4821 npm run dev
|
||||
```
|
||||
|
||||
The Vite dev proxy and the Claude Code hooks follow the port on their own
|
||||
(`client/vite.config.ts` reads `DASHBOARD_PORT`; the server publishes the port it bound).
|
||||
|
||||
And make sure Claude Code posts hooks to the new port:
|
||||
|
||||
```bash
|
||||
CLAUDE_DASHBOARD_PORT=4821 claude
|
||||
# or edit scripts/hook-handler.js and change the default port
|
||||
```
|
||||
|
||||
## Ports
|
||||
|
||||
|
||||
Reference in New Issue
Block a user