rolebox

What it is / why you'd want it

A general coding agent is one agent with one prompt. rolebox turns it into your configured team: specialist roles you define in YAML, each with its own prompts, model, skills, and permissions, working the same task together. What they learn survives the session — decisions, conventions, and lessons persist in memory — and a graph execution engine actually runs the team: dispatching each role, carrying results and signals between them, enforcing budgets, loop caps, and approval gates.

The pitch, concretely

• It remembers your project. Decisions, conventions, and lessons persist in memory and auto-inject at session start (<available_memory>) — you stop re-explaining yourself.
• Your team, defined by you. Every specialist is a YAML role with its own prompt, model, skills, and permissions — install one from the registry or write your own.
• Real concurrency with a ceiling. Parallel multi-agent dispatch with engine-managed concurrency, per-node budgets, and retries — the team scales without runaway spend.
• Autonomy you can gate. Workflows run as an explicit graph with bounded loops, and a node flagged needs_approval: true pauses the graph until you approve it.
• Edits that never drift. 30+ language-server tools (go-to-definition, diagnostics, references, rename) plus content-hash-anchored editing that survives concurrent file changes.

The graph engine is how the team runs: graph_create → graph_add_node / graph_add_edge → graph_run builds an explicit workflow, and graph_status reads results back. graph_run is non-blocking — you end your turn and the engine wakes you with [GRAPH COMPLETE], or [GRAPH BLOCKED] at an approval gate. Architecture and the full toolset: docs/graph-engine-architecture.md.

Supported harnesses

| Harness | Config directory | Roles directory | Global skills | Env override | |---|---|---|---|---| | opencode | ~/.config/opencode | ~/.config/opencode/rolebox | ~/.config/opencode/skills | XDG_CONFIG_HOME | | pi | ~/.pi/agent | ~/.pi/agent/rolebox | ~/.pi/agent/skills | PI_CODING_AGENT_DIR | | dsh | ~/.dsh | ~/.dsh/rolebox | ~/.dsh/skills | DSH_HOME | | Codex | ~/.codex | ~/.codex/rolebox | ~/.codex/skills | CODEX_HOME |

On every harness a rolebox/ directory in the current working directory takes precedence over the global roles directory; registry roles install with rolebox install <name> and deploy with rolebox sync <opencode|pi|dsh|codex>. Jump to setup: opencode · pi · dsh · codex

60-second install

opencode

cd ~/.config/opencode && npm install rolebox
mkdir -p ~/.config/opencode/rolebox && cd ~/.config/opencode/rolebox && rolebox init my-agent -y

// ~/.config/opencode/opencode.jsonc
{ "plugin": ["rolebox"] }

pi

pi install npm:rolebox     # project-local instead: pi install -l npm:rolebox
mkdir -p ~/.pi/agent/rolebox && cd ~/.pi/agent/rolebox && rolebox init my-agent -y
# from a checkout instead: add "extensions": ["/path/to/rolebox/dist/entries/pi.js"] to ~/.pi/agent/settings.json

dsh

dsh plugin --profile <name> add rolebox    # installs the bundle into that profile
mkdir -p ~/.dsh/rolebox && cd ~/.dsh/rolebox && rolebox init my-agent -y   # $DSH_HOME/rolebox if set

Restart the harness. A non-bundle dsh install instead needs one - insert: row naming the profile-relative ./node_modules/rolebox/dist/entries/dsh.js in the profile's cordis.patch.yml — see examples/dsh/cordis.patch.yml. Profile patch semantics, the web role-switch dock, and the /rolebox REST surface are documented in docs/dsh-plugin-contract.md.

codex

npm install -g rolebox     # or run from a checkout built with `bun run build`
rolebox sync codex

rolebox sync codex writes the local plugin bundle under $CODEX_HOME/rolebox-marketplace (~/.codex/rolebox-marketplace by default), registers it in the Codex config.toml, and deploys installed roles to $CODEX_HOME/rolebox. The bundle starts the rolebox MCP server (rolebox mcp), which exposes rolebox's canonical tools over stdio. Restart Codex afterwards. Details: docs/codex.md.

