Core documentation

Opcore

Opcore gives coding agents specific feedback while they edit source. Its installed hook checks the current Git changes and returns the file, location, rule, and evidence when something needs repair.

Important

Opcore 0.3.0 is a full rewrite. We narrowed the old graph, search, and editing toolkit to focus on dependable verification during agent work:

• One Rust engine reuses parsed source facts, removing graph databases and repeated snapshot builds from routine checks.
• Feedback follows completed edits, including supported shell and MCP calls, so coverage depends less on tool-specific patch formats.
• Rules use explicit evidence and report coverage gaps; documentation ownership no longer depends on filename mentions.
• Automatic checks never execute project code. Compiler checks are opt-in for pre-commit and CI.

The old graph, inspect, and edit commands are retired. Install @the-open-engine-company/opcore and follow the new setup instructions.

§Examples

export function total(
  a: number,
  b: number,
  c: number,
  d: number,
  e: number,
  f: number,
) {
  return a + b + c + d + e + f;
}

function parameters: 6; configured maximum is 5

const allowed = flags =>
  flags[0] && flags[1] && flags[2] &&
  flags[3] && flags[4] && flags[5] &&
  flags[6] && flags[7] && flags[8] &&
  flags[9] && flags[10];

cyclomatic complexity: 11; configured maximum is 10

def total(a, b, c, d, e, f):
    return a + b + c + d + e + f

function has 6 parameters; configured maximum is 5

fn total(
    a: u8,
    b: u8,
    c: u8,
    d: u8,
    e: u8,
    f: u8,
) -> u8 {
    a + b + c + d + e + f
}

Rust callable has 6 parameters; configured maximum is 5

package metrics

func total(
    a int,
    b int,
    c int,
    d int,
    e int,
    f int,
) int {
    return a + b + c + d + e + f
}

Go callable has 6 function parameters; configured maximum is 5

42

IaC JSON syntax requires an object at the document root

if true; then
  echo ok

Invalid Shell syntax: expected 'fi'

syntax = "proto3";
message Greeting {

Invalid Protobuf syntax near }

import { a } from "./a";
export const b = a + 1;

cycle: src/b.ts -> src/a.ts (2 files)
  witness: src/b.ts -> src/a.ts -> src/b.ts

{"from":"src/b.ts","to":"src/a.ts","kind":"runtime"}

duplicate identical file: src/b.ts (2 occurrences, was 1)

export const twentyFirstValue = 21;

update the registered document with this source change

fn count() -> u32 {
    "one"
}

E0308: mismatched types

const label: string = 42;

Type 'number' is not assignable to type 'string'.

value: str = 1

number is not assignable to str

Open the phone-sized hook diagram

Verify, available as opcore check, checks syntax and source hygiene for JavaScript and TypeScript, Python, Rust, Go, HCL-based infrastructure code, Shell, and Protocol Buffers. JavaScript, TypeScript, Python, Rust, and Go also receive callable size and complexity checks.

Project Sense compares repository relationships with the Git baseline. It reports introduced runtime cycles, exact duplication, growing interface violations, and documentation obligations. Unchanged or reduced baseline debt doesn’t block.

The default checks read a captured Git view and verify that it stayed unchanged. They don’t execute repository code or alter source and Git state. The installed post-edit hook sends Verify and Sense findings back to the agent for repair. Commit hooks and CI provide the final checks.

§Get started

Upgrading from opcore 0.2.x or an Opcore Zero development install? Follow the migration instructions before installing.

The npm release supports Linux x86-64 with glibc 2.39 or newer and Apple silicon macOS. You’ll need Node.js 18 or newer, npm, Bash, and Git. Agent integration requires Codex or Claude.

npm install -g --foreground-scripts @the-open-engine-company/opcore
opcore --version

From a Git project, run:

opcore doctor --repo .
opcore check --repo . --all

The installer sets up every detected agent at user scope, so its hooks apply across that agent’s Git projects. After a Codex install, restart Codex, open /hooks, review the command, and trust it. Doctor checks installed configuration; follow the activation smoke test to verify automatic execution.

