A uniform surface for your coding agents, with a layer of architectural knowledge underneath.
Sensei Code does not replace Claude Code, Codex, or Cursor Agent. It gives them the context an agent session cannot give itself — the repository's governed invariants, contracts, failure modes, forbidden fixes, and proof obligations — and it makes the task, not the agent session, the unit of continuity.
Switch from one agent to another mid-task and the architectural context, the scope, the decisions already made, and the evidence survive the switch, because they live in Sensei rather than in a transcript.
For changes that warrant it, the same application can run a fully governed pipeline: isolated candidates, deterministic audit, Sensei admission, exact-artifact apply, and verification. That is opt-in, not the default.
It should feel familiar to users of Claude Code, Codex, Cursor Agent, Pi, and similar tools: open a repository, describe a task, watch work happen, inspect decisions, and continue the conversation. The difference is the architectural knowledge underneath, and the fact that Sensei Code does not treat one model session as architect, implementor, reviewer, authority, and memory at the same time.
In assisted mode, the default:
HUMAN + their coding agent
|
SENSEI CODE
context · task identity · continuity
|
SENSEI
invariants | contracts | failure modes
forbidden fixes | proof obligations
In governed mode, opt-in per task:
HUMAN
ultimate authority
^
| rare escalation
|
ARCHITECT / REVIEWER
OpenAI
^
| architectural authority
|
SENSEI CODE
autonomous orchestrator
|
+---------------+---------------+
| |
Claude Code Codex
implementor implementor
| |
+---------------+---------------+
|
Git worktrees
|
SENSEI
truth | governance | evidence | admission | closure
Sensei knows and governs. Sensei Code coordinates work. Agents implement.
Sensei Code makes Sensei easier to adopt without making Sensei easier to bypass.
Modern coding agents are powerful implementors, but an agent session does not automatically answer repository-owned questions such as:
- What architectural rules apply to this change?
- Which source is authoritative?
- Which known failure modes and forbidden fixes already exist?
- What scope may change?
- What tests and proof obligations are required?
- Did the candidate stay inside the admitted envelope?
- Is the evidence fresh and bound to the exact result?
- Is the task actually complete?
Sensei already owns those semantics. Sensei Code is the missing workflow layer that lets a developer use them without manually relaying prompts, diffs, receipts, worktrees, and evidence among several terminals.
You drive your agent. Sensei Code supplies the governed architectural context, keeps the task identity, and surfaces what Sensei observes (preflight, edit checks, diff audit) while the work happens. The agent writes in your checkout; you commit. Nothing is sealed and nothing is admitted.
Context is delivered through whatever each agent supports — generated CLAUDE.md / AGENTS.md / rules files, hook-driven briefings, MCP tools, or a prompt preamble — and it is selected proportionally to the file's rigor class rather than dumped wholesale.
Absence is typed. "No invariants apply here" and "the graph has no coverage here" are different answers, and the second one is never rendered as a blank panel.
The autonomous pipeline: isolated candidate worktrees, bounded workers, deterministic diff audit, reviewer cycles, Sensei admission, exact-artifact apply, verification, and completion. It costs more and it buys receipts.
A task is governed because the canonical Sensei records exist for it — never because a config key says so. An assisted task is never presented as a governed run.
Neither mode uses Sensei's own code-generation stack. The coding agents generate; Sensei governs. See docs/architecture.md section 3.4 for the evidence behind that decision.
In governed mode, Sensei Code is designed to be autonomous during normal development. It does not ask the user whether it may read a file, run a test, create a candidate worktree, or let a bounded worker repair a failed test.
It uses three authority levels:
Sensei Code may act autonomously inside its configured local capability envelope. Typical actions include repository inspection, worktree creation, worker execution, builds, tests, Sensei queries, candidate audits, retries, and bounded repair cycles.
The architect may resolve normal architectural questions autonomously, using repository evidence and Sensei context. A worker failure does not become a human question merely because an agent is uncertain.
Sensei Code interrupts when a decision reaches authority the architect does not own — human-owned product intent, an invariant, an externally meaningful contract, a trust boundary, an explicit policy — or when Sensei cannot certify the decision at all.
The trigger is a property of the graph, not a model's confidence. A model deciding whether to bother you is not a control: a confidently wrong architect never escalates, and an uncertain one escalates when nothing is at stake. So the conditions are computable:
the decision touches a region with no graph coverage at this generation
a claim in the governing plan is contradicted by the graph
the governing contract is unknown, contested, or absent
the change would alter human-owned intent, an invariant, or a trust boundary
the graph is not fresh enough to answer the question being decided
Sensei cannot establish who owns the authority for this decision
The corollary matters as much: outside those conditions, do not ask. A prompt that a certifiable rule could have answered is a defect.
And every answer you give is written back into the graph as an intent, invariant, contract, or forbidden fix — so the same question is certifiable next time and never reaches you again. Without that, the interruption rate plateaus and the system has merely stopped asking rather than learned. With it, your involvement shrinks toward genuinely new territory.
The UI then presents a small numbered decision surface:
╭─ ⚑ HUMAN AUTHORITY REQUIRED ───────────────────────────────────╮
│ │
│ The proposed fix would change a human-owned contract. │
│ │
│ Architect recommendation: 1 │
│ │
│ 1. Preserve the contract and redesign the implementation │
│ 2. Change the product policy │
│ 3. Stop the task │
│ │
╰───────────────────────────────────────────────────────────────╯
Normal execution keeps flowing. Authority crossings do not.
The first Go foundation is being built around these boundaries:
- Bubble Tea v2 terminal application
- Bubbles v2 textarea input
- Lip Gloss v2 styling
- structured event bus and JSONL session history
- explicit execution / architectural / human authority model
- direct structured MCP connection to Sensei's
awareness-mcp - Sensei workspace identity and preflight before architecture
- OpenAI/Codex architect and reviewer adapters
- Claude Code primary worker with Codex fallback
- isolated sibling Git worktrees for candidates
- autonomous bounded review/repair cycles
- Sensei deterministic diff audit before reviewer acceptance
- Level-3 human authority rendezvous and resume
sensei-code doctorreadiness checks, naming the fix for each failure- an architect command set over Sensei:
/report,/focus,/why,/debt,/audit,/gate,/refactor,/learn /runauthorizes the task; the plan is shown, never voted on- Esc stops a running task, leaving the candidate as it stands
- Esc at a Level-3 decision defers the question; only a chosen option answers it
- guidance typed during a run, delivered at the next worker cycle
- one candidate per task, handed between workers instead of restarted
/resumefor a task interrupted after it was planned- pull request creation from an accepted candidate, never a merge
The foundation deliberately stops short of pretending that reviewer acceptance is Sensei admission. The next governed slice binds candidate output to Sensei's canonical admission/apply/verification contracts.
See docs/architecture.md and docs/implementation-status.md.
Anything you type that is not a command is a task: describe it and the architect
plans it, you accept the plan, and only then does a worker touch a candidate.
The commands answer questions without starting any work. /help lists them, and
that listing is generated from the same declaration the dispatcher reads, so it
cannot describe a command that does not exist.
Understand the codebase
/report |
what Sensei knows about this repository, with each count's provenance |
/focus <path> |
what governs one file, before you change it |
/why <id> |
read the rule behind a name, what it protects and what proves it |
/debt |
the surfaces no invariant protects, largest first |
Keep a change under control
/audit |
Sensei's own repository evaluation and corpus validation, quoted |
/gate |
check the working diff against what governs it, before you commit |
/refactor <target> |
ask the architect for a bounded refactor plan |
Teach Sensei
/learn <what broke> |
queue a scar so the next agent cannot repeat it |
Session: /resume, /setup, /login, /mcp, /clear, /help. /setup
reports the same readiness checks as sensei-code setup and repairs nothing;
repair stays with the CLI's --apply, because it reaches outside the repository.
Two habits are worth forming. /focus before editing a file tells you what it is
bound by; on a governed path it will say SECURITY_RISK · human_approval_required
rather than letting you find out afterwards. /debt tells you where an agent's
change would meet nothing that could refuse it, which is where AI-written code
accumulates risk fastest.
Every command ends with what it does not establish. A count measures what is recorded, never whether the code obeys it, and a class Sensei holds nothing for is knowledge it was never given rather than evidence the repository is clean.
Assisted mode — the agent is yours, the context is Sensei's:
$ sensei-code
◆ SENSEI
workspace identity verified · graph generation 2026-08-15T09:14Z (HEAD-2)
golang/architecture/agentcommand/ · rigor class B
4 invariants · 2 failure modes · 1 forbidden fix
proof obligations: api_agent_test.go:TestVendorBoundaryRepair
runtime coverage: UNAVAILABLE (no crossing source)
● CLAUDE
working in your checkout...
◆ SENSEI
edit check: api_agent.go
⚑ forbidden fix nearby: "widen the vendor boundary to pass the test"
● CLAUDE
...
◆ SENSEI
diff audit: 2 files · contracts represented · no forbidden fix observed
✓ REVIEWED WORKING TREE
assisted task · no admission requested · yours to commit
Governed mode — opt-in, receipts at the end:
$ sensei-code
◆ SENSEI
workspace identity verified
briefing and preflight loaded
◈ ARCHITECT
architecture resolved
bounded implementation contract issued
● CLAUDE
implementing in isolated candidate worktree...
◆ SENSEI
candidate diff audited
contracts: represented
forbidden fixes: none observed
◈ REVIEWER
REVISE: add the missing clean-room regression test
● CLAUDE
repairing autonomously...
◆ SENSEI
candidate diff audited
◈ REVIEWER
ACCEPT
✓ READY
candidate ready for governed admission
───────────────────────────────────────────────────────────────
> _
───────────────────────────────────────────────────────────────
ready · agent activity collapsed · Ctrl+O toggle
If the architect reaches human-owned authority, the conversation pauses at the numbered decision and resumes the same workflow after the answer.
The core runtime is local:
Sensei Code
Sensei / awareness-mcp
Git
Codex CLI
Claude Code
compiler / tests / repository tooling
GitHub is optional collaboration and publication infrastructure, not project authority.
Model providers own their own authentication. Sensei Code does not collect ChatGPT, Claude, or Cursor credentials.
The context Sensei Code injects is only as good as the graph behind it, and a stale graph does not fail loudly — it answers confidently and wrongly. Readiness is therefore part of the product, not a setup step.
Every injected packet carries the graph generation it was answered from, and one of:
fresh graph generation covers HEAD
behind graph generation predates HEAD by N commits
uncovered the files in view are not represented at this generation
unbuilt no graph for this repository/domain
unavailable the store or service cannot be reached
mismatched graph identity does not match this checkout
Assisted mode shows the state and keeps working. Governed mode fails closed on anything but fresh unless the human explicitly accepts a weaker state for that task.
A repository with no graph is the normal first run, not an error. Sensei Code guides the explicit onboarding Sensei owns and never fabricates bindings to reach a green status; until then it degrades honestly to an ordinary agent session with typed-absent context.
sensei-code doctor is the single computation behind all of this — binaries, versions, store, generation, freshness, domain, tool subset, provider readiness. The UI reads the same answer the CLI prints.
See docs/architecture.md section 5, including the operational hazards the product is expected to absorb so that users never meet them.
brew install globulario/tap/sensei-codeor, without Homebrew:
curl -fsSL https://raw.githubusercontent.com/globulario/sensei-code/main/packaging/install.sh | shOn Windows: winget install Globulario.SenseiCode.
Sensei Code reads Sensei's graph, so it needs Sensei too. The formula depends on it and the script installs it when it is missing; you should not have to install two things by hand.
Then, in any repository:
sensei-code setup --apply
sensei-codesetup is the whole onboarding. It checks everything a session needs — the
Sensei CLI, which awareness-mcp wins on PATH and whether it is recent enough
to expose the workspace tools, the graph server, graph freshness, the domain
registration that lives outside the repository, the awareness corpus, and each
agent's MCP access — and for anything wrong it reports what you would see when
it breaks alongside the command that fixes it. With --apply it repairs what
it can and re-checks rather than assuming the repair worked, looping until
nothing further can be fixed, because some repairs unlock others.
Run it again any time something behaves oddly. Most of what goes wrong here presents as an unrelated symptom: a stale graph marker fails every task closed with a digest that appears nowhere, and an agent whose MCP tools are blocked reports that Sensei is unavailable when Sensei is fine.
git clone https://github.com/globulario/sensei-code
cd sensei-code
go build -o bin/sensei-code ./cmd/sensei-codeRequires Go 1.25 or later.
Configuration is stored in:
<repository>/.sensei-code/config.json
It is local state and should not be committed.
The default capability envelope permits routine local development but refuses external/destructive authority:
{
"permissions": {
"read_repository": true,
"write_candidates": true,
"create_worktrees": true,
"run_builds": true,
"run_tests": true,
"local_commit": true,
"push": false,
"force_push": false,
"production_deploy": false
}
}The default provider roles are:
architect: Codex, read-only repository access
implementor 1: Claude Code, isolated candidate worktree
implementor 2: Codex, isolated candidate worktree fallback
reviewer: Codex, read-only repository access
Provider commands are adapters, not architectural identities. They can be replaced without changing the Sensei-owned governance model.
Sensei Code speaks directly to Sensei's structured MCP bridge rather than scraping terminal prose or duplicating Sensei semantics.
The integration surface includes canonical tools such as:
sensei_workspace_status
awareness_briefing
awareness_impact
awareness_preflight
awareness_audit_diff
task_status
task_briefing
advance_task
sensei_workspace_admit_change
sensei_workspace_verify_admission
complete_task
inspect_terminal
recover_projections
awareness_investigate
awareness_evidence_coverage
awareness_candidates
awareness_challenge
Not every tool is wired into the first vertical slice yet. Sensei remains the owner of those semantics as each stage is added.
Workers never receive the canonical checkout as their normal mutation surface.
Candidate worktrees are created beside the repository:
/work/project/
/work/.project.sensei-code-worktrees/
task-.../
claude/
codex/
This separates local application/session state from candidate execution state and reduces the blast radius of autonomous workers.
A candidate worktree is still not authority. It becomes meaningful only through Sensei-governed evaluation, admission, application, verification, and completion.
Provider stdout is normalized into an event stream. The TUI is only one projection of that stream.
Important event classes include:
task.created
agent.started
agent.finished
candidate.changed
candidate.audited
authority.required
authority.resolved
workflow.completed
workflow.failed
Raw worker activity is persisted but collapsed in the normal UI. This keeps the interface conversational while preserving evidence for debugging and future JSON/IDE/CI frontends.
- Sensei is not an agent. It is the governance boundary.
- Sensei Code does not replace your coding agent. Assisted mode is the default; the agents keep generating the code.
- Mode is derived from receipts, not configuration. Governed means the canonical Sensei records exist.
- Injected context carries its provenance. Every claim names the graph generation it came from; absence is typed, not blank.
- Absence of evidence is not success. Fail closed when Sensei cannot establish required truth.
- Architectural authority extends exactly as far as Sensei can certify it. Not one decision further.
- Escalation is triggered by certifiability, not by model uncertainty. And do not ask a human what a certifiable rule already answers.
- Every human answer becomes a governed entry. An unrecorded decision guarantees the question returns.
- Workers do not own architecture. They implement bounded contracts.
- Reviewer acceptance is not admission. Sensei owns admission and verification.
- Routine execution is autonomous in governed mode. Do not convert worker uncertainty into human permission prompts.
- Human interruption means an authority boundary was reached. Keep it rare and explicit.
- Local UI state is not project truth. Durable architectural truth belongs to Sensei/repository governance sources.
- Manual work must never masquerade as a governed run. Receipts and exact bindings matter.
See LICENSE.