OpenExec

Executable engineering judgment for AI coding tools

What Is OpenExec?

Can expert engineering judgment become executable?

Most engineering expertise is tacit. It lives in senior engineers' heads: where to look first, which files not to touch, which tests actually matter, when a shortcut is acceptable, and when a change must stop for human review.

AI coding tools can generate code, but they do not automatically inherit that judgment. Left alone, an agent can read too much, touch the wrong surface, retry unpredictably, skip implicit checks, or leave behind a confident summary instead of evidence.

OpenExec is a deterministic runtime for AI coding tools. It wraps Claude Code, Codex, Gemini CLI, or any OpenAI-compatible API in executable structure: blueprints, scoped tools, quality gates, checkpoints, memory, policy, approvals, and audit trails.

The model still reasons. OpenExec governs the run.

The Thesis

OpenExec treats AI work as an engineering process, not a chat session.

Documentation can explain expert judgment. Checklists can remind people to apply it. OpenExec tries to encode more of that judgment as reusable runtime behavior:

• Blueprints capture repeatable workflows.
• Tool policies limit what an agent can see or change.
• Quality gates make tests, linting, formatting, and review explicit.
• Checkpoints preserve intermediate state for recovery and inspection.
• Memory and skills carry lessons from previous work into future runs.
• Audit trails record what happened, not just what the agent said happened.

That is the product boundary: OpenExec is not the agent. It is the control plane around the agent.

Current Scope

OpenExec is intentionally factual about what exists today and what remains architectural direction.

Shipped or implemented in the repository:

• Single-binary Go runtime with CLI, TUI, embedded web UI, and MCP server surfaces.
• Blueprint execution for staged work such as gather context, implement, lint, test, and review.
• Provider adapters for local AI CLIs and OpenAI-compatible HTTP APIs.
• Context assembly, pruning, skills loading, memory, caching, checkpointing, and predictive loading packages.
• SQLite-backed state, audit, approval, budget, telemetry, and PII scrubbing components.
• SRE-oriented safety primitives including allowlisted infra tools, Terraform plan inspection, and approval gates.

Still maturing:

• End-to-end replay and durable recovery UX.
• Production polish for the web console and operator workflows.
• Organization-wide policy distribution.
• Large-scale distributed agent and backlog coordination.

The direction is ambitious, but the core idea is narrow: make AI execution inspectable, bounded, repeatable, and easier to improve.

How It Works

openexec init          # Configure project (model, settings)
openexec run           # Execute tasks via blueprint pipeline

Execution Flow:
  CLI -> Manager -> Pipeline -> Blueprint Engine -> AI CLI or API Provider
                                    |
                      gather_context -> implement -> lint -> test -> review

Three Execution Modes

Supported Execution Modes

CLI Tools (spawn local subprocess):

API Providers (OpenAI-compatible HTTP API):

Any OpenAI-format API works: Kimi K2.5, Mistral, Ollama, DeepSeek, Together AI, etc. Configure in openexec init or set directly in config:

{
  "execution": {
    "api_provider": "openai_compat",
    "api_base_url": "https://api.moonshot.cn/v1",
    "api_key": "$KIMI_API_KEY",
    "api_model": "moonshot-v1-128k"
  }
}

API mode enables true multi-agent parallel execution with the coordinator pattern.

Features

Core (always on):

• Blueprint Execution: 5-stage pipeline (gather_context -> implement -> lint -> test -> review)
• Multi-Model Support: Claude, Codex, Gemini via CLI; any OpenAI-compatible API via shim
• Deterministic Routing: Task classification (mode, toolset, repo zones, sensitivity)
• Skills System: Load SKILL.md knowledge packages, auto-selected per task, Claude Code compatible
• Context Pruning: Intelligent file selection to reduce token usage

Opt-in (via .openexec/config.json):

• API Provider: Use any OpenAI-format API (Kimi, Mistral, Ollama) instead of CLI tools
• Coordinator Multi-Agent: Frontier model decomposes tasks, workers execute in parallel, coordinator merges
• BitNet Routing: Local 1-bit LLM for enhanced intent classification (auto-downloads model)
• Quality Gates V2: Auto-detects project type (Go/Python/TS/Rust), runs lint/test/format gates
• Checkpointing: Deterministic checkpoints after each stage for crash recovery
• Memory System: Extracts learning patterns from completed stages, injects in future runs
• Predictive Loading: Pre-fetches likely-needed files based on task description
• Caching: Knowledge cache and tool result cache to avoid redundant work

