opencode-agenthub

Requires Node >= 18.0.0. Supports macOS and Linux directly. Windows users should use WSL 2 for the best experience; native Windows support remains best-effort alpha.

opencode-agenthub puts a ready AI coding team into each repo you work in — and when you want a better one, its HR Office helps you assemble custom teams from strong public agent repos, test them safely, and adopt only what you trust.

Use it in two ways:

• everyday coding — get a ready auto / plan / build team into each repo with setup auto and start
• HR Office — source, test, and promote stronger custom teams without touching your normal setup until you are ready

The npm package name is opencode-agenthub. The CLI command is agenthub. opencode-agenthub also works as a compatibility alias.

---

Install

npm install -g opencode-agenthub

Then verify:

agenthub --version
agenthub --help

Requirements

• Node >= 18.0.0 on PATH
• opencode on PATH
• Python 3 on PATH for HR inventory sync and staged-package helper scripts
• Bun (for tests/development only)

Platform support

Platform	Status
macOS	Supported
Linux	Supported
Windows via WSL 2	Supported and recommended
Native Windows	Best-effort alpha support

For Windows users, install and run Agent Hub inside WSL 2. This matches OpenCode's recommended Windows setup and preserves expected POSIX behavior for bash launchers, Python helpers, symlinked skills, and shell tooling.

Native Windows is still best-effort in alpha. Agent Hub now emits a startup notice on native Windows, generates run.cmd alongside run.sh, and avoids a few common platform pitfalls, but HR and shell-centric workflows are still most reliable under WSL 2.

---

Quick start

For most solo users, this is the whole flow:

1. Create your Agent Hub home

agenthub setup auto

This creates your personal Agent Hub home and installs the built-in auto / plan / build setup.

It also imports your existing opencode provider/model basics. If something looks wrong, agenthub doctor will tell you what to fix.

2. Start working in your repo

agenthub start

This activates your default coding team in the current repo.

After that, you can keep using plain opencode inside the folder for day-to-day work.

3. Inspect what is active

agenthub status

Use status any time you want to see which profile, agents, plugins, and runtime boundaries are active.

4. If something feels off, diagnose it

agenthub doctor

doctor checks your environment, home, workspace runtime, or plugin setup and points you to the right troubleshooting guide.

---

HR Office — recruit a better team without touching your normal setup

The default auto / plan / build team gets you moving fast. HR Office is where Agent Hub becomes a stronger product:

• discover strong public agent / skill repos
• stage a candidate team in isolation
• test it in a real repo with agenthub hr <profile>
• promote only what you want into your normal setup

Start here:

agenthub hr

HR Office running inside OpenCode to help source and stage a stronger team before promote.

After bootstrap, a runnable demo team is staged for you:

agenthub hr demo-coding-team

If you want to keep it after trying it in a real repo, promote the same demo into your Personal Home:

agenthub promote demo-coding-team

It preserves the real seven-role team shape and repo provenance of a strong HR-built coding team, including roles adapted from agency-agents and review workflow from obra/superpowers. The built-in copy vendors a lightweight vendored skill subset from obra/superpowers and anthropics/skills so it stays runnable without extra browser or Python-heavy dependencies.

Read the full HR guide at docs/hr-office.md.

Everyday commands

Command	Effect
agenthub setup auto	Create your personal home with the default coding team
agenthub start	Launch the default team in the current repo
agenthub start last	Reuse the last profile used in this workspace
agenthub start <profile>	Launch a specific profile in this workspace
agenthub status	Inspect the current workspace runtime and plugin boundary state
agenthub doctor	Diagnose setup/runtime issues and link to fixes
agenthub doctor --fix-all	Apply safe automatic fixes where possible
agenthub hr	Enter the isolated HR Office
agenthub hr <profile>	Test an HR-home or staged HR profile in this workspace
agenthub promote <package-id>	Import an approved staged HR package into your Personal Home

If you want a blank structure and no built-in coding team yet:

agenthub setup minimal

---

Runtime visibility and troubleshooting

When you want to inspect the active runtime, plugin boundary state, or why something feels off, start here:

agenthub status
agenthub status --short
agenthub status --json

agenthub doctor
agenthub doctor --category home
agenthub doctor --category environment
agenthub doctor --category workspace --config-root <path>
agenthub doctor --category plugin --config-root <path>

• agenthub status shows your active team, agents, plugins, and any health warnings.
• agenthub doctor checks your setup and tells you exactly what to fix.
• plugin doctor still works as a compatibility path, but it now routes through agenthub doctor --category=plugin.

For plugin bridge, OMO baseline, runtime boundary controls, and troubleshooting links, see docs/runtime-reference.md.

---

Build your own agents and teams

When you are ready to go beyond the default coding team:

Command	Effect
agenthub new soul reviewer	Create a new soul scaffold
agenthub new skill repo-audit	Create a new skill scaffold
agenthub new bundle reviewer	Create a new bundle scaffold
agenthub new profile my-team	Create a new profile scaffold
agenthub list	List installed assets
agenthub backup --output ./my-team-backup	Back up your Personal Home
agenthub restore --source ./my-team-backup	Restore your Personal Home from a backup

---

What Agent Hub creates

Part	What it does	Default location
Personal Home	Your reusable main library of teams, prompts, skills, and settings	~/.config/opencode-agenthub/
Workspace Runtime	The active composed runtime for one project	<workspace>/.opencode-agenthub/current/
HR Office	An isolated place to source, test, and stage stronger teams	~/.config/opencode-agenthub-hr/

If you used setup auto, you already have a ready-to-run default profile.

Terminology: A profile is a team. A bundle is one agent in that team. You only need these two terms until you start building custom teams.

---

Storage layout

Personal Home

Default location:

~/.config/opencode-agenthub/

Created up front:

souls/
skills/
bundles/
profiles/
settings.json

Example agenthub-home/ layout after agenthub setup auto, showing the core bundle / profile / skill / soul asset folders.

Created only when you actually use them:

instructions/
mcp/
mcp-servers/

Workspace Runtime

Default location:

<workspace>/.opencode-agenthub/current/

Workspace-specific memory lives in:

<workspace>/.opencode-agenthub.user.json

That file stores things like:

• last-used start profile in this workspace
• last-used hr test profile in this workspace
• .envrc preference state

Upgrade

Use this only when you install a newer package version and want to refresh built-in managed files in an existing home.

# preview Personal Home built-in file changes
agenthub upgrade

# overwrite Personal Home managed built-in files
agenthub upgrade --force

# preview HR Office built-ins + helper scripts
agenthub upgrade --target-root ~/.config/opencode-agenthub-hr

# overwrite HR Office built-ins + helper scripts
agenthub upgrade --target-root ~/.config/opencode-agenthub-hr --force

Notes:

• agenthub upgrade targets your Personal Home by default
• agenthub upgrade --target-root ~/.config/opencode-agenthub-hr targets HR Office
• HR upgrade refreshes built-in HR assets and helper scripts, but never modifies staged packages under ~/.config/opencode-agenthub-hr/staging/
• Continue to test staged teams with agenthub hr <profile> before using agenthub promote <package-id>

If a compose or runtime issue persists after upgrade, run agenthub doctor and follow the linked docs/troubleshooting/... guide for the reported category.

---

Development

bun run test:smoke
npm run build