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. The automatic checks never run your project's code. Compiler and type-checker checks are opt-in for pre-commit and CI. Opcore pairs with Zeroshot: Opcore checks each edit while an agent writes code, and Zeroshot…
The robustness engine for AI coding agents. A local Rust code graph gives an agent repo-wide understanding, a validation gate that runs before an edit lands, and safe symbol-aware edits. Deep on TypeScript, useful on Rust, local and deterministic.
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.
The automatic checks never run your project’s code. Compiler and type-checker checks are opt-in for pre-commit and CI.
Opcore pairs with Zeroshot: Opcore checks each edit while an agent writes code, and Zeroshot has independent agents review the whole change before it lands.
Opcore 0.3.0 is a full rewrite. The graph, inspect, and edit commands are gone. Upgrading from 0.2.x? Follow the migration instructions.
When to use it
Opcore fits when:
Codex or Claude Code edits your repository and you want problems caught during the session, with the file, location, rule, and evidence the agent needs to fix them;
you want the same checks as a pre-commit hook and a CI gate;
your code is JavaScript or TypeScript, Python, Rust, Go, HCL-based infrastructure, Shell, or Protocol Buffers.
It is not:
a test runner, or a replacement for your existing linters and tests. Run it alongside them;
a code search, navigation, or refactoring tool;
available as published binaries for Windows, Linux ARM64, or Intel macOS yet.
Examples
See what Opcore catches
Expand an example below to see the source and finding. Use a disposable Git project, following Getting started. Fast Verify and Project Sense messages below were checked against the current binary; native compiler wording can vary with the installed toolchain.
Fast Verify
Run opcore check --repo . --all to check these examples.
TypeScript: a function with too many parameters
export function total(
a: number,
b: number,
c: number,
d: number,
e: number,
f: number,
) {
return a + b + c + d + e + f;
}
Rule:complexity.max-parameters
function parameters: 6; configured maximum is 5
JavaScript: decision logic crosses the complexity limit
Suppose src/a.ts is a 667-byte module already in the baseline. Adding byte-for-byte identical content as src/b.ts produces:
Rule:sense.duplication.identical_file
duplicate identical file: src/b.ts (2 occurrences, was 1)
The report lists src/b.ts as changed and src/a.ts as the existing occurrence. The default minimum is 256 bytes, so a tiny shared snippet does not trigger this rule.
A TypeScript module grows past its public-interface limit
Suppose src/api.ts already has 20 explicit exports. Adding one more crosses the default boundary:
export const twentyFirstValue = 21;
Rule:sense.interface.module_exports
The finding records before: 20, after: 21, and limit: 20. Unchanged or reduced interface debt does not block. Any increase above the limit does, including a change from 21 to 22 exports.
An important module changes without its registered documentation
Suppose ten modules import src/core.ts, and .opcore.json binds that source to docs/core.md through documentation.bindings. Renaming a public export without updating the document produces:
Rule:sense.documentation.document_not_updated
update the registered document with this source change
Opcore reads only the exact source-to-document binding. It does not guess ownership from filenames or search Markdown for matching words.
Native checks
These opt-in checks also need the project setup and explicit execution authorization described in Providers. The diagnostics below illustrate typical output; exact wording comes from the installed toolchain or checker version.
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 snapshot of your Git changes. They don’t run repository code or change source or 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.
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 # uncommitted changes against HEAD
opcore run pre-commit # all staged source; Sense reports what the commit introduces
opcore run ci --base <base-commit> # the committed tree; Sense reports what changed since the base
opcore run pre-commit --comparison introduced # existing codebases: report only issues this commit introduces
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.
Result
Next step
Clean or allow
The selected checks completed with no findings. Fast unsupported coverage warnings may remain in the report.
Findings or deny
Read the evidence, repair the change, and rerun the same command.
Not checked
No source changes required checking; use check --all for a project check.
Partial
Review the missing Sense coverage. Use --allow-partial only if you accept those gaps.
Unsupported
An explicitly selected provider or capability does not apply; inspect its coverage details.
Incomplete or indeterminate
Resolve the reported setup, capture, or evaluation failure and retry.
--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 follows only local dependencies it can confirm uniquely, so some imports (for example bare Node packages or external Go modules) stay unresolved and show up as partial coverage. The Sense reference lists what each language resolves, the fixed limits, and what each JSON coverage field means.
For generated or vendored trees, add literal repository-relative exclusions such as {"schemaVersion":1,"targets":{"exclude":["generated","vendor"]}}; targets.exclude does not accept globs. See configuration.
Providers
Provider
Checks
Fast
Built-in syntax, hygiene, and code metrics; the default CLI and hook path.
Rust-native
Cargo Check against the selected workspace or package.
Node-native
Project-local TypeScript checking with an npm lockfile.
Python-native
Host Pyright or mypy using the selected Python environment.
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 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.
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.
Ask questions and talk to the team on Discord. 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:
评论