---
name: workbench-setup
description: Install, inspect, update, or remove Agent Workbench shared global instructions and its local launcher while preserving personal instruction text.
---

Use the bundled Python 3.11+ installer on Linux or macOS. Native `npx skills` distributes this skill; it does not execute the installer or apply global prompts.

Orchestration's interactive Manager, native Worker ladder and configured context policy live in the `orchestrate-harnesses` skill. Window values come from the effective model configuration, not skill or role instructions. Updating that skill changes its distributed defaults, not the current Manager's interactive model/settings or the user's partial model overrides. Remove obsolete `roles.manager`/`roles.preflight`/`roles.acceptance` and controller-only log/prompt overrides as described in that skill before the next dispatch. Setup does not migrate those private settings or rewrite historical tasks. Private rules outside the managed block may still require a Gateway/fixed Manager or Python controller; inspect and reconcile those explicitly when migrating.

After global distribution, explicitly apply the setup:

```sh
python3 ~/.agents/skills/workbench-setup/scripts/workbench.py install
~/.local/bin/agent-workbench status
```

The installer creates `~/.agents/AGENTS.md`, links Codex's `~/.codex/AGENTS.md`, and ensures `~/.claude/CLAUDE.md` has one native import resolving to the shared instructions. An existing equivalent Claude import is reused. Personal text belongs outside `<!-- BEGIN agent-workbench -->` and `<!-- END agent-workbench -->` in the shared file. Existing Codex regular-file bytes migrate there on first installation; existing Claude text stays in its file.

`agent-workbench install` reapplies distributed assets. `agent-workbench update` first updates only installed skills owned by `onsager-ai/agent-workbench` through the native skills lock, then runs freshly distributed setup code. Node.js 22.20+ and npx are needed for distribution and updates. Do not edit the native skills lock yourself.

When `orchestrate-harnesses` is installed, `install` (and `update`) also generates one Claude Code subagent per routable tier at `~/.claude/agents/<role>.md` (`luna`, `haiku`, `flash`, `terra`, `sonnet`, `sol`, `opus`), so a Claude Manager can dispatch `subagent_type: <role>`. A tier is routable when its role has `cli: claude` (using `model`) or a non-null `claude_model` in the effective model configuration, which merges the user's partial override over the distributed `models.json`. Claude tiers are generated by default; Codex tiers need a gateway route, for example `{"roles": {"luna": {"claude_model": "<gateway model ID>"}}}`, and no gateway or provider prefix is built in. Each file carries the tier's model and effort in frontmatter and the Worker instructions as its prompt. Rerun `agent-workbench install` after editing the override; a tier whose route is removed loses its generated file. Without `orchestrate-harnesses` no agents are generated, and status says so.

Generated agent files are recorded with content hashes in the state file. Setup never overwrites a file it does not own, or an owned file you edited, and reports a conflict instead; other files in `~/.claude/agents` are left alone. `status` lists owned agents and `uninstall` removes unmodified ones.

`agent-workbench uninstall` removes the public block and owned import/launcher, and makes Codex's file regular again with the current private text. Backups remain private under `~/.local/state/agent-workbench/backups`; uninstall never restores stale snapshots over later edits. This is the normal rollback operation. Review retained backups manually for historical recovery.

If a command reports an override, foreign entry, missing resource, or edited managed block, preserve the files and resolve that specific conflict before retrying. There is no force-overwrite mode. State and lock live under `~/.local/state/agent-workbench/`. Installation also owns `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` in `~/.claude/settings.json` and `model_auto_compact_token_limit` and optionally `model_context_window` in `~/.codex/config.toml`, when the respective config directory exists. It preserves other settings, including Magpie routing. Foreign or edited owned values conflict; missing values are reapplied. Status reports each key and uninstall removes only unmodified owned values. Compaction is advisory, not a hard request-token cap; restart running sessions to pick up changes. Installation does not edit other skills, project files, shell configuration, credentials, or permissions.

For isolated fixtures, put the skill at the canonical location under a disposable home, then pass `--home PATH` before the command. Alternate-home updates require an explicit `--skills-cmd` executable command; they never default to the real user's npx update. Native permission choices remain with the user.