powerglide CLAUDE.md

Claude Code Guide — powerglide Repository

Build & Test Commands

# Full build
zig build

# Run all tests (including leak checks)
zig build test --summary all

# Health check
./zig-out/bin/powerglide doctor

Repository Guidelines

• Style: Follow idiomatic Zig 0.15.2 patterns. Use std.fs.File.stdout().deprecatedWriter() for I/O.
• Memory: Explicit allocation is required for all data structures. Use unmanaged ArrayList and HashMap where appropriate, passing the allocator to each method.
• Ralph Loop: Respect the 11-state model in src/agent/loop.zig.
• Velocity: Always use the multiplier-based velocity model (delay = 1000 / velocity). CLI flags and config values are f64.

Project-Specific Context

• Supercar Theme: Use technical, high-performance terminology in prose. Avoid generic marketing fluff.
• Commit Format: feat/fix/docs(module): description. Author: bkataru <[email protected]>.

Zine Website

The documentation website is in website/ and built with Zine. To rebuild and deploy:

cd website && zig build
cp -r zig-out/docs/. ../docs/

MCP Module

• src/mcp/server.zig — JSON-RPC 2.0 over stdin/stdout; start with powerglide mcp
• src/mcp/client.zig — subprocess MCP client; connects to external MCP servers
• src/mcp/tool_bridge.zig — converts McpTool → Tool, prefixed mcp_{server}_{tool}
• Config key: mcp_servers array in ~/.config/powerglide/config.json

igllama / Local LLM

Full Qwen3.5 lineup (download with igllama pull unsloth/Qwen3.5-<N>B-GGUF -f <file>):

• :8090 → Qwen3.5-0.8B-Q8_0.gguf (local agent)
• :8091 → Qwen3.5-2B-Q8_0.gguf (local2b agent)
• :8092 → Qwen3.5-4B-Q8_0.gguf (local4b agent)
• :8093 → Qwen3.5-9B-UD-Q4_K_XL.gguf (local9b agent)

Start with: igllama api <model> --port <N> --no-think --max-tokens 512 --threads 4 --threads-batch 16 --ctx-size 2048 --mlock

• OpenAIClient.json_mode = true → forces response_format: {"type":"json_object"} for constrained output
• Doctor scans :8090–8099 automatically
• Trial harness: zig build trial — runs T01–T17 × all 4 endpoints
• Quant harness: zig build trial-quant — runs T01–T17 × 16 models: 0.8B-BF16 | 2B (Q4/Q5/Q6/Q8/BF16) | 4B (Q4/Q5/Q6/Q8/BF16) | 9B (Q4/Q5/Q6/Q8/BF16), sequential on :8090
• Bench harness: zig build bench — tokens/sec throughput benchmark, accurate via igllama v0.3.11 usage.completion_tokens
• Ctx harness: zig build ctx — context length sensitivity (2B-Q6 × ctx-size 512/1024/2048/4096 × T01-T17)
• Model filter: ./zig-out/bin/trial-quant 4B-Q4 9B-Q5 — run only specific models