helix-agent

Cut Claude Code's token usage by 82–97% — automatically. One MCP server that detects retry loops, compresses screenshots & DOM via local LLM, and auto-selects the optimal model for your GPU.

日本語README: README.ja.md

Token Savings — Real Numbers

"My Max plan 5-hour quota vanished in 19 minutes." — Claude Code users (666+ 👍)

helix-agent tackles the #1 pain point of Claude Code: token waste.

All compression runs on your local GPU via Ollama — zero cloud API cost.

The problem in numbers

A typical Claude Code session burns tokens in ways you don't see (source: 926-session audit):

After 22 turns (average session), that's ~1M+ tokens — most of it overhead.

helix-agent attacks each layer:

• Tool schemas → use defer_loading: true (we document how)
• Screenshots/DOM → vision_compress / dom_compress (97-99% cut)
• Browser actions → agent-browser backend (82-93% cut)
• Retry loops → retry_guard (infinite → 0)
• Routine delegation → local LLM via think ($0 vs ~$0.04/call on Opus)

Who is this for?

What helix-agent does that nothing else does

Why retry_guard?

Claude Code's Opus sometimes gets stuck calling the same tool with identical args when it misreads an error (anthropics/claude-code#41659). A Max plan 5-hour quota can vanish in 19 minutes.

There is no built-in loop detection. The community best practice is "write your own hook". retry_guard packages that hook as a reusable MCP tool.

retry_guard_check(tool_name="navigate", args={"url": "..."})
# → {"loop_detected": true, "repeat_count": 3,
#    "recommendation": "Tool 'navigate' called 3 times with identical args.
#                       Likely stuck in retry loop. Vary args or escalate."}

Three tools, one purpose:

Per-session histories, SHA1-hashed call fingerprints, sliding time window. No LLM required for the guard itself — pure logic, sub-millisecond.

Bundled extras

GPU Auto-Detection & Model Tiers

helix-agent detects your GPU at startup and selects the best model for each task. Works on any NVIDIA GPU from 8GB to 96GB+.

Key finding: gemma4:e2b on 8GB VRAM runs 2.7× faster than 31b with comparable output quality for compression tasks. You don't need a $2,000 GPU to save tokens.

# No configuration needed — just install a model that fits your GPU:
ollama pull gemma4:e2b   # 8GB GPU
ollama pull gemma4:e4b   # 16GB GPU
ollama pull gemma4:26b   # 24GB GPU
ollama pull gemma4:31b   # 48GB+ GPU
# helix-agent picks the right one automatically.

Token savers — screenshot-to-text pipeline

The core idea: never send raw images or HTML to Claude. Compress them locally first.

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│ Screenshot   │────→│ vision_compress  │────→│ ~400 tokens  │
│ (15K tokens) │     │ (local gemma4)   │     │ (text only)  │
└──────────────┘     └─────────────────┘     └──────────────┘

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│ DOM/HTML     │────→│ dom_compress     │────→│ ~500 tokens  │
│ (114K tokens)│     │ (local gemma4)   │     │ (text only)  │
└──────────────┘     └─────────────────┘     └──────────────┘

When computer_use(action="screenshot", analyze=True) is called, the raw image is automatically deleted from the response — Claude only receives the text summary. This happens transparently, no extra configuration needed.

• vision_compress — screenshot → local vision LLM → JSON (page_type, interactive_elements, state_flags). 97% reduction.
• dom_compress — HTML → local LLM → JSON (forms, links, buttons, next_action_candidates). 99% reduction.

Real example (tested on RTX PRO 6000):

Input:  1920×1048 screenshot of X.com (would cost ~15,000 tokens)
Output: "X home feed, Japanese UI, 'For You' tab, post by @Suryansh777
         about Claude Code Resource Bible visible" (~400 tokens)
Saved:  7,362 tokens in one call

Browser automation (v0.12.0)

computer_use routes browser actions through Vercel's agent-browser (Rust/CDP) by default, falling back to helix-pilot → Playwright.

Measured on 50 identical automation flows:

Autonomous screen verification (v0.14.0, NEW)

Claude Code's computer_use normally sends raw screenshots (~15,000 tokens each) back to the model. helix-agent intercepts this:

Action: computer_use(action="click", target="#submit")
  ↓
