MadAppGang/magus instruction manual

1. What Magus is and how it relates to Claude Code

Magus is an MIT-licensed marketplace of Claude Code plugins maintained by MadAppGang. It is not a replacement for Claude Code: it extends the host through plugin manifests, slash commands, agents, skills, hooks, MCP servers, and project settings. **Classification:** `claude_extension`. Documented mechanisms are **context injection** (skills and knowledge), **orchestration** (agents and multi-model workflows), **interception/lifecycle control** (Claude Code hooks), and **tool surfaces** (MCP runtimes such as Claudish, Mnemex, and tmux-mcp). Some features also depend on external CLIs. Setup effort is best described as **medium** because basic plugins are simple to enable, while terminal, semantic-search, benchmarking, and external-model functions require separate binaries or credentials.

The supplied files document core development, Go, Bun/TypeScript, Dingo, project setup, design review, terminal operation, benchmarks, semantic code navigation, and multi-model collaboration. The main README also identifies `magus-marketing` for image/video plugins and `magus-alpha` for experimental plugins, but says no alpha plugins are published. Individual plugin licenses may differ from the repository license and are identified in their own manifests.

Repository marketing statements about speed, savings, quality, and production results are claims from the project and are not independently verified here. Likewise, the metadata mentions 15 plugins and a TUI installer, but the supplied first-party files do not document an installer workflow; this manual therefore does not invent one.

2. Install, enable, share, update, and verify plugins

Prerequisites are Claude Code with plugin support and GitHub access. The main README states a general Claude Code requirement, while `dev` specifically requires Claude Code ≥0.1.0 and runtime dependencies; dependency plugins using manifest `dependencies` follow a Claude Code v2.1.110+ pattern. Register the core marketplace once inside Claude Code:

/plugin marketplace add MadAppGang/magus

Enable only the plugins a project needs by editing `.claude/settings.json`; values must be booleans:

{
  "enabledPlugins": {
    "dev@magus": true,
    "code-search@magus": true,
    "multimodel@magus": true,
    "terminal@magus": true,
    "setup@magus": true
  }
}

Plugin IDs include their marketplace. For example, marketing plugins use `image@magus-marketing`, not `image@magus`. To share project configuration, the documented workflow is:

git add .claude/settings.json
git commit -m "Enable Magus plugins for this project"
git push

Each teammate still adds the marketplace once; after pulling the settings file, Claude Code detects, installs, and activates enabled project plugins. Update the marketplace with:

/plugin marketplace update magus

Verify the setup using `/doctor` and `/plugin list`. If a required knowledge provider is absent, a directly documented installation command is:

/plugin install dev@magus

The main README also documents `/implement Create a user profile page with avatar upload and bio editing` and `/import-figma NavigationBar` as top-level examples, but the supplied catalog files do not identify which current plugin owns them.

3. Universal development with dev and language-specific knowledge

`dev@magus` is the language-agnostic development assistant. Start with `/dev:help` to see the detected stack. `/dev:dev` runs depth-adaptive feature work; `/dev:debug` performs structured debugging; `/dev:fix` applies a TDD-oriented production fix; `/dev:architect` designs systems; `/dev:research` performs converging multi-source research; `/dev:interview` produces a requirements specification; and `/dev:investigate` performs read-only tracing and origin analysis. `/dev:audit` routes quality checks to the appropriate reviewer, `/dev:design-system` checks design-system guardrails, `/dev:doc` writes or repairs documentation, `/dev:learn` reviews session learnings, `/dev:setup` scaffolds project context, and `/dev:worktree` manages Git worktrees with optional database branching. Learning changes become standing guidance only after `/dev:learn --apply`; `/dev:learn --prune` removes entries.

Agents run in separate context windows. Build agents are `developer`, `frontend-developer`, and `devops`; understanding agents are `researcher`, `debugger`, `architect`, `aggregator`, and `stack-detector`; checking uses `reviewer` and `qa-engineer`; documentation uses `docs`; interviews use `spec-writer`. Skills are procedures registered for `/dev:<name>` use, while `knowledge/` files are references reached by path.

Hooks surface prior coaching, queue session learnings, enforce incomplete `/dev:dev` phases, inject plan/resume protocols, continue after plan approval, and restore runs after clear/compact. Disable them with `WORKFLOW_COACHING=off` or `WORKFLOW_LEARNING=off`; `DEV_COACHING_MODEL` changes the classifier model. Hooks and scripts require Bun. `dev` depends on Claudish and Multimodel.

The `go` plugin adds `/go-tui` plus Go references. With `dev`, developer, architect, reviewer, and QA agents automatically consume role-specific Go guidance. Without `dev`, only `/go-tui` and manual reference reading remain available.

4. Bun/TypeScript and Dingo development toolkits

The Bun plugin’s entry point is:

/bunjs:bun lets create a todo app

