agora

A G O R A
_{The alignment layer between human intent and AI execution.}

Your AI agent doesn't fail at writing code. It fails at understanding what you meant.

Agora is a Human-AI Alignment (HAA) framework for making human taste
executable by AI coding agents.

Before a single line is written, five ancient philosophers interrogate your
intent until it's unambiguous. Then a verification-gated loop builds it —
checking at every iteration that the output still matches what you actually
wanted.

Quick start

Requires Claude Code (authenticated with a
Claude subscription) and Node 22+.

npm install -g @lazydevz/agora                 # installs the `agora` CLI + MCP server
claude mcp add --scope user agora -- agora mcp # register the tools in every project

Then open Claude Code in your project and ask:

"Use agora to align on a settings page, then build it."

Claude Code will call Agora's tools as needed: start or resume the project-local
.agora/ session, run alignment, and build through the gates.

More install options and a worked example: docs/getting-started.md

Developing Agora with Codex or another coding agent? Read
docs/SESSION_HANDOFF.md first, then the shared
agent guide for task execution, model guidance and the
MCP host relay contract. The installation above is the shipped Claude Code path;
using Codex to contribute does not add an OpenAI runtime to Agora.

The problem every AI-coding developer knows

You ask for a feature. The agent confidently builds something. It compiles, it
runs — and it's subtly, frustratingly not what you meant. You correct it. It
drifts somewhere else. Five iterations later you're further from your intent than
when you started.

This isn't a model-quality problem. It's an alignment problem. And it compounds:

If each iteration drifts just 10% from intent:   0.9¹⁰ ≈ 0.35

After 10 iterations, the result resembles your intent by ~35%.

It does not matter how powerful the underlying model is. Alignment is the
leverage point, not raw generation power. Agora bets its entire architecture on
closing the gap before the loop starts — and policing it during every iteration.

Why philosophy (and not more prompts)

Everyone tries to close the intent gap with better prompts, plans, or templates.
Agora closes it with the most refined methods of inquiry humanity has ever
produced — operationalized as code. Each philosopher is a real module that drives
a real decision at a specific point in the workflow:

How it works: two loops

Agora runs two loops back to back. The first makes sure you're building the right
thing. The second makes sure you build it right — and that it stays right.
A locked Seed is the handoff between them.

┌──────────────────────────────────────────────────────────────────┐
│  Alignment Loop  (Human-AI Alignment, "HAA")                       │
│  Goal: drive expected ↔ actual gap to ~0% BEFORE any code          │
│                                                                    │
│  Phase −1  Husserl Epoché   — bracket assumed frames (optional)    │
│  Phase  0  Auto-scan        — brownfield detect, ingest MD context │
│  Phase  1  Open intake      — receive all the context you can give │
│  Phase  2  Iterative rounds — Aristotle structures (4 causes),     │
│            Socrates tests, Plato measures maturity                 │
│  Terminate — user assent + structural validation + Plato Dihairesis│
│              splits the goal into atomic, verifiable pieces        │
└──────────────────────────────────────────────────────────────────┘
                           │
                           ▼  🔒 locked Seed (.agora/seed.json)
                           │
┌──────────────────────────────────────────────────────────────────┐
│  Ralph Loop  (verification-gated implementation)                   │
│  Goal: satisfy the Seed AND stay aligned, every iteration          │
│                                                                    │
│  Each iteration must pass the gates:                               │
│    Gate 0  Pre-flight infra   — CLIs authed, deps reachable        │
│    Gate 1  Deterministic      — lint, typecheck, build, test       │
│    Gate 2  Functional QA      — your project's Playwright tests    │
│    Gate 3  UI/UX quality      — Aquinas Disputatio                 │
│    Gate 4  Technical quality  — Aquinas Disputatio                 │
│    Gate 5  Alignment check    — output ↔ Seed telos   ◀ inviolable │
│                                                                    │
│  Loop continues until all gates pass AND you are satisfied.        │
└──────────────────────────────────────────────────────────────────┘

The Alignment loop refuses to terminate until intent is settled. The Ralph loop
refuses to ship until every gate passes — including the alignment gate, the one
that can never be waived.

What it feels like in practice

You: "I want a settings page."                    ← vague is fine; that's the point

[Husserl]   "A *page* — or do you actually want settings to *persist* per user?"
[Aristotle] "Why does this exist?"  → telos: users want to customize defaults
            "What's its essential structure?"  → form
            "Which stack?"  → material        "Who/when/how?"  → efficient
[Plato]     "That telos is still shallow — what *good* does customization serve?"
            → loops back until each answer is mature enough
[Plato]     splits it into atomic pieces:  ac_001  ac_002  ac_003 …

🔒 Seed locked.  Now Ralph takes over:

  ▸ implement ac_001  →  Gate 1 ✓  Gate 5 ✓ (drift 0.04)  Gate 3+4 ✓  →  done
  ▸ implement ac_002  →  Gate 1 ✓  Gate 5 ✗ (drift 0.41!) →  fix + retry
  ▸ …until every piece passes every gate.

Runs inside Claude Code — host-supplied reasoning

Agora is designed to run as a layer inside Claude Code. It contributes the
method (the philosophers) and the gates (verification); Claude Code contributes
the intelligence.

In the MCP path, Agora makes no LLM calls. When reasoning is needed, your
existing Claude Code session does the thinking — which means:

• ✅ Reasoning uses your host session under that host's plan and usage limits
• ✅ No Agora-side API key or nested LLM call is needed for this path
• ✅ Agora stays a thin, fast alignment/verification layer — anti-fragile to model upgrades

The augmentation bet: Agora is to AI coding agents what Linux distros are to
the kernel. When the next model ships, every workflow built on Agora inherits the
gain. We bet on AI progress, not against it.

Status

Agora is alpha and under active development. We believe an honest status beats a
polished lie — here's exactly what works today.

Note on architecture: the in-Claude-Code plugin model (above) is now the
primary path — all reasoning happens inside your interactive Claude Code session
via the stepped MCP tools. Standalone CLI (subprocess) mode remains supported
for non-plugin users and invokes claude --print; its billing follows the
installed Claude runtime and account terms. The billing assumptions recorded
in ADR-0009 / ADR-0010 are historical, not a current pricing guarantee.

What makes Agora different

• One command, guided flow. You rarely think about subcommands — agora tells
  you what to do next at every step.
• Biased over un-biased. We pick the best option so you don't have to.
• Per-folder isolated. Cross-folder context bleed is forbidden; same-folder
  accumulation is welcomed.
• Auto-detect everything detectable. We never ask what we can already know.
• Telos-first. Purpose (the final cause) is the primary axis of every
  evaluation — not features, not file counts.
• Built by the method it teaches — see ADR-0003.

Inspirations & credits

Agora was partly inspired by Ouroboros's
intuition that AI coding benefits from an intent-refinement phase before
implementation. Agora is an independent TypeScript implementation with its own
architecture, philosopher modules, Claude Code MCP mode, and verification gates.

See CREDITS.md for full attribution and MANIFESTO.md
for the philosophy behind the philosophy.

License

MIT. See LICENSE.

_{Built by Sang Rhee · lazydevz, Inc.}