Verify: computer_use(action="screenshot", analyze=True)
  ↓ (raw image auto-deleted, local gemma4 analyzes)
Result: "Form submitted, success toast visible" (~400 tokens)

The instructions field in the MCP server tells Claude Code to:

1. Always use vision_compress instead of sending raw screenshots
2. Always verify actions with analyze=True screenshots
3. Always run retry_guard_check before repeating any tool call
4. Delegate routine tasks to local LLM via think at $0 cost

This means Claude Code autonomously saves tokens without any user intervention — just connect the MCP server and it works.

Self-evolving memory (v0.14.0, NEW)

Inspired by NousResearch/hermes-agent: helix-agent reviews conversations every N turns using a local LLM and automatically saves reusable skills and insights — at $0 cost.

• Memory nudge: Every 5 turns, gemma4 reviews for saveable preferences/corrections
• Skill auto-generation: Successful task patterns → SKILL.md files (hermes-compatible)
• The agent gets smarter the more you use it — all running locally

4-Layer Code Review Pipeline (v0.15.0, NEW)

Automated multi-LLM code review that catches 100% of issues at ~¥30 ($0.20) total:

Layer 2: gemma4 ReAct review ($0, with web_search + RAG)
  ↓ findings + context
Layer 3: Sonnet 4.6 verification + cross-file analysis (~¥10)
  ↓ merged findings
Layer 4: Opus 4.6 meta-review (~¥5, reads summary only — no source code)
  ↓ final verdict
Codex:   Consultant (P1 issues only, on-demand)

Empirical results (5-model comparison on real codebase):

Key finding: gemma4 + RAG ($0) outperforms Codex GPT-5.3 (~¥50) in code review.

# Daily review (gemma4 only, $0)
code_review(target="src/", skip_sonnet=True)

# Pre-release (gemma4 + Sonnet, ~¥10)
code_review(target="src/", context="payment module")

# P1 emergency (+ Codex consultant)
code_review(target="src/", codex_consult=True)

# Control Codex reasoning depth explicitly
code_review(target="src/", codex_consult=True, codex_effort="xhigh")

Codex reasoning effort control (v0.15.0):

• codex_effort="none|minimal|low|medium|high|xhigh" — overrides Codex reasoning depth
• Default (empty) → high
• Auto-escalation: when the pipeline detects ≥3 P1 issues, Codex is invoked with xhigh automatically (no manual tuning needed)

gemma4 Context Expansion (v0.15.0, NEW)

gemma4 now operates as a 12-tool ReAct agent with external knowledge access:

• web_search — Qdrant RAG search + SearXNG web search
• search_memory — enhanced with source/category filters
• add_memory — auto-categorizes into 9 categories (vtuber/coding/mcp/genai/llm/security/infra/x_ops/job)
• Security: 5 injection defense rules prevent execution of instructions found in search results

Qwen3-VL 32B Vision/OCR (v0.15.0, NEW)

Dedicated vision model for 95%+ OCR accuracy on Japanese text:

Auto-selected for 48GB+ GPUs. Role separation: gemma4 = code/reasoning/RAG, Qwen3-VL = vision/OCR.

Parallel Task Execution (v0.15.1, NEW)

Run multiple tasks simultaneously with automatic model routing:

parallel_tasks(tasks='[
    {"task": "Summarize this code", "type": "summarize", "context": "..."},
    {"task": "Translate to English: ...", "type": "translate"},
    {"task": "Classify these items", "type": "classify"},
    {"task": "Search for best practices", "type": "search"},
    {"task": "Security review", "type": "review", "context": "...code..."}
]')

2-axis automatic model selection — task type × input complexity:

Benchmark (5 tasks simultaneous, clip-bridge 501 lines):

Light tasks (e2b/e4b) run in parallel via asyncio.gather. Heavy tasks (31b+) run sequentially to avoid GPU contention.

Autonomous operations & growth loop (v0.15.0, NEW)

helix-agent ships a scripts-layer automation harness that keeps the agent itself healthy. The audit → dispatch → heal chain runs under Windows Task Scheduler so Claude Code stays on a self-healing substrate.

Delegation & agents

ReAct loop with tool access, context-inheriting sub-agents, background workers, Qdrant shared memory, JSONL tracing, PathGuard safety, OOM auto-fallback.

