Chitin Kernel

The armor that stops your AI coding agent from doing dangerous things.

Chitin Kernel sits between your AI coding agent (Claude Code, Copilot, Codex, Gemini) and your machine. Before the agent runs a command, the kernel checks it against a policy file. Dangerous things are blocked. Everything else passes through.

It is a single Go binary. No daemons, no network calls, no runtime dependencies.

Naming note: "Chitin Platform" is the umbrella project (eight components, modeled on a biological organism). Chitin Kernel — this repo — is the governance component specifically.

What problem does this solve?

AI coding agents are great at writing code and terrible at knowing when to stop. Left alone, they will rm -rf a directory, push to main, commit a .env, or run a shell pipeline that takes down your machine. Chitin Kernel is the deterministic rule-check that catches those cases before the agent executes them.

Rules you write live in chitin.yaml. Violations are denied and logged as JSON lines, so you can see what the agent tried to do.

Try it

# Install
go install github.com/chitinhq/chitin/cmd/chitin@latest

# Wire it into your agent of choice
chitin init claude      # or: copilot, codex, gemini

# See what would happen for a given command (no execution)
chitin evaluate -t Bash -c "rm -rf /tmp/data"
# -> Decision: DENY  Reason: Dangerous operations require human approval

chitin evaluate -t Bash -c "git status"
# -> Decision: ALLOW

chitin init writes three files: your agent's hook config, a starter chitin.yaml policy, and a .chitin-identity marker.

A minimal chitin.yaml:

mode: enforce           # or "monitor" to warn without blocking

rules:
  - action: dangerous
    effect: deny
    reason: Dangerous operations require human approval
  - action: git
    branches: [main, master]
    effect: deny
    reason: No direct push to protected branch
  - action: "*"
    effect: allow

Action types: read, write, exec, git, net, dangerous.

How it works, briefly

Agent proposes command
        |
  [ Hook ] reads the tool call
        |
  [ Normalize ] classifies it into one of 6 actions
        |
  [ Invariant check ] runs safety rules that policy cannot override
        |
  [ Policy evaluate ] applies chitin.yaml: deny wins, then allow, else deny
        |
  allow -> exit 0      deny -> exit 2 + JSON event

Every decision is appended as a JSON line to .chitin/events.jsonl. This file is what Sentinel (the telemetry component) reads to detect drift and mine new rules.

Git driver & reusable CI workflow

Install chitin gates as git hooks (pre-commit runs the validate stage, pre-push runs the build stage):

chitin init git              # install .git/hooks/{pre-commit,pre-push}
chitin init git --remove     # uninstall (only touches chitin-owned hooks)
chitin doctor                # reports the git driver alongside AI drivers

Each hook invokes chitin gate stage <stage>, which runs every gate script registered under that stage directory. Hooks exit non-zero — and therefore abort the git operation — when any gate fails. Existing non-chitin hooks are never overwritten.

In CI, call the reusable workflow from any downstream repo:

jobs:
  gate:
    uses: chitinhq/chitin/.github/workflows/chitin-gate.yml@main
    with:
      stage: build   # or design | groom | planning | research | validate

Optional inputs: chitin-version (pin a release tag), working-directory, runs-on.

Research-phase manifest

Before a task is admitted by Octi it passes through a research phase — a source-coding step that produces a research_manifest.json satisfying the contract in internal/research/manifest_schema.json.

The manifest travels with the task through every downstream gate, so those gates can be cheap envelope checks (schema valid? scope fits?) instead of re-inferring intent.

# Write a skeleton the agent can fill in.
chitin research init my-task-id -o research_manifest.json

# After filling fields, seal the contract with a content hash.
chitin research sign research_manifest.json --in-place

# Validate at any time.
chitin research validate research_manifest.json

# Downstream: the embedded has_sources gate picks the manifest up
# automatically from $CHITIN_RESEARCH_MANIFEST, <worktree>/
# research_manifest.json, or the CWD.
chitin gate run research/has_sources --worktree .

See examples/research_manifest_example.json for a signed, valid sample.

Where next

• GETTING_STARTED.md — 15-minute tour, including the other kernel primitives (gate, soul, session).
• Chitin Platform overview — how this kernel fits with Octi (dispatch), Sentinel (telemetry), Atlas (memory), and the rest.
• canon package — standalone Go library that parses shell commands into a canonical form with stable digests. Useful on its own.

Development

go build ./cmd/chitin
go test ./...

Part of the Chitin Platform

The Chitin platform is a cognitive operating system for AI agents, modeled on biological organisms. Each repo owns one biological role. The Chitin Kernel (this repo) is the armor — deterministic governance on every tool call. Other organs:

Repo	Biological role	What it does	Start here if you want to…
chitin (this repo)	Armor	Governance kernel — policy, invariants, hooks	Gate an agent you already use
shellforge	Muscles	Local governed agent runtime / sandboxed execution	Run a governed agent end-to-end
octi	Nervous system	Swarm coordinator — triage, dispatch, routing	Orchestrate multiple agents
sentinel	Senses	Telemetry + detection on agent traces	Analyze how agents fail
llmint	Metabolism	Token-economics middleware for LLM providers	Control LLM cost in Go apps
atlas	Memory	Workspace starter kit — knowledge graphs + LLM-compiled wikis	Wrap your repos in AI-powered knowledge tooling

One-line pitch for the whole platform: SoulForge distills reasoning archetypes. The Cognitive Router assigns the right mind. ShellForge gives it a body. Chitin Kernel determines what it can safely do.

See GETTING_STARTED.md for the platform-level entry-point guide.

License

See LICENSE.