If npm skipped lifecycle scripts, run opcore setup. For the CLI without agent integration, use opcore setup --no-hooks; project-local and CI setup also works without an agent installation.

See Getting started for source and archive installs, agent selection, prerequisites, and cleanup. Windows, Linux ARM64, and Intel macOS have no published binaries.

§Workflows

opcore run post-edit                         # current changes against HEAD
opcore run pre-commit                        # full staged Verify and introduced Sense
opcore run ci --base <base-commit>            # full committed Verify and introduced Sense
opcore run pre-commit --comparison introduced # Fast brownfield gate; native needs a safe baseline

Add the pre-commit workflow to your Git hook and require the CI workflow alongside existing tests and linters. Configure the applicable native providers for compiler or type-checker coverage; those runs also require explicit host authorization. The setup guide has recipes.

One root .opcore.json holds shared settings and workflow overrides. Pre-commit can use stricter thresholds or fewer exclusions than post-edit; monorepos can select different native project roots. See Configuration.

Use check or sense to run an individual evaluator. Plain check reports Nothing checked on a clean worktree; check --all checks the current project even when nothing changed. A full check with no source candidates reports Not checked. Recognized source that Fast Verify cannot analyze remains in the report as an unsupported coverage warning without blocking the check.

--advisory makes findings report-only. Fast unsupported coverage is already a non-blocking warning; incomplete evaluation and unacknowledged required Sense coverage still block. Add --json for structured evidence. The getting-started guide explains exit statuses and partial-coverage options.

The examples above show findings in every supported language family.

§Troubleshoot Sense coverage

Sense resolves only uniquely confirmed local dependencies; bare Node packages, missing, dotted, or colliding Python absolute imports, Cargo-configured Rust roots, external Go modules, and HCL/Shell/Protobuf loading semantics remain deliberately unresolved. A one-component Python import does resolve when it has exactly one sibling module or package target. effectivePolicy.importantFanIn is the configured direct-dependent threshold for important modules. Fixed duplicate-analysis limits such as dedup_region_file_limit cannot be raised at runtime. For generated or vendored trees, use literal repository-relative exclusions such as {"schemaVersion":1,"targets":{"exclude":["generated","vendor"]}}; targets.exclude does not accept globs.

In JSON, documentationCoverage.evaluated: false means no qualifying documentation obligation was evaluated, while a registry state of not_read means the registry was not needed for that view. publicSurfaceAuthoritative: false means Opcore could not establish a complete explicit public surface. The fetchable Sense reference has the full resolution table and limits; configuration defines exclusions. Release bundles rewrite these development links to their exact vX.Y documentation archive.

§Providers

Native checks are opt-in. They may execute repository-controlled build scripts, wrappers, or checker plugins with the current account’s access to host files and the network. Their temporary copy doesn’t isolate that execution; automatic hooks always use the default checks. See Provider setup and usage before selecting native profiles.

§Agent Server Protocol

Opcore includes the complete Agent Server Protocol (ASP) v1.0 definition and four check providers. A calling tool supplies exact file contents and grants read access. Each provider returns findings, coverage, and evidence; the calling tool owns the decision and any ASP receipt.

Open the phone-sized ASP diagram

Opcore’s bundled local runner reports allow, deny, or indeterminate for local use. Its result has advisory assurance and doesn’t issue an ASP receipt. Read the protocol definition for integration contracts.

§Documentation and help

Read the development documentation, including the CLI reference, public Rust API, and ASP specification. These pages contain complete static HTML without requiring JavaScript; release bundles point to their exact minor archive. In a source checkout, generate the same site from the Rust definitions:

./scripts/build-docs.sh

Open target/site/index.html in a browser. CI checks the generated site on every pull request and publishes the passing main build to GitHub Pages. Running the local build only writes target/site/.

Report reproducible problems in GitHub Issues. Contributing explains useful report details and the development checks.

Before removing an npm installation, clean up its agent integrations:

opcore uninstall
npm uninstall -g @the-open-engine-company/opcore

Update and removal instructions cover source installs and recovery after an interrupted setup.