nntrivi2001
cc85e35439
Update detection was a commit count against the default branch, which says nothing about whether a *version* shipped and is pure noise on the plugin cache (a depth-1 clone, where every distance is a graft artefact). It now reads the forge's own releases API and compares the published tag to this install's package.json version, falling back to the commit count only when no release can be read — with the reason in release_check, so "up to date" never silently means "we could not look". Two states a commit count cannot express: dev_build (ahead of the newest release, missing nothing from it) now reads "Dev build - N ahead" instead of a false "Up to date"; and on a shallow clone every commits_*_release field is null and dev_build is never asserted, because the numbers would be meaningless. POST /api/updates/apply gains a second mode, chosen by install kind and never by the request body. A checkout still fast-forwards onto the release tag, rebuilds and self-restarts. A ~/.claude/plugins/cache/ install is refused by applyUpdate (that directory is Claude Code's to replace) and handed instead to a detached chain: claude plugin marketplace update -> claude plugin update -y -> plugin-bootstrap.js --force from the NEW cache dir, which retires this server and starts its replacement. Both write the HTTP response before anything stops the process. The chain records every outcome to plugin-update.json in the runtime dir, outside the cache the update replaces, so the next server reports it as last_plugin_update: a failed chain is otherwise indistinguishable from a slow one, and the tab would poll a server that never returns. /reload-plugins is deliberately not in the chain - it is REPL-scoped to the session that runs it, so no background process can perform it, and plugin-bootstrap derives PLUGIN_ROOT from its own __dirname, which is what makes it unnecessary for the dashboard. Also rebrands the sidebar subtitle, splash and page title to SmartGift Solution, and corrects three ARCHITECTURE.md statements that claimed /apply did not exist. Verified: server 1683/1683, client 486/486, build, prettier, file-header audit, openapi.yaml regenerated.
AgentHub
Internal SmartGift build. Local-first control surface for Claude Code agents —
monitoring is one part of it, not the whole. Hooks POST every tool call to an
Express + SQLite server and a React UI updates over WebSocket; lanes track
parallel agent work through a pipeline; and the agenthub CLI drives real terminal
sessions, lane runtimes, and Claude Code's own configuration.
AgentHub records and shows — it does not orchestrate. The session in control makes every decision.
Internal build — all rights reserved.
(Tiếng Việt: README.vi.md)
What it does
- Sessions, agents, events. Everything Claude Code emits, recorded and searchable: tool calls, token usage, cost, subagent trees, transcripts.
- Lanes. One lane per working directory, surviving session restarts. A lane moves through pipeline stages and the dashboard shows where it is.
- Stage detection. The stage is inferred from the tool stream, so a session
that never calls
agenthub stagestill shows progress — rendered dashed amber and never as done, because an inference is not evidence. - Run Claude Code or Codex from the browser. A real terminal (tmux + a real
PTY, rendered with xterm.js) attached to a lane's directory — the exact TUI
you'd see locally, fully interactive, resumable, and attachable from a real
terminal too via
agenthub lanes shell. Which CLI it starts is the lane's own setting. - Analytics (in-dashboard tab), alerts, and a workflow view, plus a CLI.
Requirements
Node >= 20 (engines in package.json). Node 24 is what the test suites
are verified on — node 25 currently breaks 6 server tests through a
better-sqlite3 ABI mismatch and 20 client tests through a global localStorage
change.
The superpowers plugin is required by the ship-feature pipelines only, not
by the dashboard. /agenthub:ship-feature and /agenthub:ship-feature-lane drive
superpowers:brainstorming, writing-plans, test-driven-development,
requesting-code-review and verification-before-completion phase by phase,
and both built-in pipeline templates name those same slash commands as their
per-node drivers. Without it the dashboard, hooks and CLI all work
normally — the two pipeline skills are what stop partway. /agenthub-doctor reports
it as a WARN row.
You do not normally have to install it. The plugin's SessionStart
bootstrap installs it for you, once, in its detached worker — so a session never
waits on the clone, and the current session needs /reload-plugins before the
skills resolve (any later session picks them up on its own). The outcome is
logged to ~/.claude/agenthub/runtime/bootstrap.log, and /agenthub-update
retries a failed one. To install it by hand instead, or after opting out:
claude plugin install superpowers@claude-plugins-official
Set AGENTHUB_AUTO_INSTALL_PLUGINS=0 to opt out of the automatic install. Only the
plugins on a fixed allowlist in server/lib/skill-plugins.js are ever installed
this way — superpowers today. A custom pipeline template naming some other
plugin's command is reported by /agenthub-doctor and never installed, because a
template is a file anyone can drop into DASHBOARD_PIPELINES_DIR.
Install as a Claude Code plugin
Two commands on a machine that has nothing but Claude Code, no clone and no
npm run setup:
/plugin marketplace add https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
/plugin install agenthub@agenthub
The first session start installs the hooks, boots the server, puts agenthub on
PATH; it runs detached, so the session never waits on
it. /agenthub-doctor reports the state, /agenthub-open builds the UI and prints the
URL, /agenthub-update refreshes after a plugin update. This path needs Node
>= 22.5 (no native better-sqlite3, so the server uses node:sqlite).
Details, including what to delete on uninstall:
docs/PLUGINS.md.
Install from a checkout
npm run setup # root and client dependencies
npm run build # builds the client into client/dist
npm start # serves the built client and the API on :4820
Open http://localhost:4820.
Development, with hot reload:
npm run dev # server on :4820, Vite client on :5173
DASHBOARD_PORT overrides the port, DASHBOARD_CLIENT_DIST overrides where the
built UI is served from (defaults to client/dist; the plugin install points it
at its own runtime directory). postinstall writes the Claude Code hook entries
that feed the dashboard — do not run it when the agenthub plugin is installed, or
every event is counted twice.
Run as a service (auto-start on boot)
npm start only runs while that terminal (or agenthub start's background
process) is alive — a reboot loses it. On Linux, agenthub service install sets
up a systemd --user service instead, so :4820 is up again on its own after
every reboot, with no manual step and no Claude Code (or any AI tool) needed
to trigger it:
npm run build # the service serves the built client, same as npm start
agenthub service install # writes + enables ~/.config/systemd/user/agenthub.service
agenthub service status # systemctl --user status agenthub
agenthub service uninstall # disable and remove it
agenthub service install also tries loginctl enable-linger so the service
starts on a cold boot, before anyone logs in; if that needs elevated rights on
your machine it prints the sudo loginctl enable-linger <user> command to run
once yourself. Plugin installs get the same persistence automatically — see
Auto-start on boot in docs/PLUGINS.md.
The CLI
agenthub is linked by npm run setup; otherwise call node bin/agenthub.js.
agenthub status # is the dashboard up
agenthub start # start it in the background and wait for healthy
agenthub service install # auto-start on boot via systemd --user (Linux)
agenthub sessions # recent sessions
agenthub lanes # lanes with stage and progress
agenthub lanes pipeline # this lane's pipeline template, or switch it
agenthub lanes node <id> # run ONE pipeline node's own command (no id: list them)
# (in a session: /intake, /qc, /ship-full, /ship-quick …)
agenthub stage <name> # declare the current lane's stage
agenthub tail # live event feed
agenthub --help lists the rest.
Lanes
A lane is a working directory the dashboard watches. Two kinds:
- adopted — a directory you already had. The dashboard only reads it; it is never reset or deleted.
- managed — a git worktree the dashboard created under
LANES_ROOT. It owns the full lifecycle and may reset or remove it, behind a three-check destroy guard and a counted preflight the caller has to echo back.
agenthub lanes add --cwd /path/to/repo --title "My feature" # adopt
agenthub lanes add --repo /path/to/repo --slug my-feature # managed worktree
Every lane also carries the CLI that drives it — claude (the default) or
codex — picked in the Add-lane modal and fixed for the life of the lane. A
Codex lane's run panel offers Codex's own sandbox, approval and reasoning-effort
choices, and resumes with codex resume --last. Codex emits none of this
dashboard's hooks, so a Codex lane records its runs but stays absent from
Sessions and Analytics. Its stage detection works anyway, from Codex's own
rollout journals on disk ($CODEX_HOME/sessions/**/rollout-*.jsonl, polled every
DASHBOARD_CODEX_POLL_MS ms, default 15000), and on a Codex lane a detection
also advances the declared stage — the one place an inference moves the blue
current ring, because a Codex session has no hook and nothing else would ever
move it. What a Codex lane cannot get for free is evidence: an auto-advanced
node stays amber (passed-no-evidence), never green, since only the session
itself can say what it finished. Three things help it get there: the run console
pre-fills a codex pane's opening prompt with a stage-declaration checklist built
from its own pipeline nodes, agenthub lanes agents install writes the same
instructions as a marker-delimited block in the lane's AGENTS.md, and a 60s
sweep (DASHBOARD_CODEX_NUDGE_MS, 0 disables) types a one-line reminder into
a lane's pane if its current stage sits without evidence for more than two
minutes.
The declared stage comes from agenthub stage. The inferred stage comes from tool
events and expires after DETECTION_TTL_MS (default 5 minutes), so a lane can
move backwards between work sessions. Detection never writes the declared stage,
and an inferred node never renders as done.
A lane's pipeline template can be switched after creation — agenthub lanes pipeline <template> from the terminal, or the pipeline-template picker next to
the lane's title in the Workspace detail panel. Both re-resolve the lane's
current declared stage against the new template's nodes and warn if it no
longer matches one.
A lane can also run its own application stack, isolated per lane, when its
repository declares a profile at <repo>/.agenthub/profile/ — a profile.env of
declarations plus shell hooks the dashboard calls. Each lane gets a slot, and its
ports and per-lane directories derive from it:
agenthub lanes up # boot the stack of the lane owning this directory
agenthub lanes runtime # slot, ports, service health
agenthub lanes logs api # tail a service log
agenthub lanes down
Services are fully detached, so restarting the dashboard never stops a running lane. This is resource namespacing on the host, not a container: lanes run as the same user and share the network.
docs/LANES.md has the pipeline model, the destroy guard, the
preflight contract, the Workspace page, GET /api/lanes/:id/git, and the full
runtime/profile contract.
Tests
npm run test:server # node:test
npm run test:client # Vitest
Both must be green before a commit; the pre-commit hook runs them plus Prettier.
Layout
| Path | What |
|---|---|
server/ |
Express API, SQLite schema, hook ingest, lane and worktree libraries |
client/ |
React 18 + Vite + Tailwind dashboard |
bin/agenthub.js |
CLI |
docs/ |
Architecture, API, lanes, database |
plugins/ |
Claude Code plugins shipped with the dashboard |
Docs
ARCHITECTURE.md— request flow, schema, WebSocket surfacedocs/LANES.md— lanes, pipelines, stage detectiondocs/API.md— REST endpoints (openapi.yamlis generated)docs/DATABASE.md— tables and migrationsINSTALL.mdCLAUDE.md— the rules an agent working in this repo must follow