Installation

Installation

BizarHarness can be installed three ways: from npm, from source, or per-project. The npm install is right for almost everyone; the source install is for contributors; the per-project install is for CI or sandboxed environments.

npm (recommended)

The package is published to npm at bizarharness.

Run without installing

The fastest way to try BizarHarness without leaving anything on your machine:

npx bizarharness

npx downloads the package to a temp directory, runs the interactive installer, and cleans up. Use this to evaluate BizarHarness before committing to a global install.

Install globally

For an install that sticks:

npm install -g bizarharness
bizarharness

This puts the bizarharness binary on your $PATH. Verify with:

bizarharness --help

You should see the help text with usage, subcommands (audit, init, export, plan, test-gate), and the install hint.

Add to a project as a dev dependency

If you want bizarharness to be available only inside a specific project (and tracked in package.json):

npm install --save-dev bizarharness
npx bizarharness

The --save-dev flag keeps the install out of production dependencies. The npx invocation is needed because the binary isn't on the global $PATH from a local install.

Verify the install

bizarharness --version

The current version is 1.2.1. If the command is not found, your $PATH does not include the npm global bin directory. On most systems this is ~/.npm-global/bin (custom) or $(npm config get prefix)/bin (default). Add it to your shell rc.

Manual install from source

Use this if you want to hack on BizarHarness itself — change an agent's prompt, add a new agent, or test a plugin patch.

git clone git@github.com:DrB0rk/BizarHarness.git
cd BizarHarness
chmod +x install.sh
./install.sh

The script:

1. Creates ~/.config/opencode/agents/ if it doesn't exist.
2. Copies every file from config/agents/*.md into that directory.
3. Copies the master config/AGENTS.md to ~/.config/opencode/AGENTS.md.
4. Copies the bundled plugin from plugins/bizar/ to ~/.config/opencode/plugins/bizar/, excluding node_modules, dist, and *.log.
5. Merges the template config/opencode.json into your existing ~/.config/opencode/opencode.json using jq. If jq is missing, it falls back to a copy. If a config already exists, it's backed up to opencode.json.bak first.
6. Idempotently ensures the Bizar plugin entry is in the plugin array, even if the merge step replaced the array.
7. Prints next steps (edit opencode.json, restart opencode, /connect).

After the script runs, restart opencode and run /connect.

Per-project install (bizarharness init)

If you want BizarHarness to live inside a single project — useful for monorepos, multi-tenant setups, or contributors who don't want a global install — use init:

cd ~/my-project
bizarharness init

init is a lighter-weight version of the full installer. It:

• Detects the project stack (Next.js, Django, Rust, etc.) from package.json / pyproject.toml / Cargo.toml / go.mod.
• Installs relevant skill packs based on the detected stack.
• Creates .bizar/PROJECT.md with stack, conventions, and entry points.
• Creates .bizar/AGENTS_SELF_IMPROVEMENT.md with starter active rules.

init does not copy agent files into ~/.config/opencode/. It assumes the global install already happened (so all the agents are available), and just configures the project for use with BizarHarness.

Uninstall

To remove BizarHarness globally:

npm uninstall -g bizarharness

Then clean up the artifacts it left behind:

# Agent definitions
rm -rf ~/.config/opencode/agents/

# Master AGENTS.md (verify no other harness needs it first)
rm -f ~/.config/opencode/AGENTS.md

# Bizar plugin
rm -rf ~/.config/opencode/plugins/bizar/

# Plugin entry from opencode.json (manual edit; or restore from backup)
cp ~/.config/opencode/opencode.json.bak ~/.config/opencode/opencode.json

If you used a per-project install, delete the .bizar/ folder from the project root:

rm -rf .bizar/

Note: RTK, Semble, and the Skills CLI are installed as side-effects of the BizarHarness installer. Remove them only if you're sure no other project depends on them.

# RTK
rm -f ~/.local/bin/rtk
# Semble
uv tool uninstall semble
# Skills CLI
npm uninstall -g skills

Troubleshooting install issues

bizarharness: command not found after npm install -g.

Your npm global bin directory is not on $PATH. Find it with npm config get prefix, then add <prefix>/bin to your shell rc. Restart the shell.

EACCES: permission denied during install.

You installed Node with sudo and npm can't write to the global directory. Fix the permissions on the npm prefix, or use a version manager (nvm, fnm) to install Node in your home directory.

Installer hangs on "Detecting opencode".

The pre-flight check runs opencode --version. If opencode isn't on $PATH, the check should fail gracefully and prompt to continue. If it hangs, cancel with Ctrl-C and check which opencode.

jq: command not found during ./install.sh.

The install script falls back to copying the template opencode.json instead of merging. You'll lose any custom config you had. Install jq (brew install jq, apt install jq) and re-run the script — it will preserve your existing config on the second run.

Plugin copy fails with "no such file or directory" on Windows.

The find command in install.sh uses POSIX semantics. On Windows, use Git Bash or WSL, not cmd.exe.

opencode restarts but the new agents don't appear.

The opencode TUI caches the agent list at startup. After running the installer, fully quit opencode (Ctrl-C twice) and start it again — /agents should now show Odin, Thor, Tyr, etc.

bizarharness init doesn't detect my stack.

init only recognizes package.json, pyproject.toml, Cargo.toml, and go.mod. If your project uses something else (Bun, Deno, a Makefile-only build), init will report the language as "unknown" and skip skill pack installation. The .bizar/PROJECT.md file is still created and can be edited by hand.

Next steps

Next: Quick Start — a five-minute tour of the agent system in action.

For the full architecture, see Architecture.