UltraPlugin v3.0

Master orchestrator for Claude Code. Activates on every session start — no commands needed.

v3 philosophy: guidance, not enforcement. v2 blocked tool calls (Grep, unbounded Read, Edit on code files) via PreToolUse hooks. Because hook events carry no reliable agent identity, subagents were blocked too and fell into infinite re-delegation loops — costing far more tokens than the blocks saved. v3 removes all blocking: token-saving heuristics are injected as advisory guidance, and the model keeps full judgment (including free model choice for subagents).

---

What It Does

Session Start (automatic)

On every session start, UltraPlugin:

1. Detects all installed Claude Code plugins on the machine
2. Recommends missing base plugins and auto-installs them in the background
3. Heals broken plugin install paths (multi-disk, cache drift)
4. Injects usage hints per plugin into systemMessage — Claude knows how to use each one efficiently
5. Maintains an advisory token-guidance block in CLAUDE.md (marked, never touches your own rules)

What it deliberately does NOT do (v3)

• Never blocks Grep / Read / Edit / Write — no PreToolUse enforcement
• Never truncates tool outputs
• Never forces caveman ultra or rewrites other plugins' configs
• Never writes hooks into your user settings.json
• Never restricts which model subagents may use

Plugin Registry

UltraPlugin knows how to configure and route for every plugin in its registry. For unknown plugins (not in the registry), it applies a generic token-saving rule: filter all outputs >2000 chars via ctx_execute sandbox before entering context.

Multi-disk Support

Correctly resolves ~/.claude regardless of which disk the plugin is installed on. Respects CLAUDE_CONFIG_DIR env variable for non-standard Claude installations.

---

Base Plugins (auto-installed)

These are installed automatically in the background on first session if missing. No action needed.

Plugin	Source	What it enables
caveman	github.com/JuliusBrussee/caveman	~75% prose token savings — ultra mode
token-optimizer	github.com/alexgreensh/token-optimizer	Context health monitoring, checkpoints, statusline
obsidian-skills	github.com/kepano/obsidian-skills	Vault ops, markdown, canvas, bases
context-mode	github.com/mksglu/context-mode	Sandbox for large files — zero context injection
local-rag (MCP)	github.com/shinpr/mcp-local-rag	T0 semantic search — chunks never enter context

After background install completes (~60 seconds), restart Claude Code to activate.

---

Recommended Plugins

These are suggested (not forced) if not already installed. UltraPlugin applies token-saving routing rules for them automatically when detected.

Plugin	What it enables
code-simplifier (claude-plugins-official)	Post-edit code cleanup
playwright (claude-plugins-official)	Browser automation with snapshot→ctx_index→ctx_search routing
claude-md-management (claude-plugins-official)	CLAUDE.md lifecycle management
security-guidance (claude-plugins-official)	Security best practices (passive)
firecrawl (claude-plugins-official)	Web scraping with ctx_execute filter
claude-context-optimizer (egorfedorov)	Token usage tracking, waste heatmaps, ROI reports
cc-plugin (TokenRollAI)	Sub-agent architecture against context explosion
token-optimizer-mcp (ooples, MCP server)	Cached/diffed/filtered payloads for repeated reads
claude-token-efficient (drona23, doc only)	CLAUDE.md verbosity rules — alternative to caveman, never auto-installed

Official-marketplace plugins: install via Claude Code → Settings → Plugins. The git-based ones (and the MCP server) can be installed by UltraPlugin itself:

node <ULTRAPLUGIN_HOOK_DIR>/install-deps.js --recommended

---

Self-Update

UltraPlugin keeps itself up to date from this GitHub repo:

• Automatic: every session start spawns a background check against version.json on main. When a newer version exists, it is installed into a new versioned cache folder, installed_plugins.json is repointed, and all old version folders are deleted (locked folders are renamed .obsolete-* and removed next session). You just restart Claude Code.
• On demand: run /ultra-update — Claude confirms and runs update-self.js --force.

Release flow (maintainer): bump version in .claude-plugin/plugin.json and version.json, commit, push to main. All machines pick it up on their next session.

---

Installation

Prerequisites

• Node.js installed and in PATH
• Claude Code desktop app

Option A: GitHub Marketplace (recommended)

1. In Claude Code: Settings → Plugins → Add Marketplace
2. Enter: https://github.com/pedrovinchi1/ultraplugin.git
3. Install and enable ultraplugin from the new marketplace
4. Restart Claude Code
5. On next session start: base dependencies install automatically in background
6. Restart Claude Code again after ~60 seconds

Option B: Manual (ZIP / local folder)

Works even when the plugin ZIP is on a different disk than Claude (e.g. plugin on D:, Claude on C:).

1. Extract the UltraPlugin folder anywhere on your machine
2. Open %USERPROFILE%\.claude\plugins\known_marketplaces.json and add:

   "ultraplugin": {
     "source": { "source": "local", "path": "C:\\path\\to\\UltraPlugin" },
     "installLocation": "%USERPROFILE%\\.claude\\plugins\\marketplaces\\local-desktop-app-uploads\\ultraplugin",
     "lastUpdated": "2026-01-01T00:00:00.000Z"
   }