This index selects only the one or two relevant hidden skills. `/bunjs:project-setup` covers layouts, strict TypeScript configuration, typed environment data, workspaces, and tooling. `/bunjs:http-service` covers `Bun.serve`, routes, middleware, contexts, responses, and streaming. `/bunjs:errors` covers validation boundaries, operational versus programmer errors, timeouts, retries, and circuit breakers. `/bunjs:testing` covers `bun:test`, component tests, doubles, coverage, and flakes. `/bunjs:security` covers passwords, tokens, injection, rate limits, CORS, headers, and supply-chain concerns. `/bunjs:production` covers shutdown, logging, health checks, Docker, signals, and CI. `/bunjs:performance` covers profiling and measured optimization. `/bunjs:tui` covers OpenTUI, Yoga layout, widgets, gradients, and screenshot checking.

The source says only Bun was tested. It records measured traps, including ignored singular coverage keys, permissive non-strict SQLite parameters, route-method fallthrough, full route-table replacement during reload, non-capturing wildcards, non-terminating unhandled rejections, call-through spies, and empty JSON serialization of `Error`. Seven skills include tested assets. A package can be checked using the documented pattern:

cd plugins/bunjs/skills/<name> && bun install && bun test

The Dingo plugin supplies one comprehensive `dingo-developer` skill for `.dingo` code transpiled to Go. It covers error propagation, Result and Option types, enums, pattern matching, guard-let, lambdas, safe field navigation, null coalescing, ternaries, tuples, and generics. It also includes code-review rules, anti-patterns, feature combinations, Go interoperability boundaries, and migration guidance. Documented constraints include: `guard` accepts Result/Option rather than booleans; `?.` supports fields, not method calls; and `??` dereferences pointer types.

5. Project provisioning, statusline, and skill indexing

Enable `setup@magus`, then use `/setup:project` to inspect and provision a repository with appropriate plugins, tools, MCP servers, framework references, and a seeded knowledge base. On an existing repository, first preview changes because provisioning writes settings:

/setup:project --dry-run

Use `--scope user` or `--scope project` to choose where settings are written. The statusline commands are `/setup:statusline-install`, `/setup:statusline-customize`, and `/setup:statusline-uninstall`. Customization selects sections, theme, and bar widths; uninstall removes the adaptive statusline.

Skill indexing is manual and explicit:

/setup:index-skills

It walks skills reachable from the project, writes a browsable Markdown index, and inserts a small deterministic index into `CLAUDE.md`. Entries report per-turn listing cost. This matters because the supplied documentation says Claude Code shares an 8,000-character skill-description budget across installed plugins. Skills marked `disable-model-invocation` avoid automatic listing but must be reached through a command, path, or explicit routing row. Nothing automatically runs the indexer.

The `dev` and Bun documentation explain the same design tradeoff: keep generally important routing skills visible, but hide narrowly used procedures until explicitly requested. In the Bun plugin, `/bunjs:bun` is the visible index and the eight specialist skills are hidden. Do not assume that an unlisted skill will be discovered without a routing entry; the repository’s reported benchmark found no automatic use without one.

6. Semantic navigation and multi-model collaboration

`mnemex@magus` is a dependency plugin rather than a user workflow. When `code-search` or `dev` is enabled, it is auto-installed. The `mnemex` binary must already be on `$PATH`; the plugin automatically sets `MNEMEX_LSP=true`. Its MCP server exposes structural navigation (`callers`, `callees`, `define`, `references`, `symbol`, `context`, `hover`), indexing (`index_codebase`, `reindex`, `index_status`, `clear_index`), edits (`edit_lines`, `edit_symbol`, `rename_symbol`, `restore_edit`), analysis (`dead_code`, `impact`, `map`, `test_gaps`), memory operations, and semantic/code search. The main catalog describes `code-search` as read-only investigation through `code-search:analyze` and the `code-search`, `investigate`, and `deep-analysis` skills; advanced call-graph tools appear only when the configured engine supports them.

`multimodel@magus` runs independent external-model work through Claudish:

/multimodel:team Review the auth implementation
/multimodel:delegate grok implement rate limiting
/multimodel:delegate gemini /dev:architect design the payment service

`team` runs blind parallel APPROVE/REJECT voting and aggregates verdicts. `delegate` gives one external model a full Claude Code session and relays its questions interactively. Supporting skills cover agent coordination, validation, complexity routing, phased orchestration, quality gates, and error recovery.

Model names must resolve from Claudish’s live catalog through `list_models` or `search_models`; use bare IDs or families such as `grok`, `gemini`, or `gpt`, without provider prefixes. Read `claudish:claudish-usage` before Claudish work. Workflows use MCP tools such as `team`, `create_session`, and `run_prompt`, not shell calls to run models.

7. Claudish runtime and visual design workflows

