OpenCanon

Local repo rules

Executable repo conventions for agents.

OpenCanon loads the rules for a repo, runs validators, and returns findings agents can act on.

Install skill View source

Runs locally. Open source. No analytics.

validator output local daemon
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

Rules beside the code they govern.

Keep docs, decisions, validators, and findings in one local loop.

Context The project rules OpenCanon can show to humans and agents. Load the docs, decisions, and validators for a path before an agent edits it.
Validators Structured data from source files, such as imports, exports, comments, calls, and literals. Run typed rules over repository facts. Fixtures pin the behavior.
Findings Actionable results with severity, rule id, file location, and optional fixes. Return severity, location, decision links, and fix metadata.
Hooks A local process that watches the repo, caches facts, runs validators, and serves the CLI, hooks, and UI. Send concise validation output to Codex, Claude Code, and OpenCode after edits.

Runtime

One daemon, same result everywhere.

The daemon watches changes, caches facts, and serves the CLI, hooks, and UI.

Runtime Loop

One daemon. Three clients.

Changes become facts. Validators turn facts into findings. The CLI, hooks, and UI read the same local API. A local process that watches the repo, caches facts, runs validators, and serves the CLI, hooks, and UI.

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

Feedback

Findings agents can act on.

Each finding includes the rule, location, reason, and 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 the skill.

Clone OpenCanon into your agent host's skills directory. The skill includes the CLI, daemon, UI assets, validators, and engine.

nick-vi/opencanon
sh 
npx skills add nick-vi/opencanon --skill opencanon -a codex -y
 
bun .agents/skills/opencanon/scripts/opencanon.ts setup --yes --hooks codex
 
bun run opencanon daemon start
bun run opencanon daemon status
bun run opencanon daemon open

Read the install guide