supercharge-ai 0.2.0

Multi-agent framework for Claude Code

Supercharge-AI

Supercharge-AI is a recursive Claude Code orchestrator that improves as it builds. It moves context to markdown, delegates it recursively to workers, allowing a more focused task execution and avoiding information loss during context compaction. Memory agent helps Supercharge to learn from its errors and improve itself over the time.

Inspired by Recursive Language Models (RLM) and Confucius Code Agent (CCA) — recursive self-delegation from RLM, persistent note-taking and hierarchical orchestration from CCA.

Installation

claude plugin install supercharge-ai --plugin-dir ~/.claude/Supercharge-AI

On first session start, the plugin auto-installs uv and the supercharge CLI if missing. Prompts are injected automatically via SessionStart and SubagentStart hooks.

Recommended: After installing, run supercharge init in each project to add the SuperchargeAI @path include to your CLAUDE.md. This ensures Claude Code prioritizes SuperchargeAI methodology over its default patterns.

Architecture

Three-layer system:

1. Orchestrator - Top-level Claude Code session with Task tool for native subagents
2. Agents - Native .claude/agents/*.md for high-level coordination
3. Workers - Claude Agent SDK (Python) for low-level execution

Workers use Agent SDK instead of claude -p for:

• Direct API calls (no subprocess overhead)
• Session resumption across context resets
• Custom tool configurations per agent type
• Recursion depth tracking via environment variables

Commands

supercharge init

Add SuperchargeAI @path include line to the project's CLAUDE.md. Idempotent — skips if already present. Use --project-dir to target a specific project.

supercharge deinit

Remove the SuperchargeAI include line from CLAUDE.md.

supercharge task init <agent_type>

Create a new task workspace. Prints the UUID.

supercharge subtask init <agent_type> <prompt>

Spawn a new Agent SDK worker on a task. Returns JSON {worker_id, result}.

Options:

• --task-uuid UUID — parent task UUID (agents pass this; workers get it from SUPERCHARGE_TASK_UUID env var automatically)
• --model MODEL — model override (sonnet, opus, haiku)

supercharge subtask resume <worker_id> <prompt>

Resume a worker that stopped with Questions. Looks up session from worker file.

Recursion Depth

Workers can spawn sub-workers recursively (RLM-style). A countdown mechanism prevents infinite recursion.

How it works

Two environment variables control depth:

Variable	Set by	Purpose
SUPERCHARGE_MAX_RECURSION_DEPTH	User (settings.json)	Initial budget for the first subtask init call
SUPERCHARGE_RECURSION_REMAINING	CLI (internal)	Countdown passed to each child worker

Heuristic in subtask init:

1. SUPERCHARGE_RECURSION_REMAINING is set → we're inside a worker → use it
2. Not set → we're at the first call (orchestrator/agent level):
   • SUPERCHARGE_MAX_RECURSION_DEPTH is set → use it as initial budget
   • Not set → default to 5

Each subtask init call decrements the remaining count by 1 and passes it to the child via ClaudeAgentOptions(env=...). When remaining reaches 0, the CLI refuses to spawn and returns an error.

Example chain (default 5):

Agent calls subtask init          → remaining=5, child gets 4
  Worker calls subtask init       → remaining=4, child gets 3
    Sub-worker calls subtask init → remaining=3, child gets 2
      ...
        Worker at remaining=0     → CLI refuses: "Max recursion depth reached"

The worker's initial prompt includes its recursion budget so it knows whether it can delegate.

Configuration

Set SUPERCHARGE_MAX_RECURSION_DEPTH in your project's Claude Code settings to override the default:

.claude/settings.json (checked into repo, shared with team):

{
  "env": {
    "SUPERCHARGE_MAX_RECURSION_DEPTH": "3"
  }
}

.claude/settings.local.json (gitignored, personal override):

{
  "env": {
    "SUPERCHARGE_MAX_RECURSION_DEPTH": "8"
  },
  "permissions": {
    "allow": ["..."]
  }
}

The env field in Claude Code settings sets environment variables for the entire session. These propagate through Bash commands and Agent SDK subprocesses automatically.

Precedence (highest wins):

1. SUPERCHARGE_RECURSION_REMAINING (already inside a worker)
2. SUPERCHARGE_MAX_RECURSION_DEPTH (user-configured in settings.json)
3. Default: 5

Fast Model Configuration

SUPERCHARGE_FAST_MODELS controls which models use fast (fire-and-forget) mode. Comma-separated, case-insensitive. When set, replaces the default entirely.

Variable	Default	Example
SUPERCHARGE_FAST_MODELS	haiku	haiku,sonnet

{
  "env": {
    "SUPERCHARGE_FAST_MODELS": "haiku"
  }
}

Set to empty string to disable fast mode for all models.

Agent Types

Agent	Purpose
plan	Decompose requests into structured task lists
code	Implement features, fix bugs, write tests
document	Update documentation to reflect changes
research	Search the web, gather external context
review	Code review of completed work
consistency	Check for contradictions, broken references, duplication
memory	Maintain project and methodology memory

Worker Modes

Model determines mode: opus/sonnet → deep (context file, resume, recursion), haiku → fast (fire-and-forget). See protocol.md for agent-facing details.

Worker Context File

Deep workers get a context file at workers/<worker_id>.md with these sections:

Section	Purpose
Assignment	Pre-filled by CLI. Do not modify.
Progress	Updated as worker works.
Result	Final deliverable. Agent reads this.
Files	Every file created or modified.
Questions	Blocks progress. Agent answers and resumes.
Errors	Problems encountered (not all require stopping).
Memory	Optional. Patterns, gotchas, instruction gaps for the memory agent.

Per-Agent Tool Permissions

Workers get tool access scoped by agent type. Two mechanisms:

1. allowed_tools — coarse filter: which tools a worker can see at all
2. can_use_tool callback — fine-grained: path-based Write/Edit scoping (deep workers only; fast workers don't support callbacks)

Tool allowlists

Agent	Deep worker tools	Fast worker tools
code	Read, Write, Edit, Bash, Glob, Grep	Read, Glob, Grep
plan	Read, Write, Glob, Grep	Read, Glob, Grep
review	Read, Write, Bash, Glob, Grep	Read, Glob, Grep
document	Read, Write, Edit, Glob, Grep	Read, Glob, Grep
research	Read, Write, Glob, Grep, WebSearch, WebFetch	Read, Glob, Grep, WebSearch, WebFetch
consistency	Read, Write, Glob, Grep	Read, Glob, Grep
memory	Read, Write, Edit, Bash, Glob, Grep	Read, Glob, Grep

All deep workers get Write for their context file. The can_use_tool callback then scopes where they can write.

Write scopes (deep workers)

Scope	Agents	Write/Edit allowed
project	code, document	Anywhere in project root
memory	memory	Memory dir + context file
context	plan, review, research, consistency	Context file only

Architectural enforcement

The can_use_tool callback also blocks supercharge task init in Bash for all workers — only the orchestrator creates task workspaces.

Permissions

SuperchargeAI needs three tool calls auto-approved to function without constant permission dialogs:

• Bash(supercharge *) — CLI commands for task/subtask management
• Write(.claude/SuperchargeAI/**) — writing task.md, result.md, notes.md
• Edit(.claude/SuperchargeAI/**) — editing task files (e.g., answering agent questions)

Two independent mechanisms handle this:

Tier 1: PreToolUse Hook (automatic)

The plugin's hooks.json includes a PreToolUse hook that auto-approves SuperchargeAI's own tool calls at runtime. No configuration needed — it activates when the plugin is enabled.

Tool	Condition	Decision
Bash	Command starts with supercharge	Allow
Write/Edit	Path contains /.claude/SuperchargeAI/	Allow
Task	subagent_type starts with supercharge-ai: and prompt contains workspace path	Allow
Task	subagent_type starts with supercharge-ai: but no workspace path	Deny
Anything else	—	Pass-through (normal permission flow)

The Task deny rule enforces that agents always receive a task workspace — preventing accidental invocations without context.

Known limitation: Plugin hooks don't fire in VS Code (Claude Code bug #18547). Use Tier 2 as a workaround.

Tier 2: Settings Permissions (manual, works everywhere)

For VS Code or as a fallback, add static permission entries to ~/.claude/settings.json:

supercharge init --add-permissions

This idempotently adds the three permission entries to your user-level settings. To remove them:

supercharge permissions remove

Tier 2 cannot enforce the Task workspace validation that Tier 1 provides — static settings don't support conditional logic.

Developer Docs

See docs/stack-propagation.md for details on how env vars, context, and identifiers flow through the orchestrator → agent → worker → sub-worker stack.

TODO

• End-to-end integration test
• Path usage metrics, permission denial logging, and dashboard
• OpenCode support
• Codex support