rolebox

See it in action — placeholder for demo GIF showing multi-agent dispatch running in opencode with Emperor orchestrating a team of specialists.

Your AI Assistant Forgets Everything. rolebox Fixes That.

Every AI coding session starts from scratch. Your assistant doesn't remember yesterday's architecture decision, last week's bug fix, or the convention you established three sessions ago. You repeat yourself. It repeats mistakes. Progress slows.

rolebox gives your AI a persistent memory. Across sessions, across projects, your agents remember.

But memory is just the beginning. rolebox transforms a generic chat assistant into a precision tool: a full engineering team that lives in YAML, deploys in seconds, and remembers everything.

What rolebox Gives You

🧠 Persistent Memory System

Your AI forgets nothing.

• SQLite + FTS5 — full-text search across every stored decision, convention, and lesson
• Workspace vs Role isolation — share project knowledge across all agents, keep role-specific notes private
• |memory| consolidation mode — review past sessions, extract durable knowledge, deduplicate, and persist
• Auto-injection — relevant memories surface at session start as <available_memory>
• CLI — rolebox memory list, search, export, stats

# Review the last 5 sessions and persist new knowledge
# (use |memory| mode inside opencode)
# CLI query:
rolebox memory search "database migration strategy"

Real result: your architect role remembers the caching strategy it designed last month. No re-explaining. No repetition.

🔬 LSP Integration (30+ Tools)

Every language server tool your IDE has, now inside your AI assistant.

| Category | Tools | |---|---| | Navigation | go-to-definition, go-to-declaration, go-to-type-def, go-to-implementation, find-references | | Diagnostics | lsp diagnostics (errors/warnings/hints per file or workspace-wide) | | Code Actions | quick-fixes, refactorings, organize imports — apply by title | | Completions | context-aware code completions with docs | | Formatting | full-document or range format | | Hover | type signatures, documentation, inline hints | | Symbols | document symbols, workspace symbols, semantic tokens, folding ranges | | Hierarchy | call hierarchy (incoming/outgoing), type hierarchy (super/sub types) | | Inlay Hints | type hints, parameter name hints | | Document Links | clickable URLs and cross-references |

No plugin per language. One system speaks to every LSP server. Automatic detection.

✂️ Hashline Editing — Edits That Never Drift

Line-number-based edits break when the file changes. rolebox uses content-hash-anchored editing instead:

• Every line tagged with a content hash — LINE#HASH
• Edits match by hash, not position. If the file changes between read and write, the edit targets the content, not the line.
• Multi-edit batching with snapshot semantics — all edits reference the original file state, applied bottom-up so indices always stay correct
• SHA-256 version tracking — detects external modifications before applying

- #10#aB  oldString      ← fragile, drifts on insert/delete
+ #10#aB|newString       ← hash-anchored, survives edits above

📬 Desktop Notifications

Never stare at a loading screen again.

• Native OS notifications when tasks complete
• Idle detection — only notify when you're away from your keyboard
• Quiet hours — scheduled silence (no 2 AM pings)
• Configurable channels — system toast, sound, webhook, file, log, or custom commands
• Event-type filtering — task complete, question asked, permission required, errors, loop complete
• Smart throttling — burst protection so you don't get spammed

// ~/.config/opencode/rolebox/notifications.jsonc (optional)
{
  "channels": { "system_toast": { "enabled": true } },
  "quiet_hours": { "start": "22:00", "end": "08:00" },
  "notify_on": ["dispatch_complete", "error"]
}

🔄 Session Management (10 Tools)

Your AI's entire work history, searchable and analyzable.

| Tool | What it does | |---|---| | session_list | List all sessions, filter by date range or project | | session_read | Full transcript with model, cost, and token metadata | | session_search | Full-text search across every message in every session | | session_info | Token usage breakdown, cost, tool frequencies, model distribution | | session_diff | Unified diff of all file changes in a session | | session_branch / fork | Branch a session at any message — like git for conversations | | session_changes | Full file change history per message | | session_inspect | Comprehensive analytics dashboard |

🚀 Dispatch System

Run multiple agents in parallel. Track everything.

