Read in: 🇺🇸 English | 🇧🇷 Português (Brasil)
Dynamic skill + subagent orchestrator for Claude Code — zero session-startup overhead, version integrity on autopilot, human-driven provisioning.
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.
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