Agence MCP

l'Agence — Agentic Engineering Co-Environments

Author: Stephane Korning · 2026 · MIT + Commons Clause
Version: v1.0.0 · May 2026

The governance layer for AI coding agents.
Every agent action classified, gated, and cryptographically logged — regardless of which LLM or tool runs it.

---

The Problem

Your AI coding agents can write code. They can commit, push, delete, refactor.

But who's watching them?

Claude Code has no audit trail. Aider trusts the user. Codex sandboxes everything and hopes for the best. LangChain gives you building blocks but no guardrails.

Agence exists because advisory guardrails aren't guardrails at all. It's the layer that sits between any AI agent and your filesystem and says "not without approval."

---

What Agence Does

Agence is an agent-agnostic governance stack for software engineering. It doesn't replace your coding agent — it governs, orchestrates, and audits all of them from a single control plane.

Command Gating — Every shell command is classified before execution:

Tier	Gate	Example
T0	Auto-execute	git status, ls, cat
T1	Logged	git add, git commit
T2	Human approval required	git push, git reset
T3	Blocked	rm -rf, chmod 777, kill

Unknown commands default to T2. Not T0. Fail-closed. The guard runs as a separate process — agents cannot bypass their own policy.

Cryptographic Audit — Every agent decision is logged to a Merkle-chained, append-only ledger. Each entry links to the previous via SHA-256. Tamper with one entry and the chain breaks. Verify with: agence ^ledger verify.

Multi-Agent Orchestration — 18 agents across 4 types (persona, tool, loop, ensemble). Route with @agent syntax. Override models with dot-notation: @ralph.gpt4o. Dispatch to Aider, Claude Code, Copilot, or your own tools — all governed by the same policy.

Peer Consensus — Route any question to 3 independent LLMs and get weighted consensus. Your architecture review shouldn't depend on one model's blind spots.

Session Persistence — Save, resume, and hand off sessions between agents. Full context survives restarts. Automatic tmux capture of stdout/stdin/stderr — no 16KB buffer limits.

Git-Native — No database. No server. State lives in git worktrees and flat files. Knowledge is sharded, gated, and selectively routed — you decide what gets shared.

---

By the Numbers

30,701	Lines of production code (23.9K TypeScript + 6.8K bash)
751	Tests with 1,768 assertions across 21 files
279	Security-specific tests (guard + hardening + SEC regressions)
9	Red-team cycles completed (SEC-008 through SEC-019)
33+	Orchestration skills (^fix, ^review, ^hack, ^peers, ^vault...)
18	Registered agents (10 persona, 5 tool, 1 loop, 2 ensemble)
12	LLM providers (Anthropic, OpenAI, Azure, Google, Mistral, Groq, Ollama...)
10	MCP tools + 3 MCP resources (Model Context Protocol server)
3	Dependencies total (MCP SDK, Bun, Zod)
0	Databases required

---

Who This Is For

• Teams using multiple AI coding agents who need one policy governing all of them
• Enterprises requiring audit trails for AI-generated code changes
• Security-conscious developers who want fail-closed gating, not fail-open trust
• Anyone who's had an AI agent break something and wished there was a layer between the agent and rm -rf

Who This Is NOT For

• If you want an AI pair programmer → use Aider
• If you want IDE autocomplete → use Continue or Copilot
• If you want to build any kind of agent → use LangChain/LangGraph
• If you want cloud-hosted async tasks → use OpenAI Codex

Agence governs all of the above.

---

GitHub Action — Agence Guard

Gate AI agent commands in any CI workflow — one step, zero infrastructure:

- name: Gate AI command
  id: guard
  uses: l-agence/agence@v1
  with:
    command: 'git push origin main'   # command proposed by your AI agent
    agent: ci
    fail_on_block: 'true'             # fail if T3-blocked

- run: echo "Tier ${{ steps.guard.outputs.tier }} — ${{ steps.guard.outputs.reason }}"

Input	Description	Default
command	Shell command to classify	required
policy	Path to custom AIPOLICY.yaml (repo-relative)	bundled policy
agent	Agent identity for MLS capability checks	ci
fail_on_block	Exit 1 on T3 (deny)	true
fail_on_escalate	Exit 1 on T2 (requires approval)	false

Output	Values
tier	T0 · T1 · T2 · T3
action	allow · flag · escalate · deny
reason	Human-readable decision
rule	Matched policy rule

See docs/marketplace/description.md for full documentation.

This PR starts with the GitHub Action path first for fast per-repo adoption; the GitHub App listing and webhook server can follow in a later phase or separate PR for org-level rollout across many repositories.

For enterprise adoption, the next layer after the GitHub App is shard onboarding so orgs can separate teams, policies, and knowledge boundaries cleanly instead of forcing one shared shard model.

---

Install

As a git submodule (recommended)

git submodule add https://github.com/l-agence/agence .agence
git submodule update --init --recursive
bash .agence/bin/agence ^init
export PATH="$PWD/.agence/bin:$PATH"

Or: clone directly

git clone https://github.com/l-agence/agence .agence
cd .agence && bun install
./bin/agence ^init
export PATH="$PWD/.agence/bin:$PATH"

Prerequisites

Tool	Required	Install
bash 4+	Yes	Built-in on Linux/macOS/WSL
git 2.30+	Yes	sudo apt install git
bun 1.3+	Yes	bun.sh
tmux	For swarm	sudo apt install tmux
jq	For ledger queries	sudo apt install jq

Windows: Use WSL (Ubuntu recommended).

---

Quick Start

# Chat with an agent
agence "How should I structure this feature?"

# Route to a specific agent
agence @sonya "Review this auth module"