• think / agent_task / parallel_tasks / fork_task — local LLM delegation
• see / browse / computer_use / vision_compress / dom_compress — vision + browser
• spawn_agent / send_agent_input / wait_agent / list_agents / close_agent — background workers
• dept_search / dept_store — per-department Qdrant (dept_hr/research/design/build/qa, mem0_shared)
• evolving_memory_review / list_learned_skills / get_skill — self-evolving memory
• retry_guard_check / retry_guard_status / retry_guard_reset — loop detection
• code_review — 4-layer review pipeline
• providers / models / config / agent_types — meta

Quick Start

git clone https://github.com/tsunamayo7/helix-agent.git
cd helix-agent
uv sync
ollama pull gemma4:e2b   # 8GB GPU (or e4b/26b/31b for larger GPUs)
uv run python server.py

Add to Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "helix-agent": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/helix-agent", "python", "server.py"]
    }
  }
}

Restart Claude Code. retry_guard_check, vision_compress, and friends are now available.

Japanese users — 日本語ユーザー向け

helix-agent ships opt-in Japanese helpers for Claude Code:

• helix-agent-ja-input — floating input window for Windows that sidesteps the React Ink + IME incompatibility (known issue)
• ja_screen_read (coming in v1.2) — Japanese UI screenshot parsing via PaddleOCR + gemma4

See README.ja.md for details.

Security

Claude Code has documented prompt-injection vulnerabilities
(CVE-2025-59536)
where malicious content in project files can exfiltrate API tokens. helix-agent
ships PathGuard — path allowlists and sanitization — so delegated tools
cannot access sensitive locations outside the workspace. See SECURITY.md.

Not a Claude Code wrapper

helix-agent is an MCP server that Claude Code connects to — it does not
wrap, proxy, or re-host Claude Code or the Anthropic API. Fully compliant with
Anthropic's Terms of Service.

Requirements

• Python 3.12+
• uv
• Ollama + any Gemma 4 model (auto-selected by GPU):
  • 8GB VRAM: ollama pull gemma4:e2b (2.3B effective, 4GB)
  • 16GB VRAM: ollama pull gemma4:e4b (4.5B effective, 6GB)
  • 24GB VRAM: ollama pull gemma4:26b (MoE 3.8B active, 12GB)
  • 48GB+ VRAM: ollama pull gemma4:31b (30.7B dense, 20GB)

Optional:

• Qdrant (shared memory)
• Playwright (browser automation fallback)
• agent-browser (recommended for 82-93% browser token savings)

MCP 3-Primitive Architecture

helix-agent implements all three MCP primitives as defined by Anthropic Academy:

Claude Code (Opus 4.6 — decides what to do)
  │
  ├─ Resources (read-only)
  │   ├─ helix://status       → runtime state, backend, retry-guard stats
  │   ├─ helix://models       → available Ollama/provider models
  │   └─ helix://config       → current configuration
  │
  ├─ Prompts (user-triggered workflows)
  │   ├─ retry_report         → loop detection analysis (Japanese)
  │   ├─ optimize_tokens      → token saving recommendations
  │   └─ setup_guide          → first-run setup walkthrough (Japanese)
  │
  ├─ Tools (27 total)
  │   ├─ retry_guard_check    → is this tool call looping? (pure logic, no LLM)
  │   ├─ vision_compress      → gemma4 vision → ~400-token summary
  │   ├─ dom_compress         → gemma4 text → ~500-token structured extract
  │   ├─ think / agent_task   → ReAct loop with local model
  │   ├─ fork_task            → parent-context inheriting sub-agent
  │   ├─ computer_use / browse → agent-browser → helix-pilot → Playwright
  │   └─ spawn/send/wait/list/close → background agent workers
  │
  └─ Infrastructure
      ├─ Qdrant shared memory
      ├─ JSONL tracing
      ├─ PathGuard path safety
      └─ OOM auto-fallback chain

Contributing

See CONTRIBUTING.md.

Related Projects

• helix-ai-studio — All-in-one AI chat studio with 7 providers, RAG, MCP tools, and pipeline
• helix-pilot — GUI automation MCP server — AI controls Windows desktop via local Vision LLM
• claude-code-codex-agents — MCP bridge to Codex CLI with structured JSONL traces
• helix-sandbox — Secure sandbox MCP server — Docker + Windows Sandbox

License

MIT