What is opensip-cli?

opensip-cli enforces a quality bar that linters can't.

You write the rules. The runner discovers them, runs them across TypeScript / Python / Rust / Go / Java / C/C++ (all in one pass), reports the result, and exits non-zero in CI when the bar is broken.

> opensip fit
  Fitness Checks
  Recipe: default   Checks: 160   Project: ~/work/my-app

  Scanning your codebase for quality, security, and architecture issues.
  ────────────────────────────────────────────────────────────

  ✓ no-console-log              312 files,   0 violations
  ✓ no-circular-imports         312 files,   0 violations
  ✗ no-cross-layer-imports      312 files,   4 violations
  ✓ no-eval                     312 files,   0 violations
  ✓ no-hardcoded-secrets        312 files,   0 violations
  ...

  150 Passed, 1 Failed (4 Errors, 0 Warnings) | Duration 8.1s

Exit code is 0 when nothing broke the bar, non-zero when something did. That's all CI needs.

Why it exists

OpenSIP started from a practical AI-coding problem: agents can write a lot of

plausible code very quickly, but speed without judgment creates dangerous blast

radius. A small, well-intentioned fix can become a wide repo mutation unless the

environment itself controls scope, checks architecture, and demands proof before

trust.

The answer is not better prompts alone. The answer is a governed feedback loop:

document the intent, encode the rules, run the checks, preserve the evidence,

and make violations fail in ways both humans and agents can act on.

opensip-cli is that guardrail layer extracted into a reusable CLI. It does not

call models or autonomously change code. It makes AI-assisted development more

trustworthy by turning architecture, quality rules, graph context, sessions, and

gates into deterministic evidence.

What it does well

— Gitleaks, Semgrep, Ruff, golangci-lint, cargo-deny, Bandit, PMD, Cppcheck,

OSV-Scanner, Trivy, and more — and normalize findings into the same sessions,

report, JSON, and gate path as built-in tools. Pristine init may recommend

language-relevant adapters; it never installs them for you.

context (impact_files, select_tests, get_file_context,

get_context_status), suite run agent-context, and agent recipes give coding

agents deterministic feedback without making the CLI an AI runtime.

What it deliberately isn't

delivery posts SARIF to a compatible endpoint, and optional OpenSIP Cloud

signal sync is key/entitlement-gated; the tool works fully offline.

autonomous code changes. It is built to help humans and agents trust the code

agents produce.

The problem it solves

Every codebase wants a quality bar. The bar is rarely controversial — no console.log in production, circular imports forbidden, cyclomatic complexity capped at 25, cross-layer imports forbidden by the modular monolith. What's controversial is enforcement: every team ends up writing a different bag of bash scripts, ad-hoc Node programs, and awk-pipelines stitched into CI to enforce its own bar. They drift. They aren't shareable. They're invisible to the IDE. They die when the engineer who wrote them changes teams.

The conventional answer is a giant linter. Linters are great at small syntactic patterns, but a poor fit for architectural checks like "no module under packages/cli/ may import from packages/fitness/checks-*" or "every defineCheck must declare at least one tag". They're also language-locked: a polyglot repo wants the same gate model in TypeScript and Python and Go.

OpenSIP CLI is the alternative: a polyglot, plugin-driven check runner that takes a quality bar and turns it into a deterministic exit code. The runner doesn't know what your checks check; it knows how to discover them, run them, score them, render them, and gate on them.

The four loops

opensip-cli ships four first-party tools, all invoked through the same CLI binary. Each answers a different question shape:

fit — fitness checks

The primary loop. "Is the codebase clean?" A check runs once per file and returns violations. Checks compose into recipes; recipes drive CI. Project-local checks live as .mjs files under opensip-cli/fit/checks/; published packs live as npm packages. The whole loop is described in detail in ../10-concepts/01-fitness-loop.md, the spine of this doc set.

sim — simulation scenarios

The second loop, opt-in. "Does it behave correctly under stress?" A scenario simulates a workload — load, chaos — and asserts something about the system under test. Same Tool/Recipe/Engine/Renderer shape as fit.

graph — static call-graph analysis

The third loop. "What is reachable from where?" Builds the project's static

call graph in a staged pipeline and runs built-in rules over it. The graph tool

is a peer of fit: rules are authored with defineRule (mirroring

defineCheck), selected through the same shared recipe substrate, and their

findings land in sessions and the dashboard just like fitness checks. Eleven

rules ship today: six reachability/duplication rules (orphan-subtree,

duplicated-function-body, near-duplicate-function-body,

no-side-effect-path, test-only-reachable, always-throws-branch) plus five

structural rules (large-function, wide-function, high-blast-untested,

cycle, unexpected-coupling).

Per-function metrics — size, fan-out, blast radius, test coverage — are computed

by an engine feature layer and surfaced both as rule findings and in the

dashboard's graph view. Five language adapters ship (TypeScript, Python, Rust,

Go, Java). Has its own baseline-gate flow.

yagni — reduction audit

The fourth loop. "What could we remove safely?" An advisory audit that ranks

evidence-backed reduction candidates — unused config surface, duplicate function

bodies (via graph bodyHash evidence), and future detectors — with confidence,

preservation arguments, and validation steps. Exit code is 0 by default; findings

are recommendations, not gate failures. See ../55-yagni/01-command-reference.md.

The CLI doesn't know what any of these four do internally — they're tools registered against a shared dispatcher. Same model lets future lint, bench, or domain-specific tools slot in without CLI changes. Top-level audit is a reserved host command, not another Tool: it drives the curated built-in suite through the same suite executor used by suite run. For the architecture behind that decoupling, see ../10-concepts/02-tool-plugin-model.md.

Installed security adapters

The same dispatcher can admit opt-in Tool plugins. The shipped external scanner

adapters are intentionally not bundled, but a team that already uses a scanner

can bring it into OpenSIP's evidence loop:

opensip tools install @opensip-cli/tool-gitleaks
opensip gitleaks doctor
opensip gitleaks --json --gate-save

The adapter records a normal session, contributes to the HTML report, supports

the host-owned baseline ratchet, and keeps the raw scanner artifact local and

gitignored. The scanner binary itself remains user-managed. Sixteen adapter

packages ship today across secrets, SAST/structural search, Python/Go/Rust

linting, dependency vulnerabilities, Java analysis, and C/C++ static analysis.

Time to first signal: ~3 minutes

curl -fsSL https://opensip.ai/cli/install.sh | bash
cd your-project
opensip init
opensip fit --recipe example

init detects your project's language(s) and scaffolds an example check and config. fit --recipe example runs that one check to prove the wiring works. From there, edit the example or delete it and write your own.

Where to go next

| If you want to … | Go to … |

|---|---|

| See what real fit / sim / graph / yagni code looks like | Show me each loop |

| Run the first smoke test right now | Quick start |

| Initialize a real repo carefully | Initialize your first repo |

| Learn the vocabulary used across the docs | Vocabulary |

| Understand the runtime layout (what's on disk) | System context |

| See the high-level architecture map | Architecture overview |

| Go deeper on the architecture (contributors) | Mental model → Architecture index |