Skip to content

Latest commit

 

History

History
214 lines (148 loc) · 9.54 KB

README.md

File metadata and controls

214 lines (148 loc) · 9.54 KB
powerglide logo

The CLI coding agent that slides

Zig Build Tests License GitHub Stars

Zig-powered multi-agent harness for extreme coding workflows. Named after the Rae Sremmurd track and its namesake Lamborghini transmission. Built for Barvis 🦀⚡

What is powerglide?

Like a finely tuned transmission at full throttle, powerglide swerves through your codebase with precision, force, and grace. It is the layer between you and a swarm of LLM-driven engineers working in parallel.

Written in Zig 0.15.2, compiled to a single static binary with zero runtime dependencies, and built around one non-negotiable constraint: the agent loop must be reliable enough to run unattended.

The foundation is the Ralph Loop — an explicit 11-state machine that sequences every agent action from task intake through tool execution to verified completion. No implicit flow, no silent exits. Every session terminates with <POWERGLIDE_DONE> or <POWERGLIDE_ERROR>. The loop drives the model; the model does not drive the loop.

$ powerglide run --agent hephaestus --velocity 2.0 "refactor the auth module to use the new session manager"

Core Pillars

  • The Ralph Loop 🔄 — Explicit 11-state machine: idle → load_tasks → pick_task → thinking → tool_call → executing → observing → verify → commit → done. Every step is auditable; every session ends with a deterministic terminal signal.
  • Velocity Control 🚀 — Precision control over agent throughput. delay_ms = 1000 / velocity. Speed up (--velocity 2.0 = 500ms/step) or slow down (--velocity 0.5 = 2000ms/step) without restarting the session. Agents can self-throttle mid-run.
  • Reliable PTYs 💻 — Every tool runs in a real pseudoterminal. Exit codes captured via waitpid with WNOHANG polling and a /proc/<pid>/status fallback — so zig build, pytest, and bash all deliver trustable results to the VERIFY state.
  • Rogue Agent Prevention 🛡️ — Step limits, heartbeat monitoring (30s), circuit breakers for repeated tool calls, and budget tracking. Stuck agents are killed before they accumulate diverged work.
  • Multi-Model Routing 🤖 — Anthropic (Claude), OpenAI, and any OpenAI-compatible endpoint (Ollama, igllama, NVIDIA NIM, Together AI). Fallback chains keep sessions alive through provider outages.
  • MCP Integration 🔌 — Run as an MCP server (powerglide mcp) or connect to external MCP servers as a client. External tools get prefixed names and become first-class tools in the registry.
  • Local LLM Support 🏠 — Pre-configured agents (local, local2b, local4b, local9b) route to the full Qwen3.5 lineup on :8090–:8093 via igllama. No API keys required for offline inference.

Architecture

Module Structure

Module Structure

Swarm Architecture

Swarm Architecture

The Ralph Loop

Ralph Loop

Quick Start

Prerequisites

  • Zig 0.15.2 — mise install zig@0.15.2 or official binaries
  • An API key for your provider (ANTHROPIC_API_KEY or OPENAI_API_KEY), or run igllama locally for a fully offline stack

Build

git clone https://github.com/bkataru/powerglide
cd powerglide
zig build
# Binary at ./zig-out/bin/powerglide

Run

# Verify setup — scans :8090-8099 for local igllama instances
./zig-out/bin/powerglide doctor

# Run a session (cloud)
./zig-out/bin/powerglide run "implement a binary search tree in Zig"

# Run fully locally with Qwen3.5-4B via igllama
igllama api Qwen3.5-4B-Q8_0.gguf --port 8092 --no-think &
./zig-out/bin/powerglide run --agent local4b "describe the orchestrator module"

# Run at double speed
./zig-out/bin/powerglide run --velocity 2.0 "add comprehensive unit tests"

# Open multi-agent TUI dashboard
./zig-out/bin/powerglide tui

Every completed session emits a structured summary:

─────────────────────────────────────────
  Session complete  [done]
  Steps:    9
  Elapsed:  3.4s
  Agent:    local4b  (Qwen3.5-4B-Q8_0.gguf :8092)
  Signal:   <POWERGLIDE_DONE>
─────────────────────────────────────────

CLI Reference

Command Purpose
run Launch a coding agent session
session Manage sessions — list, show, resume, delete, export
agent Manage agent configs — list, add, remove, show
swarm Orchestrate parallel worker swarms
config View and modify global configuration
tools List and test available tools
mcp Start powerglide as an MCP server
tui Launch the multi-panel vxfw dashboard
doctor Run system health checks
version Show version

MCP Integration

powerglide speaks Model Context Protocol natively — as both server and client.

As an MCP Server

powerglide mcp

Exposes all registered tools via JSON-RPC 2.0 over stdin/stdout. Any MCP-compatible client (Claude Desktop, another powerglide instance) can call powerglide tools.

As an MCP Client

Add mcp_servers to ~/.config/powerglide/config.json:

{
  "mcp_servers": [
    {
      "name": "filesystem",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
  ]
}

External tools register as mcp_filesystem_read_file etc. and are indistinguishable from built-in tools to the agent loop.

Local LLM Dogfooding

powerglide ships with igllama integration for fully local inference. See the Showcase for case studies across the full Qwen3.5 lineup — T01–T17 agentic task trials, quantization sensitivity curve (Q4/Q5/Q6/Q8/BF16), throughput benchmarks, and honest per-model pass-rate tables. Key findings: 9B achieves 17/17 at all quantizations, 4B passes 15/17 at Q4, and 2B's sweet spot is Q6 (11/13).

# Start the full Qwen3.5 lineup (Zig-based local inference via igllama)
igllama api Qwen3.5-0.8B-Q8_0.gguf       --port 8090 --no-think &
igllama api Qwen3.5-2B-Q8_0.gguf         --port 8091 --no-think &
igllama api Qwen3.5-4B-Q8_0.gguf         --port 8092 --no-think &
igllama api Qwen3.5-9B-UD-Q4_K_XL.gguf   --port 8093 --no-think &

# Doctor detects all running instances automatically
powerglide doctor
# OK   igllama: running on :8090 (local   — 0.8B-Q8)
# OK   igllama: running on :8091 (local2b — 2B-Q8)
# OK   igllama: running on :8092 (local4b — 4B-Q8)
# OK   igllama: running on :8093 (local9b — 9B-Q4)

# Run T01-T17 agentic trial harness across all four models
zig build trial

# Run quantization sensitivity trial (Q4/Q5/Q6/Q8/BF16 on 2B+9B; BF16-only on 0.8B+4B)
zig build trial-quant

Inspiration

powerglide synthesizes the strongest ideas from the AI coding agent ecosystem:

Project What We Took
oh-my-pi Multi-agent harness: N workers, one orchestrator, file-based coordination
oh-my-opencode Autonomous coding agents as invocable CLI subprocesses
ralph The Ralph Loop pattern: explicit states, explicit done signal
gastown Per-worker workspace isolation, no write conflicts
opencode CLI structure and multi-model routing with fallback chains
loki Tool registry, provider abstraction, session persistence
plandex Plan+execute pattern, diff-based application
goose MCP integration, agent extensibility
crush Terminal UX sensibility, vxfw-based TUI
mem0 Persistent memory layer design
igllama Local GGUF inference, OpenAI-compatible API for Qwen3.5

Documentation

Full docs at bkataru.github.io/powerglide — including Architecture, CLI Reference, Configuration, and the Showcase.

powerglide has been designed and crafted to be wielded by other agents like a potent blade ⚔️, for AI agents working with powerglide programmatically, see AGENTS.md.

License

MIT © bkataru