Sage Kernel

Sage Kernel

A proof-first, MCP-native engineering operating system for your local machine

One controlled surface where you — and your AI coding agent — inspect any repo, run the full SDLC, and ship with evidence instead of vibes.

[](LICENSE) [](package.json) [](docs/MCPSERVER.md) [](docs/mcp-tools.md) [](docs/RELEASEPROCESS.md) [](package.json)

[Quick start](#-60-second-quick-start) · [How it works](#-how-it-works) · [Capabilities](#-what-it-does) · [Architecture](#-architecture) · [Language support](#-language-support-honest) · [Docs](#-documentation-map)

---

> [!NOTE] > Honest scope, up front. The deep analysis engines (AST code review, SAST + taint, executed coverage) are JavaScript / TypeScript / Node-native. Other languages get profile detection + repository meta-checks with the correct toolchain commands inferred. Sage Kernel is an MCP stdio server — it works inside any MCP-capable client (Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Codex). It is not usable from a non-MCP chatbot. See the [capability matrix](#-language-support-honest).

---

✦ Why Sage Kernel

Modern software work is scattered across a dozen surfaces — terminal commands, agent prompts, QA scripts, templates, security scans, release checks, approval decisions, run history, and docs. Sage Kernel collapses them into one auditable local control plane that a human and an AI agent can drive through the same protocol.

Its defining principle is proof-first: nothing is "done" because a model said so. Every result is backed by a real artifact in a tamper-evident ledger, or it is reported honestly as blocked. No fake green.

  Ask the kernel  ─►  it runs real gates  ─►  it records proof  ─►  you (or your agent) trust the result

---

✦ The system in one picture

Every one of the 140 tools travels the same governed path — policy, approvals, and audit are not optional middleware, they're the only way in:

flowchart TD
    subgraph CLIENT["MCP client — Claude Code · Claude Desktop · Cursor · Windsurf · Codex"]
        H["👤 Human"] ~~~ AI["🤖 AI coding agent"]
    end

    CLIENT -->|"stdio · JSON-RPC"| SRV["apps/mcp-server — server.mjsregisters 140 kernel.* tools with Zod schemas"]
    SRV --> RT["Kernel runtime — callSafe dispatchuniform envelope: {ok, data} / {ok, error}"]

    subgraph GOV["Governance — enforced on every call"]
        POL["Policy engine — packages/policywrite-path + network deny-by-defaultdestructive-command patterns"]
        APR["Approvals ledger — packages/securitysigned · pending / approved / denied"]
        AUD["Audit sink — packages/coreevery call → audit_events"]
    end

    subgraph EXEC["Execution surfaces"]
        TOOLS["Kernel tools — packages/*profile · review · SAST + taint · testing · operate"]
        JOBS["Worker — apps/workerjob queue · retries · schedules"]
        QA["Gates — packages/enforcement + proofproof gate · claim firewall · release checks"]
    end

    RT --> GOV --> EXEC

    EXEC --> DB[("Persistence — packages/dbSQLite default · Postgres opt-injobs · approvals · audit · memory · artifacts")]
    EXEC --> LEDGER[["Proof ledger — .sage-kernel/proof/ledger.jsonlhash-chained · HMAC-anchored · fail-closed verify"]]

    LEDGER -.->|"enforce.proof_gate — no fresh diff-matched proof → blocked_*"| RT

    style CLIENT fill:#1e293b,color:#fff,stroke:#0f172a
    style SRV fill:#312e81,color:#fff,stroke:#1e1b4b
    style GOV fill:#7f1d1d,color:#fff,stroke:#450a0a
    style EXEC fill:#0f766e,color:#fff,stroke:#134e4a
    style LEDGER fill:#7c2d12,color:#fff,stroke:#431407
    style DB fill:#374151,color:#fff,stroke:#111827

---

⚡ 60-second quick start

git clone https://github.com/JasonTeixeira/sage-kernel.git
cd sage-kernel
npm install                 # Node >= 22, zero heavy deps
npm run mcp:smoke           # real client handshake — prints "passed, 140 tools"

# Point it at ANY of your repos and get a real SDLC assessment (read-only):
npm run onboard -- /path/to/your/project

You'll get a one-screen report: detected profile, loop score, review score, security status, required checks, and the top gaps — computed from your repo's actual contents. Your code is never modified.

Wire it into your AI client (permanent)

{
  "mcpServers": {
    "sage-kernel": {
      "command": "node",
      "args": ["apps/mcp-server/src/server.mjs"],
      "cwd": "/absolute/path/to/sage-kernel",
      "env": { "SAGE_PROFILE_ALLOWED_ROOTS": "/Users/you/code:/Users/you/work" }
    }
  }
}

• cwd must be the kernel checkout (it resolves its own DB relative to cwd).
• SAGE_PROFILE_ALLOWED_ROOTS lists the parent dirs the kernel may analyze.
• Full walkthrough: [docs/GETTINGSTARTED.md](docs/GETTINGSTARTED.md).

---

✦ How it works

Sage Kernel runs the same disciplined loop on every task — the order of operations a senior engineer follows, made mechanical and provable.

flowchart LR
    A["① ORIENTprofile.gaps"] --> B["② DEFINE DONEdone.generate"]
    B --> C["③ LOOPoperate / gates"]
    C --> D{"④ PROVEenforce.proof_gate"}
    D -- "no fresh proof" --> C
    D -- "diff-matched passing proof" --> E["⑤ SCOREloop.score"]
    E --> F(("Resultbacked by ledger"))
    style A fill:#0ea5e9,color:#fff,stroke:#0369a1
    style C fill:#6366f1,color:#fff,stroke:#4338ca
    style D fill:#f59e0b,color:#111,stroke:#b45309
    style E fill:#16a34a,color:#fff,stroke:#15803d
    style F fill:#111827,color:#fff,stroke:#000

The guarantee is integrity, not a number: a claim of "done / verified / passing" is only valid when a fresh, diff-matched, passing proof exists in the hash-chained ledger. Otherwise the kernel says blocked_* with a next step. A claim-firewall scans the final answer and rejects unproven success language.

---

✦ What it does

Six tool families, all traveling the governed dispatch path pictured above:

| Capability | What you get | | --- | --- | | Inspect any repo | Detect the project profile, compute a definition-of-done, score health, and surface real gaps — read-only. | | Review & harden | AST-based code review across 5 dimensions; SAST + intra-procedural taint analysis (command injection, eval, path traversal, weak crypto, prototype pollution, SSRF…). | | Test deeply | Impact-mapped test selection, execution-grounded coverage, mutation testing, and stress/chaos matrices. | | Operate autonomously | A self-healing loop that drives a real model to fix failures, prove-or-discard, and re-verify — with typed stop conditions. | | Generate | Production app templates and scaffolds from a machine-readable catalog. | | Govern | Signed approvals, permission boundaries, a tamper-evident audit log, and a local ops dashboard. |

---

✦ Architecture

flowchart TD
    subgraph APPS["apps/"]
      MCP["mcp-serverstdio · 140 tools · contracts"]
      DASH["dashboardlocal ops cockpit"]
      WRK["workerjobs · queue · runs"]
    end
    subgraph PKGS["packages/"]
      CORE["coreruntime · policy · error envelope"]
      AST["astacorn parse + walk"]
      REV["review · securitySAST · taint · supply-chain"]
      TEST["testingimpact · coverage · mutation"]
      PROF["profilesdetection · toolchain"]
      COMP["companionoperate · decompose · drive-goal"]
      PROOF["proofledger · graph · claim-firewall"]
      DBP["dbsqlite · postgres adapters"]
    end
    CAT["catalog/repos · templates · phases"]

    MCP --> CORE --> AST
    CORE --> REV & TEST & PROF & COMP
    REV & TEST & PROF & COMP --> PROOF
    CORE --> DBP
    MCP --> CAT
    DASH --> CORE
    WRK --> CORE

    style APPS fill:#1e3a8a,color:#fff,stroke:#1e1b4b
    style PKGS fill:#0f766e,color:#fff,stroke:#134e4a
    style PROOF fill:#7c2d12,color:#fff,stroke:#431407

| Layer | Path | Responsibility | | --- | --- | --- | | MCP server | apps/mcp-server/ | stdio server, 140-tool manifest, resources, prompts, contracts, smoke tests | | Runtime | packages/core/ | tool dispatch, policy/approval checks, uniform {ok,data}/{ok,error} envelope | | Analysis engines | packages/{ast,review,security,testing,profiles}/ | acorn AST, SAST + taint, coverage, profile detection | | Companion loop | packages/companion/ | operate loop, goal decomposition, autonomous driver, capability registry | | Proof spine | packages/proof/ | hash-chained + HMAC-signed ledger, proof graph, claim-firewall | | Persistence | packages/db/ | SQLite (default) and Postgres adapters, migrate/backup/restore | | Catalog | catalog/ | machine-readable registry of repos, templates, integrations, phases |

Full detail: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) · [docs/RUNTIMEENGINE.md](docs/RUNTIMEENGINE.md)

---

✦ A real interaction

sequenceDiagram
    participant U as You / AI agent
    participant K as Sage Kernel
    participant L as Proof ledger
    U->>K: kernel.profile.gaps { projectPath }
    K-->>U: { ok, profile, confidence, gaps[] }
    U->>K: kernel.operate.run { goal, acceptanceCriteria, files }
    K->>K: run gates concurrently · diagnose · repair · re-verify
    K->>L: record a proof per gate (diff-hashed)
    K-->>U: { ok, status, score, evidenceIds[] }
    U->>K: kernel.enforce.proof_gate
    K->>L: is the current diff backed by a passing proof?
    K-->>U: { allowed: true, proofId }  ← only then is it "done"

Every tool returns a uniform envelope — success is { ok: true, data }, failure is { ok: false, error: { code, kind, message } }. The server never crashes on a bad call; it returns a typed error.

---

✦ Language support (honest)

Sage Kernel detects and scores any project, but analysis depth is JS/TS-native. This matrix sets expectations precisely:

| Capability | JS / TS / Node | Python | Go · Rust · Java · Ruby · PHP · Swift | | --- | :---: | :---: | :---: | | Profile detection + definition-of-done | ✅ deep | ✅ | ✅ | | Loop score · gaps · required checks | ✅ | ✅ meta | ✅ meta | | AST code review (review.quality_score) | ✅ structural | ⚠️ heuristic | ⚠️ meta | | SAST + taint (security.proof) | ✅ AST dataflow | ⚠️ regex rules | ❌ meta only | | Executed coverage / test run | ✅ node --test | ➖ inferred | ➖ inferred | | Toolchain commands | npm | pytest | go test · cargo · mvn … |

Trust the full SDLC depth on Node/TS repos. Treat non-Node output as profile + meta guidance (the kernel labels it honestly via a toolchainNote).

---

✦ Quality, proven

Sage Kernel holds itself to the bar it enforces on others. The proof is reproducible:

npm test                 # full unit suite
npm run release:check    # 78 hard gates, must exit 0
npm run mcp:smoke        # real MCP client handshake
npm run security:scan    # secret scan
npm run publish:ready    # OSS publish-readiness gate

• 140 MCP tools, every one covered by a source-extracted conformance test.
• 78 release gates run on every change (lint, types, contracts, security, coverage, stress, drift, docs).
• Execution-grounded coverage — "tested" means executed, not import-reachable.
• Tamper-evident proof ledger — hash-chained, HMAC-signable, fail-closed verification.
• Adversarially measured security — held-out + freshly-generated corpora, not a tuned 1.0.

Details: [docs/QUALITYRATCHET.md](docs/QUALITYRATCHET.md) · [docs/RELEASEPROCESS.md](docs/RELEASEPROCESS.md)

---

✦ Daily commands

The sage CLI is optional — enable it once with npm link (or call node bin/sage.mjs directly). The npm run commands need no linking.

npm link                           # one-time: makes the `sage` command available

sage daily                         # health, tools, jobs, approvals, next actions
sage audit .                       # repo audit workflow
sage mcp config cursor --json      # generate client config
npm run onboard --           # one-shot SDLC report for any project (no link needed)
npm run engineer:measure           # proof-backed capability scorecard
npm run stress:verify -- --passes 5  # stability / flake detection

Full reference: [docs/USAGE.md](docs/USAGE.md)

---

✦ Drive it from your AI client (slash-command chains)

Once the MCP server is wired into your client (see [Getting Started](docs/GETTING_STARTED.md)), you describe an outcome and the agent calls the right kernel.* tools. To make the common multi-step flows one keystroke, copy the ready-made chains into your client's commands dir:

cp examples/slash-commands/*.md ~/.claude/commands/    # Claude Code (user-scoped)

Each chain names the exact sage-kernel tools (so routing is deterministic) and composes with your other MCP servers (docs, browser, GitHub):

| Command | Chain | Use it to | | --- | --- | --- | | /sk-audit [path] | profile → done → loop score → review → security → top-5 fixes | size up any repo | | /sk-onboard | one-screen SDLC report | first look at a project | | /sk-feature | current docs → implement → tests → review/security on the diff | build a change correctly | | /sk-ship [title] | review → verify → proof gate → open a PR with the evidence attached | merge with evidence, not vibes | | /sk-secure [path] | SAST + taint + supply-chain, ranked by severity | a focused security pass | | /sk-proof | enforce the proof gate on the current diff | confirm work is genuinely backed |

A typical loop: /sk-audit → /sk-feature add X → /sk-ship → /sk-secure. The proof gate in /sk-ship and /sk-proof refuses to bless a diff that isn't backed by a fresh passing proof. Templates: [examples/slash-commands/](examples/slash-commands/).

---

✦ Documentation map

| Start here | Reference | Operate | | --- | --- | --- | | [Getting Started](docs/GETTINGSTARTED.md) | [Architecture](docs/ARCHITECTURE.md) | [Usage Guide](docs/USAGE.md) | | [Install](docs/INSTALL.md) | [MCP Server](docs/MCPSERVER.md) · [Clients](docs/MCPCLIENTS.md) | [Security Model](docs/SECURITYMODEL.md) | | [Using the Kernel](docs/USINGSAGEKERNEL.md) | [MCP Tools](docs/mcp-tools.md) · [Resources](docs/mcp-resources.md) · [Prompts](docs/mcp-prompts.md) | [Persistence](docs/PERSISTENCE.md) | | [Engineering Loop](docs/ENGINEERINGLOOP.md) | [Runtime Engine](docs/RUNTIMEENGINE.md) | [Release Process](docs/RELEASEPROCESS.md) · [Release Proof](docs/RELEASEPROOF.md) | | [Visual Guide](docs/VISUALGUIDE.md) | [Source Repo Policy](docs/source-repo-policy.md) | [Quality Ratchet](docs/QUALITYRATCHET.md) |

Also: [Roadmap](docs/ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Security Policy](SECURITY.md) · [Code of Conduct](CODEOFCONDUCT.md) · [Changelog](CHANGELOG.md)

---

✦ Development

npm install
npm run catalog:validate
npm run mcp:contracts      # regenerate tool contracts from the manifest
npm run release:check      # the full gate suite

Optional Postgres path:

docker compose -f docker-compose.postgres.yml up -d postgres
SAGE_RUN_POSTGRES_TESTS=1 DATABASE_URL=postgresql://sage:sage@127.0.0.1:55432/sage_kernel npm run postgres:integration

---

✦ Status & philosophy

Sage Kernel is production-grade for local, MCP-native engineering workflows on JS/TS/Node projects, and a genuinely useful profile/meta layer for everything else. It is local-first by default; treat public network exposure as a separate hardening project.

It is built on one non-negotiable doctrine: nothing stated, everything proven. No fake green, no scaffolding, no scores that aren't earned.

[Get started →](docs/GETTING_STARTED.md) · Licensed under [MIT](LICENSE)

---

Built by Jason Teixeira — agency.sageideas.dev Part of a proof-driven portfolio: every claim links to an artifact.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JasonTeixeira
• Source: JasonTeixeira/sage-kernel
• License: MIT
• Homepage: https://github.com/JasonTeixeira/sage-kernel#readme

Install and usage instructions live in the source repository linked above.