A mission-swappable one-person army — for build, review and trust.
▶ Watch the 30-second intro · MIT · zero-dependency core
Once AI writes the code, the job stops being "how do I write this" and becomes "should I trust this?" Ed Agent is built for that shift. It drives one requirement — or any content, or a diff — through nine stages with a swappable squad, but it stops at two deliberation checkpoints and surfaces the questions only a human can answer:
- Was the intent captured, or is it guessing the project? Unstated intent is the #1 flagged risk, not a silent guess.
- Should you trust this (not "is it correct") — provenance, verification, blast radius, the confidence-vs-evidence gap.
- Does the local optimum serve the global goal? It flags the technically-right, business-wrong decision that digs a global pit.
- Is it substance, or over-defensive ceremony? The "looks-rigorous, all-filler" detector.
Plus a mission-aware red team that attacks every build for what its domain cares about,
claim-level grounding (Grounded / Ungrounded / Contradicted), a memory that learns your
preferences, quality disciplines (ban AI-tone filler · quantify-or-flag · no blind praise),
real artifacts at every stage, and a quantified ledger. Drop it into any bot via MCP or the
AGENTS.md brief. Zero-dependency core (Node 18+).
New in v0.6 — the inner loop. Add --loop and the produced artifact is refined in a
deterministic produce → verify → (rollback) inner loop before review, with four safety
mechanisms that make a self-iterating loop survivable instead of a runaway: a severity gate, an
overshoot rollback, iron-law HARD-HALTS (a crossed red line never bypasses you), and a
budget fuse — plus a WHAT / WHY / PATTERN audit trail and a learning flywheel that
forges a durable rule from every rejection. The model produces; the harness governs.
Click the mascot above to watch the intro.
Honest by construction. Ed Agent does not pretend to understand your business — a harness can't. It forces the intent to be captured, runs deterministic trust / coherence / substance checks, and puts the right question at the right node. The judgment, the two checkpoints, and the two gates stay human. Velocity, not autonomy.
node bin/ed-agent.mjs "Build a REST API for user onboarding with rate limiting"# → code squad
node bin/ed-agent.mjs "Launch a landing page for a new savings product"# → marketing squad
node bin/ed-agent.mjs "Draft an NDA with a 12-month liability cap"# → contract squad
node bin/ed-agent.mjs "KYC onboarding with EDD source of funds"# → finance squad (eds-mcp)
node bin/ed-agent.mjs --mission optimize --input case-study.md # → optimize squad (review)No install, no dependencies. The core is pure Node (18+). Get the code, run one command, then watch it in the dashboard.
# 1 · get it
git clone https://github.com/Edwson/Ed-Agent.git &&cd Ed-Agent
# 2 · run a requirement through the governed lifecycle# --intent captures the business goal · --approve / --signoff are the two human gates
node bin/ed-agent.mjs "KYC onboarding with EDD source of funds" \
--intent "let compliant clients finish onboarding" --approve "You" --signoff "You"# 3 · open the control room to watch + tune it — no command line needed after this
node bin/ed-agent.mjs dashboard --open # → http://127.0.0.1:4317A run writes real artifacts to out/ and a quantified entry to Ed_agents_Claude.md (its memory). The dashboard reads that same file — it is the single source of truth, and nothing leaves your machine (the server binds to 127.0.0.1 only and makes zero external requests).
ed-agentbelow is shorthand fornode bin/ed-agent.mjs(runnpm linkonce to get the realed-agentcommand).
| You want to… | Command |
|---|---|
| Build / plan something | ed-agent "your requirement"(mission auto-detected) |
| Force a squad | ed-agent "…" --mission code|marketing|contract|finance|optimize |
| Review / de-AI any content | ed-agent --mission optimize --input file.md |
| Audit a diff — "should I trust this?" | ed-agent --audit changes.diff --intent "…" --not "a non-goal" |
| Run the self-correcting inner loop | ed-agent "…" --loop(severity gate · rollback · iron-laws · budget fuse) |
| Gate on critical red-team findings | ed-agent "…" --strict |
| Resolve an open checkpoint | --resolve "trust: accepted" / --resolve "ironlaw: reason" |
| Teach it a preference | ed-agent --remember --prefer "tone: terse" |
| Open the control room | ed-agent dashboard --open |
| Run every test | npm test && npm run test:dashboard && npm run test:mcp |
Want it inside Claude / Cursor / Codex instead of the terminal? Drop it in via the MCP server or the plain-text AGENTS.md brief.
The mission is auto-detected from the requirement (override with --mission):
| Mission | Squad | Produces |
|---|---|---|
| Code | Architect · Security · QA · Doc engineer | architecture · security review (STRIDE) · test plan · README |
| Marketing | Creative Director · Conversion Analyst · Consumer Psychologist · SEO | creative brief · conversion model · SEO plan · copy outline |
| Contract | Senior Lawyer · Risk-Control Officer · Negotiator · Semantic-Logic reviewer | clause map · risk register · negotiation positions · ambiguity review |
| Finance(default) | Planning · Regulation · Data · Development · QA · Risk & Governance | eds-mcp compliant build — scaffolded HTML/CSS/JS + conformance tests |
| Optimize(grand-mentor · 総監督) | Executor A · Reviewer B · Copy C · Data/Logic D · Market/SEO E | blind-score diagnostic · adversarial debate · de-AI'd draft · three-part output |
Browse committed runs in examples/ — one per mission.
The optimize mission takes existing content (a deck, a case study, a landing page, a clause) and runs the review SOP, so Ed Agent is a thinking unit, not only a build unit:
- Diagnostic — the squad blind-scores the content across five dimensions and names the three most fatal flaws.
- Adversarial debate — Reviewer B (a hard buyer) and Data/Logic D challenge it: how does this create a real benefit, with a number?
- Humanize — Copy C strips the AI-tone filler (a deterministic de-AI pass) and lays out the structure to finish.
- Optimized version — assembled in the exact three-part format: Expert diagnostic / 専門家による診断 · Optimized version / 最適化版 · Business-value assessment / ビジネス価値評価.
node bin/ed-agent.mjs --mission optimize "In conclusion, our world-class platform seamlessly leverages cutting-edge synergy to improve value."# → REWORK (low blind score): AI-tone filler flagged · claims missing numbers · fatal flaws namedWhen the content is a regulated-finance surface, the Data/Logic officer calls the real eds-mcp engine to show the numbers instead of asserting them — the guardrail components the surface should map to, the regulatory anchors for the jurisdiction, and the token-contrast WCAG pass rate of the system it would ship on.
Three house rules run in every review, not just optimize (the same skills/quality.mjs):
- Ban AI-tone filler — an EN + JA + ZH scanner flags
in conclusion,leverage,seamless,まず,シームレス,まさに, … so the voice stays human. - Quantify or flag — any sentence that asserts a benefit with no number is surfaced for a measured figure (ROI / cost / conversion / time saved).
- No blind praise — a blind score (five dimensions) yields a PASS / REWORK verdict; mediocre work is told it "would not pass a top-tier interview/review yet," with the reasons.
The hard problems once AI writes the code aren't syntax — they're trust, lost intent, blind global judgment, and plausible-nonsense defensive code. Ed Agent stops at two deliberation checkpoints and pulls you into the reasoning instead of rubber-stamping:
| Checkpoint | Asks | Catches |
|---|---|---|
| FRAME(after analyze) | Is the business intent captured, or is the agent guessing the project? | lost intent — the agent inferring the goal from text alone |
| TRUST(after review) | Should you trust it? Does the local optimum serve the global goal? Substance or ceremony? | the technically-right, business-wrong decision · over-defensive filler · LOW-trust output |
A run stays IN DELIBERATION — not shippable — until you answer the open questions, even when both sign-off gates are cleared. State the intent up front; resolve the rest:
node bin/ed-agent.mjs "Add a payment retry flow"# → IN DELIBERATION: "What is the business goal?"
node bin/ed-agent.mjs "Add a payment retry flow" \
--intent "cut failed-payment churn" \
--not "no auto-charge without consent; do not change the payments schema" \
--resolve "trust: reviewed, accept the blast radius"# → checkpoints clearPoint it at an existing artifact / diff — "should I trust this?" (no build):
node bin/ed-agent.mjs --audit pull-request.diff --intent "cut failed-payment churn" \
--not "do not change the payments schema"# → Trust: LOW · ⚠ local optimum: "migrate the payments schema" does a declared NON-GOAL# · Substance: CEREMONY (empty catch, TODO, grand claims with no numbers) · open questionsThe four assessors live in skills/trust.mjs (intent capture · trust score · global
coherence · substance scan) — all deterministic, all framed as questions for you, none of
them making the call.
Every build now also runs two mission-aware, deterministic passes — ~0 token (no LLM calls), because they're pure functions, not prompts. "Caring about more" costs almost nothing.
- Red team — an adversarial pass whose only job is to attack the produced artifact for what this mission cares about. The universal checks (unquantified claims · AI-tone filler · over-defensive ceremony · anything that does what a non-goal forbids) run for any business; the domain catalog adds the rest — code: injection / empty-catch / hardcoded secrets · marketing: unsourced superlatives / missing disclaimer · contract: ambiguous quantifiers / one-sided clauses · finance: a regulated claim with no anchor. It states its own coverage ("checks the loaded catalog + known anti-patterns; not exhaustive; does not replace a human expert") — so it passes its own no-confident-nonsense test.
- Claim grounding — tags every load-bearing claim Grounded (traces to a cited source or the stated goal) · Ungrounded (confident, with nothing behind it) · Contradicted (does what a non-goal forbids). The universal source is the captured intent, so it runs with zero domain pack — a bakery, a SaaS, a law firm, all the same.
Report-only by default — both are surfaced in 08b-redteam-grounding.md and do not change
the verdict, so existing runs stay byte-stable. Add --strict to gate on critical
findings + contradictions (they open a red-team checkpoint; resolve with
--resolve "redteam: …" — the human consciously accepts; the harness never bypasses it).
node bin/ed-agent.mjs "Add a payment retry flow and migrate the payments schema" \
--intent "cut failed-payment churn" --not "do not migrate the payments schema"# → REDTEAM: 2 critical · grounding 1G/0U/1C (report-only — surfaced, verdict unchanged)
node bin/ed-agent.mjs "…same…" --not "do not migrate the payments schema" --strict
# → IN DELIBERATION: red-team checkpoint open — the contradiction must be accepted or fixedStandalone, no lifecycle: ed_agent_redteam and ed_agent_ground (MCP), or
skills/redteam.mjs + skills/grounding.mjs as a library.
The whole thing so far is the chains: human gates, checkpoints, "never bypass". v0.6 adds the engine — an opt-in inner loop that refines the produced artifact before review, scored every iteration by the same deterministic assessors. It can self-correct fast precisely because four safety mechanisms keep it from running away (the "Loopmaxxing" failure mode where a loop burns the budget without converging):
- Severity gate — a composite score from the verified assessors (red team + grounding + blind score + substance). The loop exits when severity ≤ target.
- Overshoot rollback — a version buffer keeps the best-severity artifact. If a producer makes it worse for too long, it rolls back to the best version and stops. (The in-harness remediator is monotone so it can't overshoot; this is the safety valve for when you wire a non-deterministic host LLM as the producer.)
- Iron-law HARD-HALT — a crossed red line (never bypass a human gate · never move a secret off-box · finance: never skip KYC/AML, never auto-move money) stops the loop immediately and opens a checkpoint. A red line is a boundary, not a judgment call — the harness never crosses it silently.
- Budget fuse — a hard
--loop-maxcap. The loop can never run forever.
Every iteration writes a WHAT / WHY / PATTERN line — a court-grade audit trail of how the artifact changed and why the loop did what it did — and each iteration runs under forced amnesia (the producer sees only the current artifact + its findings, never a growing transcript, so it doesn't collapse over many iterations). The deterministic loop converges to the floor of what it can prove, then escalates the residual to a human — it never fakes a fix.
node bin/ed-agent.mjs "Add a payment retry flow" --mission code --loop # self-correct the build
node bin/ed-agent.mjs --refine messy-draft.md --mission code --target 6 # standalone loop on a file# → severity 47 → 18 over 4 iterations: fixed hardcoded-secret → empty-catch → AI-tone filler,
# then PLATEAU — the residual (an unquantified claim + marketing "tell" words) is escalated, not faked.
The learning flywheel. When you reject something with a reason, Ed Agent forges a durable, machine-checkable rule into its memory and re-checks for it on every later run — each rejection makes the next run stricter about exactly what you flagged:
node bin/ed-agent.mjs --reject "trust: violates MiFID II best execution"# forge a learned rule# → next run lists it as a concern and the loop scores against it (deterministic, not opaque ML)Off by default → the verdict stays byte-stable. Standalone surfaces: ed_agent_loop,
ed_agent_ironcheck, ed_agent_learn (MCP), or src/loop.mjs + src/skills/ironlaws.mjs
src/flywheel.mjsas a library. A full sample is committed inexamples/sample-loop/.
intake → context → analyze →◆FRAME→ research → ledger → plan → produce → review →◆TRUST→ certify
The middle five swap their content per mission; the spine is universal. Research cross-compares sources, compresses each claim to its load-bearing clause, and quarantines unverified ones. Plan and Certify each hold a human sign-off gate; FRAME and TRUST are deliberation checkpoints. A run is shippable only when both gates are cleared AND both checkpoints are closed.
Ed Agent remembers your preferences in Ed_agents_Claude.md and applies them on later runs
(and across hosts):
node bin/ed-agent.mjs --prefer "mission: marketing"# default squad when none is given
node bin/ed-agent.mjs --prefer "jurisdiction: uk"
node bin/ed-agent.mjs --remember "we ship a savings product for Gen-Z in the UK"
node bin/ed-agent.mjs --like "dense data tables" --dislike "emoji in headings"It records likes, dislikes, preferences and concepts; recalls them at the Context stage; and applies the preferred mission / jurisdiction automatically.
Ed Agent carries a library of 139 domain skills (src/skills/*.md — the same Markdown
methods published on the portfolio). Given a need, it deterministically ranks the library
by keyword/token overlap (name + id weighted, description + audience folded in) with a small
mission-affinity nudge — ~0 token, no LLM.The library produces the depth; the router picks
which lenses to load.
node bin/ed-agent.mjs skills "launch a marketing campaign and improve SEO conversion" --mission marketing --limit 4
# → blog-copy-humanizer · backend-data-geo-seo · seo-geo-self-audit · seo-strategy
node bin/ed-agent.mjs skills "KYC onboarding and AML for a securities broker" --mission finance
# → multi-jurisdiction-kyc-aml · us-securities-law-sec · compliance-approach …Standalone surfaces: ed_agent_route_skills (MCP — args: need, optional mission / limit),
the skills subcommand above, or src/skillrouter.mjs as a zero-dep library
(routeSkills(query, {mission, limit}) · skillCatalog()). The marketing mission already loads
its top methods into every plan automatically.
Full copy-paste guide: INSTALL.md. The short version:
| You have | Do this | Setup |
|---|---|---|
| Claude Desktop | Download ed-agent.mcpb → Settings → Extensions → drag it in → Install | none — self-contained |
| Claude Desktop(config) | Add ed-agent → npx -y github:Edwson/Ed-Agent ed-agent-mcp to your MCP config | needs Node 18+ |
| Claude Code | claude mcp add ed-agent -- npx -y github:Edwson/Ed-Agent ed-agent-mcp | one line |
Then just talk to Claude: "list the ed-agent missions,""use ed_agent_route_skills — which methods fit launching a product with SEO?,""run ed_agent_deliberate on this diff." Nothing runs automatically; the harness surfaces the decision, you make the call.
MCP (Claude · Cursor · Codex):
Tools (15): ed_agent_run · ed_agent_loop(v0.6 — self-correct an artifact: severity gate ·
overshoot rollback · iron-law halt + the audit trail) · ed_agent_ironcheck(v0.6 — scan for
crossed red lines) · ed_agent_learn(v0.6 — the flywheel: forge a learned rule from a
rejection) · ed_agent_deliberate (audit any artifact/diff — "should I trust this?") ·
ed_agent_redteam (mission-aware adversarial scan) · ed_agent_ground (claim grounding, three
states) · ed_agent_trust_scan (fast trust + substance) · ed_agent_optimize (the grand-mentor ·
総監督 review) · ed_agent_quality_scan · ed_agent_missions · ed_agent_skills ·
ed_agent_remember · ed_agent_recall · ed_agent_route_skills(route the .md skill library to a need). Enable with npm install @modelcontextprotocol/sdk zod
(optional — the CLI and library are zero-dependency).
The host loop (deep deliberation):ed_agent_run and ed_agent_deliberate return the open
checkpoint questions. The host LLM (Claude/Cursor/Codex) discusses them with you, then calls
the tool again with your answers in intent / resolve[] to close the deliberation. The engine
surfaces the questions; the conversation — and the decision — stay between you and the host.
Any other LLM (Hermes, …): paste the operating contract from AGENTS.md
into the system prompt — the host then behaves as Ed Agent.
Not everyone reads code. ed-agent dashboard opens a local control room so you can see
what Ed Agent is doing and tune it without the command line:
ed-agent dashboard # → http://127.0.0.1:4317 (add --open to launch the browser)- See every governed run — drill into any run's stages, gates, deliberation checkpoints, and per-stage estimated token cost.
- See what it cost — cumulative + per-mission est. tokens, labelled as estimates (cost governance, not a bill).
- See what it learned — the rules forged from your rejections; forget any you disagree with.
- Tune how it behaves — default mission, jurisdiction, the loop's severity target and budget,
strict mode, tone, likes — saved as plain
prefer:/like:lines in yourEd_agents_Claude.md(so you can still edit by hand and keep it in git). The engine applies them to unset run options next time.
It is honest by construction: a zero-dependency node:http server bound to 127.0.0.1
only, serving one page that makes zero external requests — nothing about your runs leaves
the machine. It reads (and edits) the same human-readable memory file the CLI uses — the single
source of truth. It's a control room over real, discrete runs, not a live always-on monitor, and
it doesn't replace the CLI/MCP — it observes and tunes them.
eds-mcp is the design-system engine (it scaffolds
compliant finance UI). Ed Agent is the special-ops orchestrator that runs the whole
lifecycle across any domain — and calls eds-mcp twice over: the finance mission drives
it to build compliant UI, and the optimize mission calls it to quantify a regulated
surface under review (guardrail mapping · regulatory anchors · WCAG token-contrast). The engine
resolves from --eds <path>, ED_AGENT_EDS_MCP, or a sibling ../eds-mcp; if absent, both run
in honest contract-only mode and every other mission is unaffected.
npm test# zero-dependency contract test: missions, skills, memory, gates
npm run test:mcp # live MCP-protocol test (needs the optional SDK)MIT © Ed Chen — edwson.com
{ "mcpServers": { "ed-agent": { "command": "npx", "args": ["-y", "github:Edwson/Ed-Agent", "ed-agent-mcp"] } } }