OpenCanon

Agent-ready. Human-readable. Runtime-enforced.

Agent-ready, human-readable

Project Canon enforced by runtime.

OpenCanon turns conventions, specs, active changes, and project knowledge into local checks that humans can inspect and agents can follow.

Runs locally. Open source. CLI, MCP, hooks, and browser diagnostics.

validator output local runtime
Validator output src/services/company.service.ts
import { db } from "../db/client";  ← service imports db client
 
export class CompanyService {
  constructor(private readonly billing: BillingClient) {}
 
  async deactivate(companyId: string) {
    const row = await db  ← "companies" appears in multiple services
      .from("companies")
      .where({ id: companyId })
      .update({ status: "inactive" });
 
    return row;
  }
}
  1. error service-no-db-client src/services/company.service.ts:1

    Services must not import the database client directly. Route persistence through a repository in src/repositories/.

  2. warn repeated-domain-literals src/services/company.service.ts:7

    The literal "companies" is duplicated across services. Extract into the shared domain table registry.

Finding record with code, margin signal, and action details.

Workflow

Live project memory with proof attached.

Keep docs, conventions, specs, changes, checks, and search in one local loop.

Project Canon The enforced project source of truth: Areas, Specs, Changes, conventions, docs, and checks. Keep conventions, specs, changes, docs, and impact surfaces in typed source.
Proof Runtime checks that read project facts and return findings. Run validators, gates, doctor checks, fixtures, and declared task checks against the code.
Knowledge Structured data from source files, such as imports, exports, comments, calls, and literals. Search code, docs, symbols, chunks, related areas, and backlinks through one local index.
Hooks The local service and project runtime that index code, cache derived state, and serve CLI, MCP, hooks, and browser diagnostics. Give Codex, Claude Code, and OpenCode the same scoped feedback humans can inspect.

Runtime

One local service, same result everywhere.

The service starts project runtimes, caches derived state, and serves the CLI, MCP, hooks, and browser diagnostics.

Runtime Loop

One service. Local clients.

Changes become facts. Validators turn facts into findings. The CLI, MCP, hooks, and browser diagnostics read the same local API. The local service and project runtime that index code, cache derived state, and serve CLI, MCP, hooks, and browser diagnostics.

  1. 1 Watch changed files.
  2. 2 Extract and cache facts.
  3. 3 Run validators.
  4. 4 Send findings to CLI, MCP, hooks, and diagnostics.

Feedback

Findings that change agent behavior.

Each finding includes the rule, location, reason, related Project Canon, and optional fix metadata.

  • context loads rules for a path.
  • validate runs the validators in scope.
  • feedback returns agent-ready findings.
local session
sh
opencanon context --files src/services/company.service.ts
opencanon validate --changed
opencanon feedback --changed
Inspect context, validate changes, send findings back.

Install

Install OpenCanon.

Install the runtime once, then run setup in a repository. Agent entry files stay small and point back to the live CLI, MCP, and local API.

nick-vi/opencanon
sh
curl -fsSL https://github.com/nick-vi/opencanon/releases/latest/download/opencanon-install.mjs -o opencanon-install.mjs
node opencanon-install.mjs
rm opencanon-install.mjs
 
opencanon setup --yes --hooks codex
 
opencanon service start
opencanon service status
opencanon project status
opencanon project open

Read the install guide