Claudish is the shared MCP runtime for `code-search`, `dev`, `multimodel`, and `designer`. Install its external binary exactly as documented:

npm install -g claudish

Credentials may come from the environment, Claudish configuration, macOS Keychain, or 1Password. The plugin exposes low-level tools (`run_prompt`, `list_models`, `search_models`, `compare_models`), agentic tools (`team`, `report_error`), and channel tools (`create_session`, `send_input`, `get_output`, `cancel_session`, `list_sessions`). `CLAUDISH_MCP_TOOLS` can gate the surface to `all`, `low-level`, `agentic`, or `channel`. The CLI is documented only for runtime diagnostics: `claudish --help`, `claudish --version`, and `claudish --models`.

Optional long-session channel events can be enabled with:

claude --dangerously-load-development-channels plugin:claudish@magus

This requires Claude Code v2.1.80+, supported Anthropic authentication, and interactive mode; channels do not register under `-p`.

The Designer plugin provides `/designer:ui`, `/designer:review`, and `/designer:create-style`. Create the style file first if the project lacks a recorded design system. The UI command creates per-screen/per-state HTML/CSS artboards, shared tokens, and a component-reuse list; it can optionally implement and review. Review compares two image files using a local pixel diff, an external vision-model judgment, and detected project review services. With one image it performs usability and WCAG review. Inputs must be local image files, not URLs. If `browser-use@magus` is installed, Designer can capture pages and its own artboards; otherwise provide exported or captured files. If Claudish is unavailable, review falls back locally and labels that fact.

8. Terminal control through tmux-mcp

The Terminal plugin gives Claude controlled helper panes rather than access to the pane you type in. Install the documented dependencies, then enable `terminal@magus`:

brew install tmux
go install github.com/MadAppGang/tmux-mcp/v2@v2.0.0

Debian/Ubuntu may use `apt-get install tmux`. Core commands are:

/terminal:run npm test
/terminal:watch "bun run dev"
/terminal:repl psql $DATABASE_URL
/terminal:tui lazygit

`run` uses an ephemeral isolated TTY. `watch` starts a long-running process in visible slot 1, or an out-of-view slot with `--isolated`. `/terminal:observe [slot] [--watch]` reads without typing or closing. `repl` handles database/language prompts and SQL LIMIT safety. `tui` navigates full-screen applications; `--beside` uses visible slot 1. Manual controls are `/terminal:slots [list | close N | close all]`, `/terminal:snapshot [slot] [--lines N] [--visual]`, `/terminal:send [slot] {text or key:Name}`, and `/terminal:help`.

The `terminal:tui-navigator` agent handles repeated screen-read/keystroke cycles, REPL sessions, servers, deployments, and parallel tests. Five skills document the MCP API, application key patterns, framework signals, TDD state transitions, and workspace layouts. Slots are integer handles owned by the server; Claude cannot read or write an unowned user pane. Outside tmux, only isolated slots work. Snapshots show the visible screen, so long output should use bounded capture, `tail`, files, or query limits.

Troubleshooting checks documented by the source include `which tmux-mcp`, `claude mcp list`, and `echo $TMUX_PANE`. The source also documents `brew install watch` when macOS lacks `watch`.

9. Madbench operation, limits, and safe expectations

`madbench@magus` helps author and run agentic coding benchmarks. It requires the `madbench` harness on `$PATH` and depends on `terminal@magus`. `/madbench:bench` dispatches the `madbench:bench` agent to author, execute, or debug a bench in a visible pane. The agent loads its hidden reference skill, writes or repairs the bench, runs controls, and waits for the real run. `/madbench:doctor` performs three mechanical checks: whether the skill matches the installed harness, whether bench layout is valid, and whether the generated index is current. A Stop hook prevents a parent turn from ending while the dispatched agent is still outstanding, but gives up under documented unreadable, stale, or repeated-block conditions.

The skill covers strict bench YAML, checks, metrics, drive modes, red-state test data, validation, expectation tuning, failure diagnosis, and upstream issue drafting. Always establish controls before interpreting a treatment. The documented negative control is:

madbench check <bench>

It runs checks under the mock harness and requires every check to fail; inspect the tally because a nonzero exit alone does not prove all checks failed. The positive offline check is `madbench grade`. Do not draw conclusions from one treatment/control pair: use `--repeat` and compare rates. A passing treatment and passing control means the benchmark failed to isolate the change.

The required layout is one bench root at the project root, one directory per bench, and a `README.md` with `id`, `question`, `status`, `last_run`, and `binary` frontmatter. Do not place loose TypeScript at a bench root or use alias YAML keys.

Finally, external binaries, model providers, credentials, MCP servers, browser capture, and terminal execution expand the trust surface. Review settings and proposed changes, use setup dry-runs, retain human approval for destructive terminal actions, and treat repository benchmark and performance claims as project-reported rather than independently established.