• Background execution with real concurrency control (model-pool semaphores)
• Budget tracking per request — token/cost limits enforced automatically
• Task retry with full context preservation — failed tasks resume where they left off, not from scratch
• Task dependency graphs — visualize parent-child dispatch trees
• Chronology views — time-bucketed activity by hour, day, or agent
• Metrics & observability — real-time counters, gauges, histograms
• Watchdog — stale task detection and orphan prevention
• Result extraction — structured artifact fences (```result)

⚙️ Function State Machine

Functions aren't just injected prompts — they have lifecycle.

• Phase-based activation — active, gated, dormant states
• Evidence observation — functions track which verification tags are satisfied
• Artifact tracking — produced/consumed file status
• Transition conditions — state graphs with conditional activation
• Continuation counting — bounded retry loops

See docs/functions.md for the full spec.

🧩 Context Assembly

One tool to search everything: memory + assets + tasks + sessions.

• Cross-domain search across 4 knowledge stores
• Token-bounded context blocks — automatically truncated to fit budget
• Intelligent relevance ranking with priority boosting
• Configurable source selection (any combination of memory, assets, tasks, sessions)

📦 Asset Management

Roles, skills, functions, references — all hot-reloadable at runtime.

• Hot-reload — edit a skill or role YAML, reload without restart
• Asset search — find any skill, function, or reference by keyword across all roles
• Asset inspect — view complete frontmatter metadata for any asset
• Asset validation — dependency checking, broken reference paths, unknown conditions
• Skill composition analysis — detect conflicts and reference deduplication across skill combinations

rolebox status          # Check all roles and their status
rolebox info <name>     # Detailed role inspection
rolebox sync            # Sync installed roles with registry
rolebox monitor         # Live dispatch metrics dashboard (TUI)

What rolebox Adds to opencode

| 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 | | Desktop notifications | ❌ None | ✅ Native OS, quiet hours, idle detection, throttling | | Session analytics | ❌ Basic session list | ✅ 10 tools: search, export, fork, diff, inspect | | Background dispatch | ❌ Sequential | ✅ Real concurrency with budget tracking | | Task dependency graphs | ❌ Flat | ✅ Visualize parent-child dispatch trees | | Function state machine | ❌ Static prompts | ✅ Phased lifecycle with evidence & transitions | | Context assembly | ❌ Manual | ✅ Cross-domain search (memory + assets + tasks + sessions) | | Hot-reload assets | ❌ Restart required | ✅ Edit YAML, reload instantly | | Asset validation | ❌ None | ✅ Dependency & integrity checks | | Shareable role registry | ❌ None | ✅ npm-style rolebox install <name> | | Orchestrator (Emperor) | ❌ None | ✅ Plan → dispatch → validate → revise loop |

Quick Start

cd ~/.config/opencode && npm install rolebox

Add to opencode.jsonc:

{
  "plugin": ["rolebox"]
}

Create your first role in 30 seconds:

rolebox init my-agent -y

A ready-to-use role directory lands in ~/.config/opencode/rolebox/my-agent/. Restart opencode and pick it from your agent list.

Install the Emperor orchestrator:

rolebox install emperor

✨ Featured: Emperor — Your AI Engineering Lead

Emperor is a top-level orchestrator that plans, delegates, and validates complex work across a team of specialist sub-agents — without writing any code itself.

rolebox install emperor

How it works:

1. You describe what you need (in plain English)
2. Emperor plans the work (3-stage: draft → review → finalize)
3. Dispatches subtasks to specialists (ui, backend, test, data, docs, quality) in parallel where possible
4. Validates every result — closed-loop verification
5. Revises if needed — 2-round re-dispatch with correction budget
6. Reports back with a structured summary

Architecture:

• 3-stage planner — draft, review, finalize — catches plan flaws before execution
• 6 department workers — ui, backend, test, data, docs, quality
• Multi-subtask dependency scheduling — parallelization where possible, sequential where not
• Budget-bounded concurrency — respects model pool limits automatically
• Live risk gate — destructive operations flagged for user approval

Emperor NEVER writes code. It reads, routes, and summarizes. Best for complex multi-step work, architecture decisions, refactoring, and anything that needs strategy before execution.

Role Gallery

Pre-built roles available from the oh-my-role registry:

| 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 with rolebox install <name> and restart opencode.

Full Feature Reference

| Topic | What | Docs | |---|---|---| | Functions | Composable behavior modules with state machine lifecycle. Activated with \|name\| syntax. | docs/functions.md | | Skills | On-demand knowledge modules. Only load what you need, when you need it. | docs/skills.md | | References | Deep-knowledge documents agents read for domain context. Auto-discovered. | docs/references.md | | Subagents | Child agents with their own prompts, skills, models. Dispatch via dispatch() tool. | docs/subagents.md | | Collaboration Graph | Workflow topologies (pipeline, review-loop, star) — rolebox routes automatically. | docs/collaboration-graph.md | | Custom Hooks | JavaScript modules that fire on chat, tool, and lifecycle events. Phase-aware. | docs/hooks.md | | Extensions | Open rolebox's closed vocabularies — custom conditions, topologies, recovery strategies. | docs/extensions.md | | Memory Strategy | How persistent memory works across sessions with FTS5 search. | docs/memory-strategy.md | | Session Tools | Full session management tool reference with usage patterns. | docs/session-tools-strategy.md | | CLI | Install, search, update, sync, monitor, manage roles. | docs/cli.md | | role.yaml Reference | Full schema: model config, skills, functions, subagents, dispatch, hooks, permissions. | docs/role-yaml.md | | Dispatch Config | Concurrency, budgets, timeouts, queue depth — per-role or env vars. | docs/dispatch-config.md | | Registry | Publish your own role registry on GitHub. Share with versioning and tags. | docs/registry.md | | Create a Role | Hand-written role setup, directory structure, examples. | docs/create-a-role.md | | Error Handling | Invalid YAML, missing skills, missing functions — all fail gracefully. | docs/error-handling.md | | Limitations | No role inheritance, no runtime switching, no cross-subagent communication. | docs/limitations.md | | Compatibility | Works alongside oh-my-openagent. No conflicts. | docs/compatibility.md | | Directory Structure | Complete file layout reference. | docs/directory-structure.md |

Community & Contributing

• Docs: Full reference at docs/
• Registry: Browse roles at oh-my-role
• Discord: [add invite link]
• Issues & PRs: Welcome. See the contributing guide for guidelines.

Build roles. Share them. Make your AI assistant work the way you do.

License

MIT — see the LICENSE file.