3. Copy UltraPlugin folder to:
   • %USERPROFILE%\.claude\plugins\marketplaces\local-desktop-app-uploads\ultraplugin\
   • %USERPROFILE%\.claude\plugins\cache\ultraplugin\ultraplugin\2.0.0\
4. Open %USERPROFILE%\.claude\plugins\installed_plugins.json and add inside "plugins":

   "ultraplugin@local-desktop-app-uploads": [{
     "scope": "user",
     "installPath": "%USERPROFILE%\\.claude\\plugins\\cache\\ultraplugin\\ultraplugin\\2.0.0",
     "version": "2.0.0",
     "installedAt": "2026-01-01T00:00:00.000Z",
     "lastUpdated": "2026-01-01T00:00:00.000Z"
   }]

   And inside "enabledPlugins":

   "ultraplugin@local-desktop-app-uploads": true

5. Restart Claude Code — base deps install automatically in background
6. Restart again after ~60 seconds

Multi-disk note: The paths in steps 3-4 always use %USERPROFILE% (your C: home). The plugin source folder can be on any disk — UltraPlugin never assumes the plugin and Claude are on the same disk.

---

How It Works at Session Start

SessionStart hook fires
  ├── patchClaudeMd → write UltraPlugin rules block to ~/.claude/CLAUDE.md
  ├── applyPluginStandards → fix caveman=ultra, promptCaching=true
  ├── healSettingsHooks → inject caveman/routing/cache-heal hooks if missing
  ├── healPlugins → repair broken installPaths, register orphan cache entries
  ├── read installed_plugins.json
  ├── plugin-registry.analyzeInstalled()
  │     ├── present plugins → collect routing rules per plugin
  │     └── unknown plugins → apply generic output-filter rule
  ├── detect missing BASE plugins → autoInstallBackground() (detached spawn)
  ├── detect missing RECOMMENDED plugins → suggest in systemMessage
  ├── detect Obsidian vault → inject vault name
  └── output systemMessage with all routing rules + status

Claude receives the systemMessage before your first message and routes all tool calls accordingly.

---

Domain Routing Reference

Task	Tool
Find symbol/file (location unknown)	local-rag → cavecrew-investigator
Find symbol/file (file known)	cavecrew-investigator direct
Edit 1–2 files surgically	cavecrew-builder (model: haiku)
Review diff (findings for Claude)	cavecrew-reviewer
Write PR comments (for humans)	caveman-review
Analyze file >500L / logs / DB dump	context-mode ctx_execute_file
Index + repeated search	ctx-index + ctx_search
Compress .md file on disk	caveman-compress
Full token audit	token-optimizer
Quick context health check	token-optimizer:quick
Obsidian vault ops	obsidian-cli
Write/edit Obsidian notes	obsidian-markdown
Extract clean content from URL	defuddle
Browser automation	playwright → snapshot→ctx_index→ctx_search
Scrape web content	firecrawl → ctx_execute filter
Git commit message	caveman-commit
Semantic search	local-rag (T0 — zero context cost)

---

Behavioral Rules (enforced globally)

These rules apply to all sessions, all projects, all users:

Rule	Behavior
Bash execution	NEVER execute directly — output code block for user to run
Checkpoint	Mandatory at every task end before /compact
RAG filter	local-rag results → ctx_execute sandbox → only extracted data enters context
Ingest	Compress .md via caveman-compress BEFORE local-rag ingest
Edit routing	ALL code edits → cavecrew-builder subagent. Hook blocks Edit/Write in main thread
Read limit	Max 100 lines per Read in main thread. Hook blocks unbounded reads
Grep	Blocked in main thread. Use local-rag or cavecrew-investigator

---

Plugin Structure

UltraPlugin/
├── .claude/
│   ├── plugin/
│   │   ├── plugin.json          # Plugin manifest (v2.0.0)
│   │   └── marketplace.json     # Marketplace registration
│   └── settings.local.json      # Local permissions (never committed)
├── skills/
│   └── ultraplugin/
│       └── SKILL.md             # /ultraplugin routing table skill
├── hooks/
│   ├── hooks.json               # Registers Pre/PostToolUse + SessionStart hooks
│   ├── session-start.js         # Auto-detect, auto-install, inject routing rules
│   ├── install-deps.js          # Dependency installer (base plugins + local-rag)
│   ├── pre-tool-use.js          # Blocks Grep/unbounded-Read/Edit in main thread
│   ├── post-tool-use.js         # Truncates tool outputs >2000 chars
│   ├── plugin-registry.js       # Known plugins: tier, fixes, routing rules
│   └── context-mode-cache-heal.mjs  # Auto-heals context-mode installPath on update
├── commands/
│   └── ultra.md                 # /ultra slash command
└── README.md

---

Slash Commands

Command	Description
/ultraplugin	Full routing table, plugin status, anti-collision rules
/ultra	Quick status — active skills and what handles what

---

Updating

Edit files in the UltraPlugin source folder, then copy updated files to both:

• %USERPROFILE%\.claude\plugins\cache\ultraplugin\ultraplugin\2.0.0\
• %USERPROFILE%\.claude\plugins\marketplaces\local-desktop-app-uploads\ultraplugin\

Restart Claude Code to apply.