Code Director

Human Intent → Verified Execution

Code Director is a research and product blueprint for an vibe-checked AI agent system. It shifts the paradigm from generating more code to trusting generated code.

Every agent on the market is racing to produce more change per minute. The binding constraint, however, is how much change a human can afford to trust per minute. Code Director raises the second number by mechanically discharging most of the reviewer's obligation and honestly naming the remainder.

---

⚡ Installation

Code Director is packaged as an npm CLI tool. You can install it globally directly from the repository:

git clone https://github.com/yasirdora/codedirector.git
cd codedirector/codedirector
npm install -g .

Once installed, you can use the cdir command anywhere.

---

🚀 Quick Usage

The core workflow is driven entirely by the cdir CLI. It maps your repository, enforces scope boundaries, and verifies the agent's work.

Basic Manual Flow:

1. cdir index — builds a structural map of your codebase.
2. cdir lock draft "your prompt" — generates a strict Vibe Check contract.
3. cdir lock check — verifies that an agent didn't modify files outside the contract.
4. cdir report — generates an evidence-based change report after work is complete.

Using it with an AI Agent: Code Director is designed to automatically restrict and verify AI agents. You can plug it into any MCP-compatible agent by attaching its MCP server:

kimi mcp add codedirector -- cdir mcp

For the complete command reference and detailed agent setup, see the CLI Documentation.

---

🧭 The Core Thesis

Code Director operates on two foundational layers:

1. The Intent Layer: Formally detects ambiguity before acting and budgets the human's attention. The system establishes whether it actually understood what the human said before it writes a single line of code.
2. The Verification Layer: Compiles intent into an enforceable contract — an Vibe Check — and reports every outcome with typed evidence.

The human states what must be true. The system finds out whether it is. Every change is reported with explicit, typed evidence: what was Measured, what was Proven, what is merely Asserted, and what remains Unchecked.

🏗️ Repository Architecture

This monorepo contains the three pillars of the Code Director ecosystem, alongside the definitive product blueprints.

📦 Components

• 🛡️ codedirector/: The core CLI package. This contains the scope enforcement mechanisms, the verification engine, and the Vibe Check model.
• 🔬 intent-experiment/: The testbed and evaluation harness. This environment runs the experimental loops for intent clarification, measuring how well the system detects ambiguity and asks clarifying questions.
• 📚 research/: The foundational research dossiers. Includes a deep market landscape study of 16 existing tools and comprehensive academic/open-source technical surveys.

📜 Blueprints

The theoretical and architectural foundations of this project are detailed in the following documents. Every factual claim carries a citation to a source URL.

• 📖 CODE-DIRECTOR-v0.2.md: The definitive v0.2 product blueprint. Merges the intent layer (doc A) with the verification layer (doc B).
• 📄 CODE-DIRECTOR.md: The original v0.1 research and product blueprint.

---

📐 Core Principles

1. Evidence over assertion. Never claim a behavioral outcome without naming how it was checked.
2. The negative space is the contract. Every task carries an explicit KEEP set — what must not change. This is enforced, not encouraged.
3. Format must not manufacture content. No output contract may require a field the evidence cannot fill.
4. Attention is a finite resource. Optimize for confident decisions per unit of human attention.

For detailed instructions on running the tools, reproducing the experiments, or reviewing the market studies, please navigate to the specific README.md files located inside each sub-directory.