Read in: 🇺🇸 English | 🇧🇷 Português (Brasil)
Dynamic skill + subagent orchestrator for Claude Code — zero session-startup overhead, version integrity on autopilot, human-driven provisioning.
Pre-1.0 stability notice. This plugin is in the
0.x.yseries. Breaking changes can land in minor versions until1.0.0ships. Pin to a specific tag if your automation depends on a particular hook/skill API shape. See CHANGELOG.md for migration notes on every release.
MaxVision eliminates the 15k-token agent overhead in Claude Code 2.1.x by keeping 500+ specialist subagents and 4,000+ skills in an FTS5 catalog and materializing only what each task requires. The orchestrator reads your cheatsheets, audits locally installed components, checks upstream commits, and presents a single approval prompt before dispatching to the right agent with the right skills loaded.
Three guarantees:
- Zero-overhead discovery — BM25 full-text search across 500+ agents and 4,000+ skills. No cumulative agent descriptions in the system prompt; no session-startup overhead.
- Version integrity on autopilot — upstream commit check before every install or update. One-hour cache with
--force-checkbypass. Origin tracked in.maxvision-source.jsonper component. - Human-driven provisioning — single approval prompt (
sim / all / skip-N / none). Updates run before installs. Tier 4 entries require explicit per-line sign-off even in batch mode.
| Skill | Purpose |
|---|---|
orchestrate |
Master entry point — 8-phase flow with clarity gate, multi-task split, lazy-load agents. |
route-task |
FTS5 + BM25 discovery; picks subagent + skills for the task. |
discover-skill |
Lookup missing skills in the curated catalog. |
discover-agent |
BM25/FTS5 lookup for agents by keyword. |
check-version |
Compare local gitCommitSha with upstream (cache 1h, --force-check bypass). |
update-component |
Apply upstream update to a skill or agent. |
install-skill |
Install via sparse-clone, marketplace, synthesis, or antigravity. |
install-agent |
Install agent on-demand (lazy-load model — from_cache, sparse_clone, raw_url). |
uninstall-agent |
Remove a lazy-installed agent (manual only; never auto-invoked). |
audit-local-skills |
Read-only inventory with redundancy detection and budget report. |
synthesize-skill |
Create a custom maxvision-<name> skill from complementary upstream sources. |
refresh-catalog |
Re-fetch upstream metadata for the FTS5 catalog. |
40 commands across 5 categories, all under /maxvision:. Full reference: docs/COMMANDS.md.
| Category | Commands |
|---|---|
| Spec & Planning | spec-phase, discuss-phase, writing-plans, executing-plans, plan-phase |
| Execute & Ship | execute-phase, ship, verify-phase, pr-branch, complete-milestone |
| Review | code-review, pr-review, security-audit, qa, inbox |
| Lifecycle | progress, pause-work, resume-work, cleanup, health, forensics |
| Update | update [--force|--json], check-update [--force|--json] |
/plugin marketplace add produtoramaxvision/maxvision
/plugin install maxvision@maxvision
git clone https://github.com/produtoramaxvision/maxvision.git
claude --plugin-dir ./maxvision# Orchestrate a complex task
/maxvision:orchestrate refactor src/components/Foo.tsx to use shadcn Select and add unit tests
# Plan before coding
/maxvision:plan-phase --phase 2 --interactive
# Ship a completed phase
/maxvision:ship --phase 3
# Check for plugin updates
/maxvision:update --force
For the full guided walkthrough, see docs/QUICKSTART.md.
The orchestrate skill is the multi-domain dispatcher (10 phases P0..P10). It has two activation surfaces:
| Form | What it is | Notes |
|---|---|---|
/maxvision:orchestrate <task> |
Canonical slash command (real) | The only real slash. Always works. Use in scripts, docs, and automations. Resolves through the plugin's commands/ directory. |
| Natural-language mention or trigger phrase | Skill when_to_use auto-activation |
When your prompt matches phrases like "use the best subagent for…", "tarefa complexa: …", "rote essa tarefa", or simply mentions "orchestrate" / "orquestre" in context, Claude reads the skill's when_to_use metadata and invokes orchestrate on its own. See the skill's frontmatter for the full trigger list. |
Note. Plugin slash commands in Claude Code are namespaced — only
/maxvision:orchestrateresolves through the plugin's command resolver. A bare/orchestratetyped in chat is not a real plugin slash command; it works (when it works) only because Claude's main thread recognizes the textual mention and dispatches through skill auto-activation. If you need a guaranteed dispatch in a script or automation, use the namespaced form.
There is no LLM in any plugin hook — auto-activation is driven by the skill's when_to_use metadata and Claude Code's main-thread interpretation, not by a subprocess classifier. Hooks in this plugin are 100% deterministic (regex / JSON / file IO). If you previously relied on a UserPromptSubmit LLM nudge, see the v0.1.1 BREAKING CHANGE notes — the nudge was removed because subprocess hooks cannot inherit Claude Code's OAuth credentials, so the SDK call always failed.
MaxVision ships a Claude Code statusline showing: model · MaxVision state (milestone/status/phase) · directory · context-window progress bar. Composes with the caveman plugin automatically.
Activate by adding one entry to ~/.claude/settings.json:
Linux / macOS:
"statusLine": {
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/maxvision-statusline.sh"
}Windows:
"statusLine": {
"type": "command",
"command": "powershell -ExecutionPolicy Bypass -File \"${CLAUDE_PLUGIN_ROOT}/hooks/maxvision-statusline.ps1\""
}Or run /maxvision:setup-statusline — the auto-install hook writes the correct absolute path for your platform.
Four CLI tools are automatically in your PATH while the plugin is enabled. All validate identifiers against strict regexes before invoking external dependencies — path traversal and shell metacharacters are rejected with rc=2.
maxvision-skills list # list all local skills
maxvision-skills find <keyword> # search catalog + local by keyword
maxvision-skills check [--force] <comp> # version check (cached 1h)
maxvision-skills install <skill-id> # interactive install
maxvision-skills update <component> # interactive update
maxvision-skills audit # redundancy + budget + telemetry report
maxvision-skills search <query> # BM25 ranking against indexed skillsmaxvision-agents list # list installed agents
maxvision-agents find <keyword> # search FTS5 catalog by keyword
maxvision-agents check [--force] <name> # version-check (sidecar vs upstream)
maxvision-agents audit # inventory + 15k-token budget estimate
maxvision-agents search <query> # top-10 BM25 rankingmaxvision-dispatch run <agent> "<task>" [--worktree] [--model=sonnet|opus|haiku]
maxvision-dispatch list # list maxvision-* agents available locally
maxvision-dispatch status # opens `claude agents` UI
maxvision-dispatch attach <session-id>
maxvision-dispatch logs <session-id>maxvision-sources list # sources grouped by tier
maxvision-sources add <github-url> # add new source (autodetect metadata)
maxvision-sources verify <id> # reachability check + FTS5 stats
maxvision-sources rebuild # rebuild FTS5 index from sources
maxvision-sources stats # tier counts + install-method breakdownAdding paths: ["**/*.ts"] to a skill frontmatter makes it undiscoverable in Claude Code ≥ 2.1.84 (upstream bug #49835, open). Workaround: remove the paths: field; encode path-scoping in the description instead. This plugin's validate.yml CI blocks any PR adding paths: to a SKILL.md.
Both must be in PATH for catalog operations and version checks:
- Windows:
winget install GitHub.cli jqlang.jq - macOS:
brew install gh jq - Linux:
apt-get install gh jq/dnf install gh jq
Verify with gh auth status and jq --version.
- Claude Code ≥ 2.0
ghCLI authenticated (gh auth status) — used bycheck-versionandinstall-agentjqin PATH — used by version comparison and JSON parsingnpx(Node ≥ 18) — only for the antigravity install path
- Never installs or updates silently — single approval prompt with
sim / all / skip-N / none. general-purposedispatch is permitted only as Phase 8 fallback with full agent body injection. SetMAXVISION_DISALLOW_GENERAL_PURPOSE=1to opt out.- Max 3–4 subagents in parallel — prevents context pollution.
- Updates run before installs — updates can change resolution of new installs.
- Tier 4 entries require per-line approval even in batch mode.
- No
git pullwithout--ff-only— prevents accidental merges. - No deletion of user-authored files — only files installed by this orchestrator.
See docs/ARCHITECTURE.md for the 8-phase orchestration flow diagram, FTS5 indexing strategy, synthesis pipeline, cache layout, and .maxvision-source.json schema.
Four trust tiers documented in docs/CATALOG-SOURCES.md:
- Tier 1 (Official Anthropic):
anthropics/skills - Tier 2 (Curated premium): Antigravity, Composio, addyosmani, Obra, and others
- Tier 3 (Domain-specific): Trail of Bits, shadcn/ui, Expo, and others
- Tier 4 (Evaluate with caution): High-overlap or unmaintained sources
See CONTRIBUTING.md. Join the community:
| Channel | Best for |
|---|---|
| Discord | Real-time help, orchestration tips, pairing |
| Discussions | Design proposals, async Q&A |
| Issues | Reproducible bugs and concrete feature requests |
Security findings → SECURITY.md — never public issues. OpenSSF Scorecard: securityscorecards.dev.
MaxVision offers premium support, custom skill catalog development, and AI workflow consulting for teams. See docs/COMMERCIAL.md for tiers and pricing. Contact: contato@maxvision.com.br.
See CHANGELOG.md.
MIT — see LICENSE.
Third-party attributions: LICENSES/THIRD-PARTY-NOTICES.md.
© 2026 Produtora MaxVision