Capability Compiler

Turn any software into an API for AI.

Capability Compiler observes black-box software, explores it safely, and compiles interaction trajectories into verified, reusable capabilities — exposed to any LLM through Python APIs, the cc CLI, and the Model Context Protocol (MCP). Fully local-first: the default configuration runs offline with no account and no telemetry.

UNKNOWN SOFTWARE ─▶ OBSERVE ─▶ EXPLORE ─▶ COMPILE ─▶ VERIFY ─▶ REUSE
                                                                  │
                                          ┌───────────────────────┼───────────────────────┐
                                          ▼                       ▼                       ▼
                                    `cc execute`           `cc serve` (MCP)         Python API

What does this do?

Capability Compiler records how an application responds to actions, classifies those responses with deterministic semantic-state diffs, and turns the result into a typed, versioned, permission-scoped Capability artifact — a unit of reusable software control that any LLM can call via MCP. The output is executable without an LLM in the loop: it carries inputs, preconditions, postconditions, verifiers, and confidence derived from execution evidence.

Why does it exist?

Every adjacent project — record/replay tools, GUI-agent libraries, skill distributors — stops one or two steps short of the full pipeline. Capability Compiler ships the whole pipeline as a compiler, with the properties compilers have: determinism where possible, typed artifacts, reproducible outputs, and versioned inputs/outputs. See docs/research/differentiation.md for the detailed thesis, and docs/research/landscape.md for the ecosystem map that motivated it.

Five differentiators in one line each:

1. Trajectories → parameterized capabilities (not replays, not prompts).
2. Verification manufactured, not hand-written (synthesized from the observed state diffs).
3. Cross-run element re-anchoring (semantic refs survive DOM drift).
4. Trust data attached to executable artifacts (fingerprint, provenance, evidence-based score, deny-by-default permissions).
5. Local-first, offline-complete (mock provider runs the whole pipeline with zero network).

Quick start

# 1. Install (Python 3.11+; MCP transport included by default)
pip install capability-compiler                  # everything except adapters/providers below
pip install capability-compiler[browser]         # add the Playwright adapter
pip install capability-compiler[models]          # add Anthropic / OpenAI / Ollama providers

# 2. Verify the install
cc doctor

# 3. Inspect effective configuration
cc config show

# 4. Learn a capability from a local app (fake adapter, no browser needed)
cc learn "export a pdf" --adapter fake --name export_pdf

# 5. Run it through the gate-ordered executor
cc execute export_pdf --key format=pdf --key file_name=report.pdf

# 6. Browse what you have
cc capabilities
cc inspect export_pdf

# 7. Serve every capability as MCP tools (stdio for editor clients)
cc serve --transport stdio
cc serve --transport http --host 127.0.0.1 --port 8765 --token "$CC_MCP_TOKEN"

Every command supports --json for machine-readable output. Pass --verbose (-v) at the top level to bump logging to DEBUG; set CC_DEBUG=1 to print full tracebacks instead of structured error messages.

Python quick start

import asyncio
from capability_compiler import Compiler, CompilerSettings, CapabilityRegistry

async def main() -> None:
    compiler = Compiler()                    # offline-safe defaults (mock provider)
    async with compiler:                     # connect/disconnect bracket
        observation = await compiler.observe()
        report = await compiler.explore(max_steps=20)
        if compiler.exploration and compiler.exploration.trajectories:
            capability = await compiler.synthesize(
                compiler.exploration.trajectories[-1],
                goal_hint="export a pdf",
            )
            registry = CapabilityRegistry.from_settings(CompilerSettings())
            await registry.save(capability)
            result = await compiler.execute(capability, {"format": "pdf"})
            print(result.status.value, result.duration_ms)

asyncio.run(main())

Architecture summary

The framework is layered so each phase delivers a coherent unit and each later phase builds on a stable contract from the previous one.

The full overview lives at docs/architecture.md. Subsystem deep-dives live in docs/architecture/.

Security posture

Capability Compiler is deny-by-default at every layer:

• security.allow_network and security.allow_shell both default to false.
• allowed_read_roots and allowed_write_roots default to empty lists (filesystem scope is opt-in per capability).
• The browser adapter blocks navigation to non-loopback URLs unless security.allow_network=true; failed navigation becomes a structured PERMISSION_DENIED, never a crash.
• API keys are referenced by env-var name in config; values are resolved at call time and never persisted. The logging layer redacts by key name (api_key, token, secret, password, authorization, cookie, credential, session_id) and by value pattern (Bearer …, sk-…, gh[pousr]_…) as a second line of defense.
• Destructive capabilities (permissions.destructive=true or risk ≥ HIGH) require explicit user confirmation by default; the CLI prompts on a TTY and the executor accepts confirmed=True to skip.
• Capabilities are pure data (JSON-serializable Pydantic models). Nothing in a stored capability is ever evaluated as code.

The complete threat model, scope of promises, and explicit non-goals are in SECURITY.md. Local-first design choices are explained in docs/concepts/local-first.md.

How to contribute / how to extend

Capability Compiler ships pluggable protocols at every cross-cutting boundary; subclasses are not required (Protocols are structural).

The differentiation thesis (docs/research/differentiation.md) is the source of intent — please read it before opening a feature PR. The master plan (docs/master-plan.md) defines what is in scope and what is not. Development setup, test layout, and CI gates are in docs/ci.md.

Benchmarks

Capability Compiler ships an internal CapabilityBench suite used for sanity checks and gate reporting. It runs against the in-memory fake adapter so it never touches the network, a real OS, or a browser. See docs/benchmarks.md for what is and isn't measured.

Documentation index

• Concepts — docs/concepts/exploration.md, docs/concepts/local-first.md
• Architecture — docs/architecture.md, docs/architecture/registry.md, docs/architecture/mcp.md
• Adapters — docs/adapters/browser.md
• Model providers — docs/models.md
• CLI reference — docs/cli/commands.md
• Benchmarks — docs/benchmarks.md
• CI / cc doctor — docs/ci.md
• Research — docs/research/landscape.md, docs/research/differentiation.md

License

MIT — see LICENSE.

Acknowledgments

Capability Compiler stands on the shoulders of projects whose work the docs/research/landscape.md map credits in detail. The full production-readiness release was authored by the Capability Compiler contributors; see CHANGELOG.md for what shipped in each phase.