Sensei is an open-source system designed to provide AI coding agents with the architectural knowledge and governance typically held by senior engineers. It enables agents to consult a queryable graph of invariants, failure modes, forbidden fixes, and intent before making changes, ensuring that modifications align with the project's architectural goals.
Key Features:
Local-first architecture: Rules are defined in YAML within the repository and compiled into a local Oxigraph store, eliminating the need for SaaS or external uploads.
Deterministic closure protocol: Ensures that every change is authorized, scoped, and reproducible, with proofs of compliance captured in an append-only ledger.
CI integration: Enforces architectural integrity by evaluating diffs against governed rules during the CI/CD process.
Compatibility: Works seamlessly with AI tools like Claude Code, Codex, Cursor, and other MCP-compatible agents.
Audience & Benefit:
Ideal for developers, engineering teams, and organizations leveraging AI in software development. Sensei empowers users to maintain architectural consistency while accelerating code changes, ensuring that AI-driven modifications are both compliant and reproducible. It provides a transparent framework for governing AI contributions, reducing risks associated with unintended side effects or architectural drift.
Installable via winget, Sensei offers a robust solution for integrating AI into software development workflows without compromising on quality or governance.
README
Sensei
Executable architecture for AI-driven software change.Make architecture queryable, authority explicit, changes bounded, results reproducible, and proof accountable.
Sensei is an open-source architecture governance system for AI coding agents.
It turns the knowledge scattered across code, tests, documentation, incidents,
pull-request history, and senior engineers' memory into a repository-owned
architectural model that agents can query before they change the system.
That is the starting point.
Sensei is also building a deterministic architectural closure protocol around
probabilistic coding agents. The goal is not merely to help an agent write a
plausible patch. The goal is to determine whether an exact software change was
authorized, stayed inside scope, preserved the applicable architecture, produced
a reproducible result, satisfied its proof obligations, and may legally become
part of the project's history.
agent proposes
↓
Sensei binds identity, scope, direction, and authority
↓
the mutation is admitted and observed
↓
the exact result architecture is rebuilt deterministically
↓
proof requirements are derived and discharged
↓
the transition is recorded
↓
the task may earn architectural closure
> More context can make an agent smarter. It does not make the agent authoritative,
> deterministic, complete, or accountable.
Why Sensei exists
AI coding agents are excellent at producing locally reasonable code.
They do not automatically know:
which source owns a piece of truth
which rule is current, historical, intended, inferred, or contested
who is allowed to change a state
which mutation path is legal
whether a patch matches the operation that was approved
whether generated architecture still describes the post-change repository
whether a clean diff or passing test suite is sufficient
whether a result may become an authoritative project fact
A larger context window helps the model read more of the case. It does not create
the court, the constitution, the evidence rules, or the public record.
Each surface has one job. Sensei refuses to blur them.
What architectural closure means
A task is architecturally closed only when the same declared task and exact
result snapshot satisfy every required dimension.
Dimension
Required truth
Identity
Repository, base revision, result tree, graph, task, session, policies, and artifacts resolve to one consistent world.
Scope
Every read and mutation target is represented, bounded, and associated with the intended architecture.
Direction
The change has an authoritative preserve, evolve, migrate, or not-applicable direction.
Authority
The actor, delegation, owner, action, target, and legal mutation mechanism are valid.
Mutation
The observed result matches the admitted operations and no capability was replayed.
Protection
Applicable invariants, contracts, failure modes, forbidden moves, exceptions, tests, and proof obligations are accounted for.
Epistemic state
Every load-bearing proposition is supported, contradicted, explicitly unknown, or covered by a valid bounded exception.
Proof
Every required proof slot is discharged by compatible, binding-valid, fresh evidence.
Freshness
Generated artifacts, graph state, tests, runtime observations, and evidence still bind the exact result.
Completion
A terminal immutable receipt binds the complete chain and no load-bearing blocker remains.
Closed(task) =
IdentityValid
AND ScopeClosed
AND DirectionResolved
AND AuthorityValid
AND MutationCompliant
AND ProtectionSatisfied
AND EpistemicStateSafe
AND ProofDischarged
AND ResultArtifactsFresh
AND CompletionReceiptValid
A score, model confidence, successful command, clean diff, or passing subset of
tests is never sufficient by itself.
What Sensei provides today
Repository architecture and behavioral memory
Sensei can extract, compile, validate, and query:
components and dependencies
source files and symbols
tests and coverage anchors
contracts and authority surfaces
invariants and failure modes
forbidden fixes
project intent
historical decisions
proof obligations
portable architectural meta-principles
Agent briefings and preflight
Before an agent edits a file or begins a task, Sensei can return:
applicable invariants
known failure modes
forbidden fixes
required tests
relevant contracts
authority information
missing or contested knowledge
risk and impact
MCP, hooks, and editor integration
Sensei works with Claude Code, Codex, Cursor, and other MCP-compatible agents.
It provides:
MCP query tools
a bundled Sensei Architect skill
generated CLAUDE.md and AGENTS.md guidance
Claude Code pre-edit hooks
Cursor rules
a VS Code architecture view
CI governance
Sensei can evaluate a diff against the governed architecture and report or block
violations in GitHub Actions.
Architectural closure program
The closure protocol is being implemented as a fail-closed sequence rather than
a single optimistic verdict:
bindings
→ authority
→ admission
→ observed mutation
→ scope verification
→ proof requirements
→ evidence and certification
→ deterministic result reconstruction
→ recorded result transition
→ terminal completion
→ revocation and migration
The graph, MCP, briefing, extraction, audit, and CI surfaces are usable today.
The terminal architectural-closure lifecycle remains under active development
and is deliberately not represented as complete before its immutable completion
and evolution boundaries exist.
Governed synthesis loop
Alongside deciding whether a change may proceed, Sensei has a bounded,
deterministic loop for producing the change in the first place:
A typed session (golang/architecture/synthesis) drives an external coding
agent through a provider-neutral execution port, snapshots and seals the
result as a candidate artifact, evaluates it deterministically, and only ever
submits an accepted candidate to Sensei's existing admission and verification
owners — never granting the provider architectural, mutation, admission, or
merge authority itself. A rejected or malformed provider output is caught by
the schema/evaluation boundary and stopped, not silently applied.
This is real, merged code, not a proposal — but it is not yet a finished
product surface: it is a Go library
(golang/architecture/synthesisdriver.Run) with no CLI entrypoint yet, and it
can only drive the loop against a repository Sensei has already onboarded
(served graph authority, a task session, and closure state must already
exist). See docs/design/archer-integration-closure.md
for the exact contract, what's merged, and what's still open.
A briefing before an edit
Without governed architecture, an agent may rediscover the same dangerous
shortcut that caused the last incident.
> Agent: "I will set paid = true when the callback arrives."
With Sensei, the agent asks first:
CRITICAL payments.paid_state_requires_processor_confirmation
"paid" is money truth. It must come from the processor's verified
confirmation, never from a local cache or an untrusted callback payload.
Forbidden fix:
trust the local callback payload
Required test:
TestPaidStateRequiresVerifiedConfirmation
> Agent: "I need to verify the processor confirmation through the owner path
> before changing payment state."
Sensei does not make the decision for the agent. It makes the architecture
impossible to ignore quietly.
Install
Prebuilt releases are self-contained and require no Docker or external database.
Linux and macOS
curl -fsSL https://raw.githubusercontent.com/globulario/sensei/main/install.sh | sh
> Before editing, use Sensei to preflight the task and request a briefing for
> every affected file. Obey applicable invariants, forbidden fixes, authority
> boundaries, and required proof.
MCP tools
The MCP bridge exposes the core query and feedback surfaces:
awareness_metadata
awareness_preflight
awareness_briefing
awareness_impact
awareness_resolve
awareness_query
awareness_edit_check
awareness_propose
The generated Sensei Architect skill teaches an agent when to call them and how
to treat absence, uncertainty, contradiction, and authority honestly.
A manual Claude Code MCP configuration looks like this:
enforce fails on blocking findings and fails closed when the diff cannot be verified
Repository policy can re-level or silence rules through
.sensei/gate-policy.yaml.
A real codebase: Caddy
Sensei was tested against a pristine checkout of
Caddy.
It mapped repository structure and recovered architecture laws from project
history, including rules grounded in specific pull requests and reversions rather
than invented from model intuition.
One recovered rule described why a streaming reverse-proxy copy must honor
context cancellation, linking the failure and its correction to the repository's
own history.
A large-context model may read the entire repository, documentation, and history.
That improves candidate extraction and reasoning.
It still does not provide:
authoritative source ownership
legal mutation mechanisms
single-use admission
exact result identity
deterministic reconstruction
complete proof accounting
atomic transition recording
immutable completion
revocation without history rewrite
A model can say, "I found no blocker."
Sensei asks:
Were all mandatory sources consulted?
Was every blocker accounted for?
Did the ledger move during evaluation?
Does the proof bind the exact result?
Was the result independently reproduced?
What makes this transition authoritative?
A stronger model makes Sensei more capable. It does not make the protocol
unnecessary.
Core design laws
Sensei development is governed by a small set of non-negotiable laws:
Base binding and result binding are different objects.
The graph is a compiled projection, not authority by existence.
Task prose, model output, and user role do not create authority.
A verified diff proves scope, not correctness.
An evidence requirement is not an evidence receipt.
Certification is recomputed from records, never accepted from a caller boolean.
Missing, stale, conflicting, or incompatible knowledge never becomes PASS.
Historical receipts are immutable; later invalidation is recorded through revocation, not history rewriting.
These laws matter more than any one model, agent, editor, or storage engine.
Adopt Sensei progressively
Level
Add
Gain
1. One invariant
Protect one dangerous file
The agent receives the rule before editing it
2. One scar
Record one incident and its forbidden fixes
The same failure becomes harder to reintroduce
3. Agent consultation
Enable MCP and the Sensei Architect skill
Agents query architecture before changing code
4. Enforcement hooks
Add pre-edit guards
Consultation becomes enforced behavior
5. CI governance
Add the Sensei GitHub Action
Violating changes are reported or blocked
6. Architecture extraction
Run sensei bootstrap
Components, contracts, symbols, tests, and risks become queryable
7. Governed task protocol
Use bindings, authority, admission, and proof records
Agent work becomes an accountable transition rather than an unstructured patch
8. Architectural closure
Complete the result, proof, completion, and revocation lifecycle
Exact tasks can earn terminal closure under explicit policy
You do not need to model the entire organization before receiving value. Start
with the scar that keeps returning.
Who is this for?
Sensei earns its place when:
AI agents make locally correct but globally dangerous changes
senior engineers repeat the same architectural warnings
important rules live in Slack, post-mortems, and memory
regressions return after team turnover
code review depends on one or two people who know the history
onboarding requires months of repository archaeology
a regulated or critical system needs evidence of why a change was accepted
a large codebase needs agents to operate without silently inventing authority
Sensei is not only for large distributed systems. A single dangerous invariant
in a small repository is enough to justify it.
What Sensei is, and is not
Sensei is not
Sensei is
another code-generation model
a governance and closure protocol around any coding agent
generic RAG over repository text
typed, repository-owned architectural knowledge
a linter with hard-coded rules
a graph of project-specific contracts, scars, authority, and proof
a confidence score
explicit legal states for known, unknown, blocked, certified, and completed
a replacement for tests
a system that derives which tests and evidence are required
a hosted authority service
local, open source, and versioned with the repository
an attempt to make an LLM deterministic
a deterministic acceptance envelope around probabilistic work
Architecture
docs/awareness/*.yaml
code annotations
tests and contracts
approved decisions
│
▼
deterministic extraction + compilation
│
▼
Oxigraph RDF architecture graph
│
├── briefing
├── impact
├── preflight
├── closure assessment
└── proof requirement extraction
│
▼
task protocol and append-only ledger
│
├── identity and scope
├── authority and admission
├── observed mutation
├── deterministic result pipeline
├── evidence and proof
├── certification
└── completion and revocation
The CLI, gRPC server, MCP bridge, hooks, editor extension, and CI action are
interfaces over the same governed model.
No arbitrary SPARQL is exposed to agents. Query modes use closed typed surfaces.
Evaluate repository architecture and awareness quality
sensei audit --domain
Detect graph drift, gaps, and inconsistencies
sensei briefing --file
Return the architecture governing a file
sensei briefing --task ""
Return task-relevant architecture
sensei impact
Return structured affected nodes
sensei preflight
Evaluate risk before a task begins
sensei edit-check
Check proposed content against governed rules
sensei gate --diff
Evaluate a Git diff in CI
sensei rigor --file
Report the proof-rigor class a change owes (governed-surface, fail-closed)
sensei propose --kind ...
Stage a new architectural scar or rule candidate
sensei check
Validate governed source documents
sensei validate
Run deeper structural validation
sensei demo
Start a disposable stack and return a real briefing
Closure-protocol commands are being integrated behind the safe task orchestrator.
Low-level protocol verbs exist for testing and automation, but the intended agent
experience is one bounded next legal action at a time.
The extension reads the local Sensei graph and exposes the architecture governing
the current file plus a project-level architecture dashboard.
Repository layout
cmd/awg/ Sensei CLI
cmd/awareness-mcp/ MCP stdio bridge
cmd/yaml2nt/ governed YAML to N-Triples compiler
golang/server/ gRPC service
golang/extractor/ repository extraction and scanners
golang/architecture/ bindings, claims, closure, ledger, authority,
admission, proof, result pipeline, certification
proto/ gRPC contracts
ontology/ RDF vocabulary
docs/awareness/ governed architectural knowledge
docs/ references, guides, case studies, and design notes
Build and test:
go build ./...
go test ./...
make sensei
make sensei-smoke
Project status
Sensei has two deliberately distinct maturity surfaces.
Usable now
repository extraction
governed architectural knowledge
RDF graph compilation
MCP tools
agent skills and hooks
briefings, impact, preflight, and edit checks
repository evaluation and audit
CI diff governance
editor integration
Active closure work
complete task orchestration
deterministic result-transition recording
proof execution and discharge integration
terminal completion receipts
revocation, migration, and learning lifecycle
self-hosted closure of Sensei changes
Merged, not yet a finished surface
the governed synthesis loop (interpretation, planning, generation,
evaluation, admission, apply) — a real Go library today, with no CLI
entrypoint yet and usable only against a repository Sensei has already
onboarded
Sensei does not call an intermediate result "architecturally closed." The term is
earned only when the exact result, proof, freshness, and immutable completion
boundaries all hold.
Origin
Sensei was born from Globular, a distributed
platform developed with extensive AI-agent assistance.
The agents were productive, but they repeatedly rediscovered architecture
failures:
two components claiming authority over the same truth
stale state presented as current reality
recovery paths depending on the system they must recover
local fixes violating owner boundaries
successful intermediate states presented as completed outcomes
the same incident returning under a different filename
The response was not another prompt file.
The incidents became invariants. The bad fixes became forbidden moves. The real
repairs became required mechanisms. The required confidence became proof
obligations. Their recurring shapes became portable meta-principles.
Sensei grew from memory into governance, and from governance toward closure.
Deciding whether a change may proceed is only half the problem; the other half
is how the change gets produced. For that half, Sensei's governed synthesis
loop (interpretation, planning, generation, evaluation, bounded retry/replan)
acknowledges ARCHER, a research paper on
governed multi-agent code synthesis for regulatory compliance, as the source
of that control-loop pattern. Sensei did not adopt ARCHER's domain-specific
mechanics — its label vocabulary, its accuracy metric, or its compliance
documents are all specific to building-code review and have no analogue here.
What carried over is the shape of the loop itself, composed with an authority
chain ARCHER does not define: a produced candidate is never self-admitting —
it still passes through Sensei's own admission, application, and verification
owners before anything is accepted.
Contributors working on the closure protocol should treat frozen schemas,
fixtures, and design laws as higher authority than convenience or local
implementation shortcuts.
License
GNU Affero General Public License, Version 3 (AGPLv3).
