Golem

Golem is a local-first orchestration layer for agentic coding harnesses. It adds shared roles, a SQLite-backed tracker and dashboard, session discovery, durable delivery, lifecycle journals, and evidence-based verification without replacing the native harness.

The canonical source is substrate/. Harness adapters render it into the native surfaces each harness supports. The dashboard is the tracker’s single writer; hooks, shims, and MCP tools connect live sessions to it.

Supported harnesses

Harness	Current support	Start with
Codex	Tier A through the managed private bridge; a separately launched codex is pull-only	golem codex
Claude Code	Tier A development-channel delivery; plain claude can pull work only	golem claude
OpenCode	Tier A checkout-bound shim and bridge; opt-in	opencode after sync
Pi	Tier A worker with typed delivery; Node.js 22.19+ and Pi 0.84.3	golem pi
Gemini CLI	Unsupported; no adapter or release contract is shipped	—

The built-in roles are lead, builder, explorer, and reviewer.

Requirements

• Golem requires Node.js 22.19 or newer and npm. Pi uses the pinned @earendil-works/pi-coding-agent 0.84.3 release.
• Git.
• At least one supported coding harness installed separately.

Install from a source checkout

The npm package is not the install path. Clone this repository and link its CLI:

git clone https://github.com/laveesingh/golem.git
cd golem
npm ci
npm link
golem doctor
golem dashboard

Keep golem dashboard running. It serves the tracker and dashboard at http://dashboard.golem.localhost:7420. The *.localhost name is reserved for loopback by RFC 6761; no /etc/hosts entry is needed. The dashboard has no authentication, so do not use golem dashboard --public on an untrusted network.

Choose a harness in another terminal. Run its sync command after the source checkout install and before its first launch.

Claude Code

golem sync --target cc
golem sync --target cc-marketplace
claude plugin marketplace add ~/.golem/renders/cc-marketplace
claude plugin install golem@golem-workspace --scope user
golem claude

golem claude supplies Claude Code's development-channel launch. A plain claude session has Golem tools but must pull work. After a render update, run claude plugin update golem@golem-workspace and /reload-plugins in existing sessions.

Codex

For an ordinary Codex session, render and install the local plugin marketplace, then launch Codex:

golem sync --target codex
codex plugin marketplace add ~/.golem/renders/codex
codex plugin add golem@golem-workspace
codex

Ordinary codex delivery is pull-only. golem codex is the managed private bridge and is version-gated; see the Codex contract before using its managed delivery. The wrapper owns Codex's remote bridge and working directory, so do not pass --remote or -C/--cd to it.

OpenCode

OpenCode is disabled until enabled in ~/.golem/config.json:

{
  "harnesses": {
    "opencode": {
      "enabled": true,
      "modelMap": {},
      "testedVersion": null
    }
  }
}

Then render and launch:

golem sync --target opencode
opencode

OpenCode is bound to this source checkout. Sync writes an absolute file://.../shims/opencode/index.js entry and an absolute MCP path into ~/.config/opencode/opencode.jsonc; keep this checkout in place and re-run sync if it moves. There is no portable OpenCode package in this repository.

Pi

Install the supported Pi release separately, then render and launch a native Pi session:

golem sync --target pi
golem pi --provider <provider> --model <model>

Use golem pi --role builder, --role explorer, --role reviewer, or --role lead for a validated role preset. Pi keeps its own profile, providers, authentication, models, extensions, and sessions; Golem does not copy or rewrite that configuration.

Work model

The tracker is the source of truth for cross-session work. Ticket lifecycle is state only: todo, in_progress, blocked, review, done, or archived. Comments, dispatch, session_notify, and sessions_dispatchable provide the coordination surface. The dashboard event ledger is durable audit history, not a message subscription.

Sessions register their project, harness, role, and delivery capability. Golem routes work only through a supported path: managed Codex delivery, Claude's development channel, the OpenCode bridge, or Pi's typed-worker endpoint.

For architecture and source ownership, use REPO-MAP.md rather than this README as the repository map.

Dashboard and CLI

The dashboard serves the ticket board, session roster, chat, dispatch controls, REST API, and WebSocket updates.

golem dashboard
golem dashboard:restart
golem status
golem doctor
golem help

Command	Purpose
golem dashboard	Start the dashboard in the foreground.
golem dashboard:restart	Replace the registered dashboard with a detached instance.
golem status [--json]	Report dashboard health and its canonical URL.
golem doctor	Check dependencies, local state, renders, integrations, and dashboard reachability.
golem sync ...	Render or check cc, cc-marketplace, opencode, codex, and pi outputs.
golem role <role|clear>	Set or clear a session role. Built-ins are lead, builder, explorer, and reviewer.
golem migrate-home	Move legacy local state to ~/.golem, with a backup and rollback.
golem codex-supervisor ...	Run or inspect the managed Codex App Server supervisor.

Use golem sync --check --all to inspect render drift. Edit substrate/, not the generated plugin/ tree. The committed plugin/ tree is the generated CC round-trip and rollback copy; the live install uses ~/.golem/renders/.

Local state and safety

Mutable state normally lives in ~/.golem/:

• tracker.db — tickets, comments, dispatch records, and events.
• projects.json, sessions.json, and session-facts.json — project and live-session registries.
• journals/<project_id>/hook.jsonl — lifecycle and tool-event history.
• renders/ and substrate.lock — generated harness output and drift metadata.
• dashboard.json, endpoint leases, and harness bridge registries — live routing.
• ticket-assets/, logs/, and Codex supervisor state — supporting local state.

GOLEM_HOME overrides the state root. Existing XDG installations can be moved explicitly with golem migrate-home.

Journals and tracker data may contain prompts, model output, tool arguments, paths, and other sensitive local context. Protect the state directory. Read PRIVACY.md and SECURITY.md before exposing services or sharing diagnostics.

Development

npm ci
npm test
npm run dashboard:build
npm run check:dashboard
npm run test:release
git diff --check

See CONTRIBUTING.md for contribution rules, REPO-MAP.md for code ownership, and substrate/README.md for harness render details.

License

MIT