fakoli-claw

fakoli-claw

The Fakoli plugin suite, ported to OpenClaw — a local-first, tier-routed multi-agent coding crew.

fakoli-claw brings the Fakoli style — a crew of specialist AI agents driven by intent, evidence, and durable state — to the OpenClaw runtime. High-volume specialist work runs on your own GPU through an OpenAI-compatible endpoint (SGLang / vLLM / Ollama); planning and review route to a frontier model. The split is pure config and trivially re-tunable.

What's inside

• The crew — 9 agents installed as OpenClaw agents.list[]: fakoli-orchestrator + 8 specialists (guido architect, critic reviewer, scout researcher, smith plugin-eng, welder integration, herald docs, keeper infra, sentinel QA).
• The wave engine — the orchestrator dispatches specialists in parallel waves via sessions_spawn + sessions_yield, runs a critic gate after every code wave (it re-runs the verify commands — evidence over claim), and finishes with a sentinel evidence scorecard.
• The flow pipeline — six OpenClaw skills: flow-brainstorm → flow-plan → flow-execute → flow-verify → flow-finish (+ flow-quick fast path).
• The router — fakoli-claw-router, a description-triggered skill installed on every agent: it decides when a request stays native vs. enters a flow:*, and tells a specialist mid-packet to stand down rather than re-route. See docs/ROUTING.md.
• Durable state — the fakoli-state FastMCP server (22 tools) exposes the PRD → plan → review → claim → apply lifecycle as MCP tool calls, backed by SQLite.
• Style — style-ops maintains the operating-model principles ledger.
• Plugin shell — index.ts registers the /crew and /flow menu commands + a SessionStart context banner.

Tier routing (default)

| Tier | Model | Agents | |---|---|---| | Cloud (quality-critical) | openai/gpt-5.5 | orchestrator, guido, critic, sentinel | | Local GPU (parallel, high-volume) | sglang/qwen3.6-35b-a3b-local | welder, smith, scout, herald, keeper |

Override per install with FAKOLI_CLOUD_MODEL / FAKOLI_LOCAL_MODEL. See docs/BRING-YOUR-OWN-MODEL.md.

Install

Four moves: serve a model, fix OpenClaw for it, install the crew, run a wave. One command does all of it — see docs/GETTING-STARTED.md for the full walkthrough.

git clone https://github.com/fakoli/fakoli-claw && cd fakoli-claw

# Have a local GPU? Serve a model, fix OpenClaw, install the crew, smoke-test it:
bash setup.sh --serve --model unsloth/Qwen3.6-35B-A3B-NVFP4

# No GPU? Point at any OpenAI-compatible endpoint you already run:
bash setup.sh --provider-url http://localhost:30000/v1 --served-name my-local-model

Or run the steps yourself:

bash scripts/sglang-serve.sh up         # 1. serve a model in Docker (configurable; `down` frees the GPU for gaming)
bash scripts/openclaw-bootstrap.sh      # 2. fix OpenClaw for small local models (compaction + sub-agent caps)
bash scripts/install.sh                 # 3. install the 9-agent crew + flow/style skills, restart gateway
bash scripts/install-state.sh           # 4. optional: durable fakoli-state MCP (installs uv)

sglang-serve.sh runs SGLang with any model/limits (--model/--ctx/--max-running/--mem-fraction/--tp/...; print to dry-run, down to free the GPU). openclaw-bootstrap.sh is a general-audience helper — the compaction fix + sub-agent caps any small-context local model needs on OpenClaw, fakoli or not (--dry-run to preview; backs up + validates config). install.sh runs preflight checks, registers the crew tier-routed, wires the orchestrator's subagents.allowAgents, installs the flow + style skills, then restarts the gateway.

Quickstart — run a wave

# 1. Local tier up? On the GPU host: bash scripts/sglang-serve.sh status
# 2. Write an intent-driven plan (see flow-plan), then hand it to the orchestrator with a fresh session key:
openclaw agent --agent fakoli-orchestrator --session-key agent:fakoli-orchestrator:run1 \
  -m "Execute the plan at /abs/path/plan.md using your wave-engine protocol: parallel sessions_spawn per wave, sessions_yield, a fakoli-critic gate after each code wave, then a fakoli-sentinel evidence scorecard. End with WAVE-OK or WAVE-BLOCKED."

The call returns after the first dispatch — the wave runs asynchronously. The orchestrator spawns specialists (local on SGLang), gates with the critic, and the sentinel writes an evidence scorecard; poll the run's scratch dir for sentinel-final.status. Verify the crew + skills:

openclaw agents list
openclaw skills list --agent fakoli-orchestrator   # flow-*, style-ops show "ready"

Why local models become useful here

Smaller local models are unreliable as lone generalists but strong when work is scoped into tight packets with an evidence loop. fakoli-claw makes that native: each specialist gets only its task (intent + acceptance + scope + verify), and nothing is trusted without re-run evidence.

The compaction gotcha (important): OpenClaw's default reserveTokens floor (20000) is too large for a ~32K-context local model and dead-locks turn-1 compaction. fakoli-claw ships the fix — agents.defaults.compaction.reserveTokens=8192, reserveTokensFloor=0 (global only). See docs/NOTES-compaction.md.

Philosophy — the Fakoli style

Four invariants: intent over recipe, specialist over generalist, evidence over claim, durability over chat.

Status

Crew + wave engine + flow + state + style are live and validated on SGLang (Qwen3.6-35B-A3B) + GPT-5.5. See CHANGELOG.md and docs/.

Documentation

Architecture, internals, the build story, and the framework comparison live in docs/ — start with docs/ARCHITECTURE.md, then docs/THE-BUILD.md and docs/COMPARISON.md. Deciding when to use the crew versus native tools: docs/ROUTING.md. Operating OpenClaw safely with an autonomous crew: docs/HARDENING.md.

Background & further reading

fakoli-claw is the OpenClaw implementation of the Fakoli Style operating model. The "why" behind every design choice here is in the writing — start with

The Fakoli Style: An Operating Model for Building With Agents, then Intent-Driven Flow, crew archetypes, and State Is the Product. Full map of components → essays: docs/BACKGROUND.md. More: sekoudoumbouya.com/writing.

Evals & health

evals/eval-harness.sh scores the crew on deterministic coding tasks (a repeatable per-model number);

evals/health-smoke.sh is a one-shot live-stack check. See evals/README.md.

Credits

By Sekou Doumbouya. Canonical agent prompts: fakoli-plugins. MIT licensed.

Cloud-first (default)

fakoli-claw runs cloud-first by default — the flat-rate OpenAI Pro/OAuth path is primary; the local SGLang tier is optional and on-demand. See docs/CLOUD-FIRST.md for routing, SGLang on-demand (+ remote-start design), and cost-safety guardrails.