Deprecated entry paths. The former dist/index.js, dist/pi-extension.js, and dist/dsh-plugin.js artifacts still resolve as generated re-export aliases, but they are deprecated — new checkouts and profile rows should use the canonical dist/entries/*.js paths instead.

Comparison: opencode vs + rolebox

| Capability | Raw opencode | + rolebox | |---|---|---| | Persistent memory | ❌ Sessions start blank | ✅ SQLite + FTS5, auto-inject past decisions | | Multi-agent teams | ❌ Single agent | ✅ YAML-defined specialists, parallel dispatch | | LSP integration | ❌ No language server access | ✅ 30+ tools (go-to-def, references, rename, diagnostics…) | | Hashline editing | ❌ Line-number based | ✅ Content-hash anchored — edits never drift | | Background dispatch | ❌ Sequential | ✅ Real concurrency with budget tracking | | Hot-reload assets | ❌ Restart required | ✅ Edit YAML, reload instantly |

See it work

Loop mode runs the same task across N fresh sessions: |loop:N| executes real multi-round iterations, each round dispatching the task to a fresh worker session and reporting its own outcome — useful for refinement passes, batch fixes, and self-correcting workflows.

Role gallery

| Role | What it does | |---|---| | emperor | Top-level orchestrator — plans, delegates, validates complex work across a specialist team | | software-architect | System design, trade-off analysis, ADRs, C4 models, and architecture reviews | | react-frontend | React/Next.js component design, state management, and frontend architecture | | ai-designer | AI application design with humane UX gates, interaction modeling, and design system creation | | tauri | Desktop app development with Tauri v2 — IPC, plugins, window management, system tray | | dart-flutter | Cross-platform mobile and desktop Flutter development with full gate review pipeline |

Install any role from the oh-my-role registry with rolebox install <name> and restart your harness.

CLI reference

| Command | Description | |---|---| | rolebox init <name> | Scaffold a new role directory | | rolebox install [name] | Install a role from the registry (picker when omitted) | | rolebox status | List installed roles and their status | | rolebox info [name] | Inspect one role in detail (picker when omitted) | | rolebox sync <target> | Deploy installed roles to opencode / pi / dsh / codex | | rolebox mcp | Run the rolebox MCP server on stdio (Codex integration) | | rolebox config [name] | Configure a role's models (--target selects the harness) | | rolebox monitor | Runtime dashboard (TUI): loops, graph workflows, dispatch | | rolebox memory search <query> | Full-text search across persistent memory | | rolebox --version | Show version |

Model Alias Configuration

Registry roles often ship placeholder model names; map them once in role_config.yaml — ~/.config/opencode/role_config.yaml, ~/.pi/agent/role_config.yaml, ~/.dsh/role_config.yaml, or ~/.codex/role_config.yaml (the harness config directory). Unrecognized values pass through unchanged with a warning. Full resolution chain, error handling, and hot-reload: docs/model-aliases.md.

Upgrading from 0.x.x? rolebox 1.x replaced the 0.x execution model. Workflows are now built and run imperatively on a graph execution engine — graph_create → graph_add_node / graph_add_edge → graph_run — instead of being declared in role.yaml. See docs/graph-engine-architecture.md.

Docs index

| Topic | Docs | Topic | Docs | Topic | Docs | |---|---|---|---|---|---| | Create a Role | create-a-role.md | role.yaml Reference | role-yaml.md | Directory Structure | directory-structure.md | | Functions | functions.md | Copilot (Turn-End) | copilot.md | Skills | skills.md | | References | references.md | Subagents | subagents.md | Graph Engine | graph-engine-architecture.md | | Memory Strategy | memory-strategy.md | Model Aliases | model-aliases.md | CLI | cli.md | | Session Tools | session-tools-strategy.md | Dispatch Config | dispatch-config.md | Custom Hooks | hooks.md | | Extensions | extensions.md | Registry | registry.md | Error Handling | error-handling.md | | Limitations | limitations.md | Compatibility | compatibility.md | dsh Plugin Contract | dsh-plugin-contract.md | | dsh Provider Notes | dsh-provider-notes.md | Install/Update Audit | audit-install-update-platform.md | CLI Output Audit | audit-progress-ui.md | | Codex | codex.md | Compatibility | compatibility.md | Limitations | limitations.md |

Contributing

Contributions welcome — see CONTRIBUTING.md.

License

MIT — see the LICENSE file.