A programmable control plane for AI coding agents. Chitin sits between your agent CLIs (Claude Code, Copilot, Codex, Gemini, OpenClaw) and the system they act on, enforcing deterministic boundaries around probabilistic work.
New here? → GETTING_STARTED.md walks you through picking the right entry point and getting a governed agent running in about 15 minutes.
In biology, chitin is the structural polymer that reinforces soft organisms. In this project, Chitin is the structural layer that reinforces agent runs — boundaries where things could break (destructive commands, missing acceptance criteria, uncorrelated telemetry) get deterministic rules, everywhere else stays flexible.
| Primitive | Governs | Scope | Subcommand |
|---|---|---|---|
| Kernel | what actions are allowed | runtime, per tool call | chitin init, chitin evaluate |
| Gate | whether artifacts meet criteria | pipeline, per stage | chitin gate run, chitin gate list |
| Soul | how the agent reasons | disposition, per session | chitin soul on/off/list/status |
| Session | who's running, for how long | lifecycle + identity | chitin session start/end/rate/wrap |
All four share the philosophy: Chitin enforces structure. Agents supply the intelligence. No primitive tries to out-reason the model; each draws a deterministic boundary that catches the failure modes LLMs have in common (unsafe actions, low-quality artifacts, style drift, uncorrelated events).
Every primitive emits JSONL telemetry to $XDG_STATE_HOME/chitin/
or .chitin/events.jsonl. Every primitive runs fail-closed. Every
primitive can be replaced independently.
# Runtime governance (kernel)
chitin init claude # install agent hooks
chitin evaluate -t Bash -c "rm -rf /" # dry-run policy eval
# Artifact validation (gate)
chitin gate list # built-in gates
chitin gate run planning/check_acceptance_criteria --repo x --issue 1
# Cognitive lenses (soul)
chitin soul list # available archetypes
chitin soul on feynman # activate for this shell
# Governed driver sessions (session)
chitin session wrap claude-code --soul jobs # launch Claude inside a session
chitin session install-shell # adds `cc`, `ccr`, `cs`, `claws`
chitin session rate good --note "shipped" # rate the active sessionSee cmd/chitin/gate.go, cmd/chitin/soul.go, cmd/chitin/session.go
for flag-level help; each subcommand prints a tight --help block.
Agent Driver
| tool call
v
[ Hook ]
| parse env vars
v
[ Normalize ] --(Action)--> [ Invariant Check ]
|
v (violations?)
[ Policy Evaluate ]
|
v (Decision)
+-----+-----+
| |
allow deny
| |
v v
exit 0 exit 2 + JSON
Hook (internal/hook/) -- Reads tool call data from driver-specific environment variables (CLAUDE_HOOK_EVENT_NAME, COPILOT_HOOK_EVENT, etc.) and dispatches to the evaluation pipeline. Read-only actions are fail-open; missing policy files are fail-closed.
Normalize (internal/normalize/) -- Maps each tool call to one of six canonical ActionType values: read, write, exec, git, net, dangerous. Uses the canon package to parse shell commands and classify by tool, flags, and patterns.
Invariant Check (internal/invariant/) -- Runs registered safety invariants before policy evaluation. Invariants cannot be overridden by policy rules; they can only be set to monitor (warn) or off per invariant in chitin.yaml. Built-in invariants include recursive-delete guard, permission escalation detection, network egress restriction, IDE socket access prevention, destructive SQL detection, and dynamic script execution tracking.
Policy Evaluate (internal/policy/) -- Two-phase evaluation against chitin.yaml rules. Phase 1: any matching deny rule blocks (deny always wins). Phase 2: any matching allow rule permits. Phase 3: no match means default deny (fail-closed). Policy mode can be enforce (block) or monitor (warn only).
Event Emit (internal/hook/emit.go) -- Appends every governance decision as a JSON line to .chitin/events.jsonl for telemetry ingestion.
- Go 1.18+
- An AI coding agent: Claude Code, GitHub Copilot, OpenAI Codex, or Google Gemini
From source:
go install github.com/chitinhq/chitin/cmd/chitin@latestOr via the install script:
curl -fsSL https://raw.githubusercontent.com/chitinhq/chitin/main/install.sh | bashInitialize hooks and a starter policy for your agent driver:
chitin init claude # or: copilot, codex, geminiThis writes three files:
.claude/settings.json(or equivalent for your driver) -- hooks configchitin.yaml-- starter policy with deny rules for dangerous ops, protected branches, and secrets.chitin-identity-- agent identity file
Check that everything is wired up:
chitin statusTest how a specific action would be evaluated without executing it:
chitin evaluate -t Bash -c "rm -rf /tmp/data"
# Tool: Bash
# Action: dangerous
# Decision: DENY
# Reason: Dangerous operations require human approvalchitin evaluate -t Bash -c "git status"
# Tool: Bash
# Action: git
# Decision: ALLOWValidate a policy file:
chitin validate chitin.yamlPolicies are defined in chitin.yaml at the project root:
mode: enforce # or "monitor" (warn without blocking)
rules:
- action: dangerous
effect: deny
reason: Dangerous operations require human approval
- action: git
branches: [main, master]
effect: deny
reason: Direct push to protected branch
- action: write
target: ".env"
effect: deny
reason: Secrets files must not be modified by agents
- action: "*"
effect: allow
reason: Default allow for non-restricted actions
invariantModes:
no-network-egress: monitor # warn but don't block
script-execution-tracking: off # disable this checkAction types for rules: read, write, exec, git, net, dangerous, *.
github.com/chitinhq/chitin/canon -- Shell command canonicalization with equivalence digests. Parses raw shell strings into structured, normalized forms. Semantically equivalent commands produce identical digests.
package main
import (
"fmt"
"github.com/chitinhq/chitin/canon"
)
func main() {
// Equivalent commands produce the same canonical form and digest.
cat := canon.ParseOne("cat foo.txt")
head := canon.ParseOne("head foo.txt")
fmt.Println(cat.Tool) // "read"
fmt.Println(head.Tool) // "read"
fmt.Println(cat.Digest == head.Digest) // true
// Tool aliases, flag normalization, and subcommand extraction.
cmd := canon.ParseOne("rg -n pattern src/")
fmt.Println(cmd.Tool) // "grep"
fmt.Println(cmd.Args) // [pattern src/]
// Pipeline parsing with chain operators.
pipeline := canon.Parse("git add . && git commit -m 'fix'")
fmt.Println(len(pipeline.Segments)) // 2
fmt.Println(pipeline.Segments[1].Op) // "&&"
// Sensitive values are automatically masked.
secret := canon.ParseOne("curl -H 'Authorization: Bearer sk-longtoken1234567890abcdefghij' http://api.example.com")
// Long token-like args replaced with [MASKED]
}Features:
- 60+ tool aliases (e.g.,
cat/head/tail->read,rg/ag/ack->grep) - Short-to-long flag normalization (
-r->recursive,-i->ignore-case) - Deterministic SHA256 digests (first 16 hex chars) for deduplication
- Chain and pipe parsing (
&&,||,;,|) - Automatic masking of secrets and API keys in arguments
# Build
go build ./cmd/chitin
# Run tests
go test ./...
# Run tests for a specific package
go test ./canon/
# Vet
go vet ./...Chitin is the governance kernel. Other repos in the platform:
| Repo | Role | Start here if you want to… |
|---|---|---|
| chitin (this repo) | Governance kernel — policy, invariants, hooks | Gate an agent you already use |
| shellforge | Local governed agent runtime | Run a governed agent end-to-end |
| octi | Swarm coordinator — triage, dispatch, routing | Orchestrate multiple agents |
| sentinel | Telemetry + detection on agent traces | Analyze how agents fail |
| llmint | Token-economics middleware for LLM providers | Control LLM cost in Go apps |
| atlas | Workspace starter kit — knowledge graphs + LLM-compiled wikis | Wrap your repos in AI-powered knowledge tooling |
See GETTING_STARTED.md for the platform-level entry-point guide.
See LICENSE.