{
  "markdown": "# l'Agence — Agentic Engineering Co-Environments\n\n**Author**: Stephane Korning · 2026 · [MIT + Commons Clause](LICENSE.md)  \n**Version**: v1.0.0 · May 2026\n\n> **The governance layer for AI coding agents.**  \n> Every agent action classified, gated, and cryptographically logged — regardless of which LLM or tool runs it.\n\n---\n\n## The Problem\n\nYour AI coding agents can write code. They can commit, push, delete, refactor.\n\n**But who's watching them?**\n\nClaude 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.\n\nAgence 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.\"*\n\n---\n\n## What Agence Does\n\nAgence 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.\n\n**Command Gating** — Every shell command is classified before execution:\n\n| Tier | Gate | Example |\n|------|------|---------|\n| T0 | Auto-execute | `git status`, `ls`, `cat` |\n| T1 | Logged | `git add`, `git commit` |\n| T2 | Human approval required | `git push`, `git reset` |\n| T3 | Blocked | `rm -rf`, `chmod 777`, `kill` |\n\nUnknown commands default to T2. Not T0. **Fail-closed.** The guard runs as a separate process — agents cannot bypass their own policy.\n\n**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`.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n---\n\n## By the Numbers\n\n| | |\n|---|---|\n| **30,701** | Lines of production code (23.9K TypeScript + 6.8K bash) |\n| **751** | Tests with 1,768 assertions across 21 files |\n| **279** | Security-specific tests (guard + hardening + SEC regressions) |\n| **9** | Red-team cycles completed (SEC-008 through SEC-019) |\n| **33+** | Orchestration skills (`^fix`, `^review`, `^hack`, `^peers`, `^vault`...) |\n| **18** | Registered agents (10 persona, 5 tool, 1 loop, 2 ensemble) |\n| **12** | LLM providers (Anthropic, OpenAI, Azure, Google, Mistral, Groq, Ollama...) |\n| **10** | MCP tools + 3 MCP resources (Model Context Protocol server) |\n| **3** | Dependencies total (MCP SDK, Bun, Zod) |\n| **0** | Databases required |\n\n---\n\n## Who This Is For\n\n- **Teams using multiple AI coding agents** who need one policy governing all of them\n- **Enterprises** requiring audit trails for AI-generated code changes\n- **Security-conscious developers** who want fail-closed gating, not fail-open trust\n- **Anyone who's had an AI agent break something** and wished there was a layer between the agent and `rm -rf`\n\n## Who This Is NOT For\n\n- If you want an AI pair programmer → use Aider\n- If you want IDE autocomplete → use Continue or Copilot\n- If you want to build any kind of agent → use LangChain/LangGraph\n- If you want cloud-hosted async tasks → use OpenAI Codex\n\nAgence **governs all of the above**.\n\n---\n\n## GitHub Action — Agence Guard\n\n[![GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agence%20Guard-red?logo=github)](https://github.com/marketplace/actions/agence-guard)\n\nGate AI agent commands in any CI workflow — one step, zero infrastructure:\n\n```yaml\n- name: Gate AI command\n  id: guard\n  uses: l-agence/agence@v1\n  with:\n    command: 'git push origin main'   # command proposed by your AI agent\n    agent: ci\n    fail_on_block: 'true'             # fail if T3-blocked\n\n- run: echo \"Tier ${{ steps.guard.outputs.tier }} — ${{ steps.guard.outputs.reason }}\"\n```\n\n| Input | Description | Default |\n|-------|-------------|---------|\n| `command` | Shell command to classify | **required** |\n| `policy` | Path to custom `AIPOLICY.yaml` (repo-relative) | bundled policy |\n| `agent` | Agent identity for MLS capability checks | `ci` |\n| `fail_on_block` | Exit 1 on T3 (deny) | `true` |\n| `fail_on_escalate` | Exit 1 on T2 (requires approval) | `false` |\n\n| Output | Values |\n|--------|--------|\n| `tier` | `T0` · `T1` · `T2` · `T3` |\n| `action` | `allow` · `flag` · `escalate` · `deny` |\n| `reason` | Human-readable decision |\n| `rule` | Matched policy rule |\n\nSee [docs/marketplace/description.md](docs/marketplace/description.md) for full documentation.\n\nThis 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.\n\nFor 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.\n\n---\n\n## Install\n\n### As a git submodule (recommended)\n\n```bash\ngit submodule add https://github.com/l-agence/agence .agence\ngit submodule update --init --recursive\nbash .agence/bin/agence ^init\nexport PATH=\"$PWD/.agence/bin:$PATH\"\n```\n\n### Or: clone directly\n\n```bash\ngit clone https://github.com/l-agence/agence .agence\ncd .agence && bun install\n./bin/agence ^init\nexport PATH=\"$PWD/.agence/bin:$PATH\"\n```\n\n### Prerequisites\n\n| Tool | Required | Install |\n|---|---|---|\n| `bash` 4+ | Yes | Built-in on Linux/macOS/WSL |\n| `git` 2.30+ | Yes | `sudo apt install git` |\n| `bun` 1.3+ | Yes | [bun.sh](https://bun.sh) |\n| `tmux` | For swarm | `sudo apt install tmux` |\n| `jq` | For ledger queries | `sudo apt install jq` |\n\n> **Windows**: Use WSL (Ubuntu recommended).\n\n---\n\n## Quick Start\n\n```bash\n# Chat with an agent\nagence \"How should I structure this feature?\"\n\n# Route to a specific agent\nagence @sonya \"Review this auth module\"\n\n# Launch an agent shell\nagence !ralph                    # Persona: autonomous iteration\nagence !claude                   # Tool: Claude Code CLI\nagence !aider                    # Tool: aider (code patches)\n\n# Save session (resume later or hand off to another agent)\nagence ^save \"OAuth2: done token validation, next: refresh flow\"\nagence ^resume\nagence ^handoff @sonya\n\n# Audit trail\nagence ^ledger verify            # Verify Merkle chain integrity\nagence ^audit trail              # View full decision history\n\n# Peer consensus (3 independent LLMs)\nagence @peers \"Should we use Redis or Postgres for session storage?\"\n\n# See all commands\nagence --help\n```\n\n---\n\n## Architecture\n\n```\nYOUR REPO/\n└── .agence/                     ← lives here (submodule or clone)\n    ├── bin/                     # CLI: agence, aibash, ibash, aido, agentd\n    ├── codex/                   # Governance: AIPOLICY.yaml, Laws, Principles, agents/\n    ├── nexus/                   # Local state: .ailedger, sessions, faults (gitignored)\n    ├── knowledge/               # Team knowledge: docs, lessons, plans (committed)\n    │   └── private/             # Private knowledge (gitignored, never shared)\n    ├── organic/                 # Swarm coordination: tasks, jobs, workflows\n    └── lib/                     # Core: guard.ts, signal.ts, skill.ts, memory.ts, peers.ts\n```\n\n**COGNOS** — Four pillars:\n\n| Pillar | Purpose | Location |\n|--------|---------|----------|\n| **CODEX** | Immutable governance — Laws, Principles, Rules, AIPOLICY | `codex/` |\n| **KNOWLEDGE** | Team-shared docs, lessons, plans — selectively routed via `@` symlinks | `knowledge/` |\n| **NEXUS** | Local operational state — sessions, ledger, signals | `nexus/` (gitignored) |\n| **ORGANIC** | Swarm orchestration — tasks, workflows, matrix scheduling | `organic/` |\n\n**Runtime**: Bun + bash. No Python. No pip. No npm install of untrusted packages in the critical path.\n\n**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](MCP.md) for integration guide.\n\n---\n\n## Command Reference\n\n| Prefix | Mode | Example | Use When |\n|---|---|---|---|\n| _(none)_ | Chat | `agence \"explain this error\"` | Advice, explanation, Q&A |\n| `^` | Knowledge | `agence ^save`, `agence ^lesson` | Shared state, knowledge ops |\n| `~` | Private | `agence ~note \"idea\"` | Private notes (never committed) |\n| `+` | Autonomous | `agence +refactor-auth` | Agent plans & executes a task |\n| `/` | Validated | `agence /git-status` | Pre-approved safe commands |\n| `!` | System | `agence !ralph`, `agence !claude` | Launch agents or tools |\n| `@` | Route | `agence @sonya \"review this\"` | Send to specific agent |\n\n---\n\n## Agent Roster\n\n| Agent | Type | Best For |\n|---|---|---|\n| `@ralph` | **Loop** | Autonomous iteration with backpressure |\n| `@sonya` | Persona | Architecture, code review |\n| `@claudia` | Persona | Deep reasoning, critical decisions |\n| `@chad` | Persona | DevOps, infra, CI/CD |\n| `@aleph` | Persona | Red team, security analysis |\n| `@claude` | **Tool** | Claude Code CLI (headless spawn) |\n| `@aider` | **Tool** | Code patches, git diffs |\n| `@pilot` | **Tool** | GitHub Copilot CLI |\n| `@peers` | **Ensemble** | 3-LLM weighted consensus |\n| `@pair` | **Ensemble** | 2-LLM lightweight consensus |\n\nOverride models with dot-notation: `@ralph.gpt4o`, `@sonya.opus`, `@ralph.aider`\n\n---\n\n## Governance\n\nAgence uses a 5-tier command policy. The guard runs as a **separate process** — agents cannot bypass their own policy.\n\n| Tier | Gate | Example |\n|---|---|---|\n| T0 | Auto-execute | `git status`, `ls`, `cat` |\n| T1 | Logged | `git add`, `git commit` |\n| T2 | Human approval | `git push`, `git reset` |\n| T3 | Blocked | `rm -rf`, `chmod 777` |\n| T4 | Never | Force push main, drop DB |\n\nUnknown commands default to T2. **Fail-closed.** 120+ rules across git, GitHub CLI, AWS, Terraform, and shell.\n\nAll decisions logged to `nexus/.ailedger` — append-only, Merkle-chained, HMAC-signed.\n\nSee [SECURITY.md](SECURITY.md) for full security architecture, red-team findings, and disclosure timeline.\n\n---\n\n## Swarm (agentd)\n\n```bash\nagentd start ralph claude aider   # Launch 3 agents in tmux\nagentd tangent create fix-auth    # Isolated worktree + container\nagentd inject fix-auth \"run tests\"  # Send command via socat socket\nagentd status                     # View all agents + tangents\n```\n\nEach tangent gets: isolated git worktree, optional Docker container (`--cap-drop ALL`, `--read-only`, `--no-new-privileges`), socat socket for IPC, tmux pane for observability.\n\n---\n\n## Tests\n\n```bash\nbun test                          # Full suite\n```\n\n**751 tests**, 1,768 assertions, 0 failures across 21 files:\n\n| Suite | Tests | Coverage |\n|---|---|---|\n| `guard.test.ts` | 132 | Command gate, tier escalation, eval safety |\n| `security-hardening.test.ts` | 134 | HMAC, signal forgery, injection prevention, SEC-010→019 regressions |\n| `memory.test.ts` | 62 | COGNOS 3-store: retain/recall/cache/forget/promote/distill |\n| `peers-dispatch.test.ts` | 53 | Peer consensus, mixed routing |\n| `queue.test.ts` | 42 | Work queue, dashboard, GitHub Issues bridge |\n| `runs.test.ts` | 35 | SWE run lifecycle, aggregation, outcomes |\n| `vault.test.ts` | 20 | Hermetic vault init/sync/push/pull + SEC-019 security |\n| `setup.test.ts` | 10 | Interactive wizard, escaping, validation |\n| `mcp-client.test.ts` | 10 | MCP client guard-gating, env sanitization |\n| `mcp.test.ts` | 10 | MCP tool/resource surface verification |\n| `sequent.test.ts` | 12 | Tournament tangents, CLI dispatch |\n\n---\n\n## Documentation\n\n| Doc | What it covers |\n|---|---|\n| [Architecture](knowledge/l-agence.org/docs/ARCHITECTURE.md) | End-to-end system design |\n| [Swarm](knowledge/l-agence.org/docs/SWARM.md) | agentd, tangents, tmux model |\n| [Commands](bin/COMMANDS.md) | Complete CLI reference |\n| [Security](SECURITY.md) | TCB, red-team findings, disclosure timeline |\n| [Tutorial](docs/TUTORIAL.md) | Getting started walkthrough |\n| [Setup](docs/SETUP.md) | Detailed installation guide |\n\n---\n\n## License\n\nMIT + Commons Clause — free to use, modify, and self-host.  \nCommercial redistribution requires a separate agreement.  \nSee [LICENSE.md](LICENSE.md).\n\n---\n\n*Built by Stephane Korning. Hardened by 5 red-team cycles. Governed by its own CODEX.*\n",
  "bytes": 12922,
  "sha": "1513325b31d0547cfa42408e4d4dda865af23c87ef96ff710e691639240ff799",
  "repo_slug": "l-agence/agence",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_l_agence_agence_1c1ac784/readme"
}