# Critical Review: `oh-my-opencode-slim` by alvinunreal ## High-Level Summary **oh-my-opencode-slim** is an agent orchestration plugin for **OpenCode** (an AI coding assistant). It provides a "pantheon" of specialized AI agents — Orchestrator, Explorer, Librarian, Oracle, Designer, Fixer, Council, Councilor, Observer — that can be automatically delegated to based on task type. Think of it as a multi-agent architecture where one orchestrator agent routes sub-tasks to specialist agents, each potentially using a different LLM model, balancing speed, cost, and quality. It's a **slimmed-down fork** of the larger `oh-my-opencode` project. Version 2.1.0, written in TypeScript, built with Bun. --- ## ✅ PROS ### 1. Compelling Architecture & Design - **Multi-agent orchestration with smart delegation** is genuinely forward-thinking. Instead of one model doing everything, the orchestrator reads rich agent descriptions (with stats like "2x faster codebase search", "5x better decision-maker", "10x better UI/UX") and routes tasks accordingly. This is a novel, practical approach to the "one model to rule them all" problem. - **Model mixing** — you can assign different models to different agents (e.g., GPT-5.5 for the orchestrator, a cheaper mini model for the explorer). This is powerful for cost optimization. - **Council/Councillor system** — a multi-LLM session orchestration pattern where multiple models deliberate, which is genuinely innovative. ### 2. Excellent Documentation & README (54KB) - The README is exceptionally thorough: quick start, manual install, "Meet the Pantheon" agent descriptions, feature workflows, MCP integration guide, configuration deep-dives, presets (OpenAI + OpenCode Go), migration guides, and troubleshooting. - Multilingual: README in English, Chinese, Japanese, Korean. - AGENTS.md provides comprehensive agent coding guidelines, project structure maps, lifecycle management docs (tmux session handling), and a clear release workflow. - A `codemap.md` exists for AI agents navigating the codebase. ### 3. Solid Tooling & Developer Experience - **Biome** for linting/formatting (not ESLint/Prettier) — modern, fast, unified. - **Bun** as runtime — fast builds and tests. - **TypeScript strict mode** enabled. - **Zod** for runtime validation (v4). - Clean npm scripts: `check`, `check:ci`, `typecheck`, `test`, `build`, release scripts (patch/minor/major/beta with git tags). - `turndown` + `jsdom` + `@mozilla/readability` for web page-to-markdown conversion — practical for web research. ### 4. Strong Community Signals - **6,500+ GitHub stars** — significant adoption and interest. - **397 forks** — active community engagement. - **102 open issues** — while high, this indicates active users reporting bugs/requests. - Testimonials from real users in the README are detailed and credible (verbatim quotes about workflow improvements). ### 5. Thoughtful UX Features - **LazySkills TUI** — a terminal UI for managing agent skills, visibility diagnosis, and safe action suggestions. - **Multiplexer integration** (tmux/Zellij/Herdr) — opens each agent in a dedicated pane so users can watch specialists work live. - **Schema auto-generation** (`generate-schema` script) so configs get autocomplete. - **Graceful shutdown** lifecycle — Ctrl+C before kill-pane, proper session.abort() ordering. ### 6. Extensibility - ACP (Agent Communication Protocol) support for external agents. - Custom agent prompts (base/custom/append resolution). - Skill system per agent with granular permissions. - MCP (Model Context Protocol) server integration per agent with include/exclude patterns. ### 7. Testing - Unit tests for council, councillor, custom agents, display-name resolution, TUI state, etc. - TypeScript strict mode catches issues at compile time. - CI checks with `check:ci`. --- ## ❌ CONS ### 1. Code Quality & Maintainability Concerns **a) Massive, monolithic files** - `src/agents/index.ts` is **737 lines** (652 lines of code) — a single file that is a God object handling agent factory creation, model resolution, ACP agent building, display name normalization, and more. This is a maintenance smell and SRP violation. - `src/agents/orchestrator.ts` is **302 lines** — should be split into smaller modules (prompt resolution, agent description constants, the orchestrator factory itself). - The orchestator prompt descriptions contain 100+ line string constants inline — these should be external template files. **b) No test coverage metrics visible** - While some tests exist, for a plugin with 10+ agents, council system, multiplexer integration, skill management, and TUI, the test coverage appears thin. No coverage tool is configured, and critical paths (multiplexer lifecycle, MCP integration, permission resolution) aren't obviously tested. **c) No CI/CD pipeline visible** - No `.github/workflows` visible — no automated testing on PRs, no release automation. The release scripts (`release:patch`, etc.) rely on local `npm version` + `git push` which is fragile and bypasses CI gates. **d) 102 open issues with only 5 open PRs** - This ratio (102 issues vs 5 PRs) suggests the maintainer may be overwhelmed or bottlenecked. Many issues could be bug reports from users hitting problems. ### 2. Configuration Complexity - The plugin requires a deeply nested JSON config (`~/.config/opencode/oh-my-opencode-slim.json`) with presets, per-agent model overrides (which can be strings or arrays of objects with `variant`), skill lists, MCP lists with include/exclude patterns (`["*", "!context7"]` syntax). This is powerful but **extremely complex** for new users. - The concept of "variants" (`low`, `medium`, `high`, `max`) per model is not clearly documented — how do these map to actual API parameters? Are they model-specific? This opacity could lead to surprising behavior. ### 3. Dependency & Stability Risks **a) Heavy dependency on `@opencode-ai/sdk` and `@opencode-ai/plugin`** - These are v1.x.x packages (`^1.3.17`) — relatively early-stage dependencies. If OpenCode changes its API, this plugin breaks. - The plugin is tightly coupled to the OpenCode ecosystem; it has no value outside of OpenCode. **b) `@ast-grep/cli` as a runtime dependency (not dev)** - AST-grep is pulled in as a full runtime dependency for code search. This works, but it's a heavy dependency (Rust binary via npm) that's only used by one agent type. **c) Optional `@opentui/solid` dependency (v0.1.97 — very early)** - The TUI relies on a pre-v1.0.0 SolidJS-based terminal UI framework. If this project changes API or is abandoned, the LazySkills feature is impacted. **d) Version 2.1.0 but the original `oh-my-opencode` project already went through a "slim" rewrite** - The project name literally acknowledges it's a simplification of an earlier project. This raises questions about whether the original was over-engineered and whether this version carries forward architectural debt. ### 4. Documentation Decay Risks - The README is massive (54KB, 826 lines) — it's impressive but also fragile. References to model names like "gpt-5.5", "gpt-5.4-mini", "deepseek-v4-flash", "glm-5.2", "qwen3.7-max" are likely **fictional/future model names** or placeholders that don't exist yet. As actual models ship with different names, this documentation will immediately become stale/confusing. - The AGENTS.md file contains an agent coding guidelines section that references `@modelcontextprotocol/sdk` `^1.29.0` and `zod` `^4.3.6` as key dependencies, but these are actually listed differently in package.json — there's a minor mismatch risk. ### 5. Potential Prompt Engineering Fragility - The agent delegation system is driven by **prompt-based descriptions** (e.g., "2x faster codebase search than orchestrator", "5x better decision maker"). These are heuristic claims embedded in prompts — they are not enforced in code. The orchestrator LLM must correctly interpret these qualitative descriptions and make good routing decisions. If the LLM ignores or misinterprets them (which LLMs frequently do with complex routing instructions), the entire delegation system degrades silently. - The "Don't delegate when" sections in agent descriptions are instructions to the LLM not to delegate certain tasks — but LLMs famously struggle with negative instructions ("don't think of a pink elephant"). ### 6. Security Surface - Agents have file read/write permissions, and the permission system is defined but not deeply auditable from the surface. A prompt injection in a web page that the librarian agent reads could potentially lead to file writes if the orchestration prompt is compromised. - The `@fixer` agent has file write permissions — if misrouted by a confused orchestrator, this could cause unintended modifications. ### 7. Community & Sustainability - Single-maintainer project ("by Boring Dystopia Development" — which appears to be the sole maintainer alvinunreal). With 6.5k stars, 100+ open issues, and only 5 PRs, this looks like a **bus factor of 1** situation. - The project's future depends entirely on one person's continued interest and availability. --- ## Overall Verdict **Rating: 7.5/10 — Promising but with rough edges** oh-my-opencode-slim is genuinely innovative — the multi-agent orchestration with model mixing, council deliberation, and automatic delegation is ahead of most alternatives in the AI coding assistant space. The documentation quality, community enthusiasm (6.5k stars), and thoughtful UX features (LazySkills TUI, multiplexer integration) show real craftsmanship. However, the project has **scalability concerns**: monolithic source files, unclear test coverage, no CI/CD, heavy prompt-engineering reliance for core logic, and a single-maintainer bottleneck with 100+ open issues. The configuration complexity and model-name instability in docs are barriers to entry. **Best for**: Power users who want fine-grained control over multi-model AI coding workflows, are comfortable with JSON configuration, and are already invested in the OpenCode ecosystem. **Not ideal for**: Users seeking a plug-and-play experience, teams requiring auditable/ deterministic behavior, or anyone uncomfortable with experimental pre-v1.0 dependencies.