Infrastructure:

• MCP Server: JSON-RPC tool server with read_file, write_file, git_apply_patch, run_shell_command
• SRE Orchestration: Deny-by-default infra tools (Ansible, Salt, SSH, Terraform) compiled from an operator-owned allowlist; TOCTOU-safe saved-plan terraform applies with deterministic destructive-change detection; persistent human approval gate with cross-process sign-off. See docs/SECURITY_MODEL.md for how hallucinations, prompt injection, and log poisoning are contained — and docs/SRE_ORCHESTRATION_ROADMAP.md for the engineering spec
• Web UI: React/Vite dashboard (embedded in binary)
• Terminal UI: Bubble Tea TUI

The Reusability Ecosystem (Three-Tier AI Libraries):

• Tier 1 (Architecture): Standardize layouts, data schemas, and API contracts using blueprints.
• Tier 2 (Functional): Ingest regulatory, compliance, and functional standards dynamically using intent-compiler packs.
• Tier 3 (Code/Implementation): Reuse components and utility snippets instantly via Skills (SKILL.md format).

Opt-in Configuration

{
  "execution": {
    "quality_gates_v2": true,
    "cache_enabled": true,
    "predictive_load": true,
    "memory_enabled": true,
    "checkpoint_enabled": true,
    "bitnet_routing": true,
    "worker_count": 4,
    "api_provider": "openai_compat",
    "api_base_url": "https://api.openai.com/v1",
    "api_key": "$OPENAI_API_KEY",
    "api_model": "gpt-4o",
    "coordinator_model": "gpt-4o",
    "worker_model": "gpt-4o-mini"
  }
}

Quick Start

Prerequisites

Install at least one AI CLI or configure an API provider:

# Option A: Install a CLI tool
npm install -g @anthropic-ai/claude-code   # Claude Code
npm install -g @openai/codex               # Codex (OpenAI)
npm install -g @google/gemini-cli          # Gemini CLI

# Option B: Use any OpenAI-compatible API (no CLI needed)
# Configure during 'openexec init' — works with Kimi, Mistral, Ollama, etc.

Installation

Download the latest binary for your platform, or use the automated script:

curl -sSfL https://openexec.io/install.sh | sh

Usage

openexec init          # Set up project, AI models, and features
openexec wizard        # Define goal, generates INTENT.md
openexec run           # Execute blueprint pipeline
openexec chat          # Conversational mode
openexec doctor        # Verify CLI tools and configuration
openexec skills list   # List loaded skills
openexec knowledge index  # Index project symbols

Project Structure

openexec/
├── cmd/openexec/          # CLI entry point
├── internal/
│   ├── agent/             # Coordinator + worker multi-agent execution
│   ├── blueprint/         # Stage-based execution engine
│   ├── cache/             # Knowledge + tool result caching
│   ├── checkpoint/        # Crash recovery checkpoints
│   ├── cli/               # Cobra commands (init, run, chat, skills, knowledge)
│   ├── context/           # Two-stage context assembly + pruning
│   ├── loop/              # CLI subprocess + API runner execution
│   ├── mcp/               # Model Context Protocol server (JSON-RPC)
│   ├── memory/            # Pattern learning across sessions
│   ├── parallel/          # Parallel blueprint engine
│   ├── predictive/        # File pre-loading
│   ├── quality/           # Lint/test/format gates
│   ├── router/            # Deterministic + BitNet routing
│   ├── skills/            # SKILL.md loading, selection, Claude import
│   └── toolset/           # Toolset definitions and registry
├── pkg/
│   ├── agent/             # AI provider adapters (OpenAI, Anthropic, Gemini)
│   ├── manager/           # Multi-pipeline orchestrator + scheduler
│   └── api/               # HTTP handlers and WebSocket
├── ui/                    # Web UI (React/Vite, embedded in binary)
├── agents/                # Personas, workflows, manifests
└── docs/                  # Documentation

Contributing

See CONTRIBUTING.md for guidelines.

Single-binary AI orchestration. Go + React.