# Launch an agent shell
agence !ralph                    # Persona: autonomous iteration
agence !claude                   # Tool: Claude Code CLI
agence !aider                    # Tool: aider (code patches)

# Save session (resume later or hand off to another agent)
agence ^save "OAuth2: done token validation, next: refresh flow"
agence ^resume
agence ^handoff @sonya

# Audit trail
agence ^ledger verify            # Verify Merkle chain integrity
agence ^audit trail              # View full decision history

# Peer consensus (3 independent LLMs)
agence @peers "Should we use Redis or Postgres for session storage?"

# See all commands
agence --help

---

Architecture

YOUR REPO/
└── .agence/                     ← lives here (submodule or clone)
    ├── bin/                     # CLI: agence, aibash, ibash, aido, agentd
    ├── codex/                   # Governance: AIPOLICY.yaml, Laws, Principles, agents/
    ├── nexus/                   # Local state: .ailedger, sessions, faults (gitignored)
    ├── knowledge/               # Team knowledge: docs, lessons, plans (committed)
    │   └── private/             # Private knowledge (gitignored, never shared)
    ├── organic/                 # Swarm coordination: tasks, jobs, workflows
    └── lib/                     # Core: guard.ts, signal.ts, skill.ts, memory.ts, peers.ts

COGNOS — Four pillars:

Pillar	Purpose	Location
CODEX	Immutable governance — Laws, Principles, Rules, AIPOLICY	codex/
KNOWLEDGE	Team-shared docs, lessons, plans — selectively routed via @ symlinks	knowledge/
NEXUS	Local operational state — sessions, ledger, signals	nexus/ (gitignored)
ORGANIC	Swarm orchestration — tasks, workflows, matrix scheduling	organic/

Runtime: Bun + bash. No Python. No pip. No npm install of untrusted packages in the critical path.

MCP: Agence exposes itself as an MCP server (10 tools, 3 resources) so any MCP-compatible client can use agence's governance layer. Agence also acts as an MCP client — consuming tools from external MCP servers. See MCP.md for integration guide.

---

Command Reference

Prefix	Mode	Example	Use When
(none)	Chat	agence "explain this error"	Advice, explanation, Q&A
^	Knowledge	agence ^save, agence ^lesson	Shared state, knowledge ops
~	Private	agence ~note "idea"	Private notes (never committed)
+	Autonomous	agence +refactor-auth	Agent plans & executes a task
/	Validated	agence /git-status	Pre-approved safe commands
!	System	agence !ralph, agence !claude	Launch agents or tools
@	Route	agence @sonya "review this"	Send to specific agent

---

Agent Roster

Agent	Type	Best For
@ralph	Loop	Autonomous iteration with backpressure
@sonya	Persona	Architecture, code review
@claudia	Persona	Deep reasoning, critical decisions
@chad	Persona	DevOps, infra, CI/CD
@aleph	Persona	Red team, security analysis
@claude	Tool	Claude Code CLI (headless spawn)
@aider	Tool	Code patches, git diffs
@pilot	Tool	GitHub Copilot CLI
@peers	Ensemble	3-LLM weighted consensus
@pair	Ensemble	2-LLM lightweight consensus

Override models with dot-notation: @ralph.gpt4o, @sonya.opus, @ralph.aider

---

Governance

Agence uses a 5-tier command policy. The guard runs as a separate process — agents cannot bypass their own policy.

Tier	Gate	Example
T0	Auto-execute	git status, ls, cat
T1	Logged	git add, git commit
T2	Human approval	git push, git reset
T3	Blocked	rm -rf, chmod 777
T4	Never	Force push main, drop DB

Unknown commands default to T2. Fail-closed. 120+ rules across git, GitHub CLI, AWS, Terraform, and shell.

All decisions logged to nexus/.ailedger — append-only, Merkle-chained, HMAC-signed.

See SECURITY.md for full security architecture, red-team findings, and disclosure timeline.

---

Swarm (agentd)

agentd start ralph claude aider   # Launch 3 agents in tmux
agentd tangent create fix-auth    # Isolated worktree + container
agentd inject fix-auth "run tests"  # Send command via socat socket
agentd status                     # View all agents + tangents

Each tangent gets: isolated git worktree, optional Docker container (--cap-drop ALL, --read-only, --no-new-privileges), socat socket for IPC, tmux pane for observability.

---

Tests

bun test                          # Full suite

751 tests, 1,768 assertions, 0 failures across 21 files:

Suite	Tests	Coverage
guard.test.ts	132	Command gate, tier escalation, eval safety
security-hardening.test.ts	134	HMAC, signal forgery, injection prevention, SEC-010→019 regressions
memory.test.ts	62	COGNOS 3-store: retain/recall/cache/forget/promote/distill
peers-dispatch.test.ts	53	Peer consensus, mixed routing
queue.test.ts	42	Work queue, dashboard, GitHub Issues bridge
runs.test.ts	35	SWE run lifecycle, aggregation, outcomes
vault.test.ts	20	Hermetic vault init/sync/push/pull + SEC-019 security
setup.test.ts	10	Interactive wizard, escaping, validation
mcp-client.test.ts	10	MCP client guard-gating, env sanitization
mcp.test.ts	10	MCP tool/resource surface verification
sequent.test.ts	12	Tournament tangents, CLI dispatch

---

Documentation

Doc	What it covers
Architecture	End-to-end system design
Swarm	agentd, tangents, tmux model
Commands	Complete CLI reference
Security	TCB, red-team findings, disclosure timeline
Tutorial	Getting started walkthrough
Setup	Detailed installation guide

---

License

MIT + Commons Clause — free to use, modify, and self-host.
Commercial redistribution requires a separate agreement.
See LICENSE.md.

---

Built by Stephane Korning. Hardened by 5 red-team cycles. Governed by its own CODEX.