AgentSeed

The anti-hallucination gate for AI coding agents.

AI agents invent APIs. They claim "all tests pass" without running anything. They ship confident, fabricated code. AgentSeed is the gate that stops it — a zero-dependency plugin that verifies code before it is marked done, so "done" means observed fact, not self-report.

English · 中文 · 日本語

⭐ Like this project? Star it — it helps developers find guardrails before they ship hallucinated code.

Why you need this

LLMs hallucinate — and in code that means invented APIs, undefined identifiers, fake test passes, and confident overclaims:

• 15.1% of code hallucinations call APIs that don't exist or were never imported (arXiv:2404.00971).
• <10% of hallucinated code fails tests — ~90% slips past CI (arXiv:2404.00971).
• 60%+ of model-output errors are unverifiable on their face (FAVA, SoK).

Prompt-only guardrails are soft: a model can agree to verify and then skip it. AgentSeed binds the instruction to a hard gate — the evidence comes from running code, not from the model's own word.

What AgentSeed is — in 30 seconds

A drop-in Agent Plugins 1.0.0 plugin (Skill + MCP server + optional client hook + CI gate) that makes three promises:

It also fills the two gaps the 1.0.0 spec deliberately leaves open:

See it catch a hallucination

# Your coding agent just "finished" this — it calls magic_unknown(),
# an API that doesn't exist and was never imported:

def f():
    return magic_unknown()      # ← hallucinated API

# AgentSeed, before the task can be marked done:
$ verify_code(source=..., language="python")
{
  "language": "python",
  "suspects": ["magic_unknown"]       # ← caught, blocking
}

# And the agent's completion claim doesn't survive either:
"The feature is production ready, all tests pass. Trust me."

$ scan_hallucination(source=...)
{
  "hits": [
    {"word": "all tests pass",   "group": "oversold",  "line": 1},
    {"word": "production ready", "group": "oversold",  "line": 1},
    {"word": "trust me",         "group": "oversold",  "line": 1}
  ],
  "clean": false                        # ← caught, blocking
}

The verdict is measured, not promised: on a seeded synthetic corpus (5 defect classes, 100 defective + 40 clean modules) AgentSeed scores precision 1.0 · recall 1.0 (tp=100, fp=0, fn=0) — locked in by a regression test. Methodology and honest limits: docs/BENCHMARK.md.

How the gate works

1. Before coding — load the SDD contract and state it in one sentence.
2. Implement — real code only: no placeholders, no invented APIs.
3. Before "done" — run verify_code + scan_hallucination; prove runtime claims with sandbox_run; validate structure with schema_validate.
4. Language audit — completion reports attach evidence; overclaim vocabulary is banned.
5. Only when all checks pass may the task be marked complete.

Quick start

Option A — download a release (no git needed):

# grab the latest asset from https://github.com/Morningstar202604/agentseed-mcp/releases
# or use the installer, which wires it into your client:
bash install.sh --client auto --hooks        # macOS / Linux
./install.ps1 -Client auto -Hooks            # Windows PowerShell
# --client: claude | opencode | cursor | manual
# --hooks / -Hooks: also register the Claude Code enforcement hook

Option B — clone:

git clone https://github.com/Morningstar202604/agentseed-mcp.git
# mirrors: https://gitee.com/badhope/agentseed-mcp · https://gitcode.com/badhope/agentseed-mcp

1. Drop the cloned agentseed-mcp/ directory into any Agent Plugins–capable client (Cursor, VS Code, Claude Code, Copilot…). No build, no install.
2. The client auto-discovers the verify-before-code skill and the agentseed MCP server from plugin.json + mcp.json.
3. That's it. Every coding task is now gated: contract → implement → verify → evidence.

Run it standalone or gate a human PR with the same rules:

python3 server/guard_engine.py                       # self-check demo
python3 -m unittest discover -s server               # full unit-test suite
python3 server/guard_cli.py gate --root .            # CI-equivalent hard gate
python3 server/guard_cli.py check . --ci             # plugin conformance only
python3 server/guard_cli.py verify src/app.go        # language inferred from the suffix
python3 server/guard_cli.py scan src/app.py --strict # inline or file, hallucination signals
python3 server/guard_cli.py scan . --baseline baseline-scan.json  # tree sweep, new signals only

Windows note: mcp.json may only name one literal interpreter, and it ships python3 (right for macOS/Linux/WSL). On Windows run ./install.ps1, which rewrites command to python in the installed copy, or edit it by hand as "command": "python" with "args": ["server/guard_server.py"] — command is a string, the array belongs to args. npx agentseed-mcp needs no editing at all: the npm shim picks the interpreter per platform.

The 8 MCP tools

Zero required dependencies — pure Python standard library; optional extras upgrade two tools to industry-standard engines (see below).

Language coverage (honest scope)

Honest limits: attribute calls (obj.m()), macros, and cross-file symbols are not analyzed; Ruby's paren-less calls are supported.

Honest limits: attribute calls (obj.m()), macros, and cross-file symbols are not analyzed; Ruby's paren-less calls are supported.

It really catches other languages — live-tested

The same rule applies to every registered language: a bare call to a symbol that is never defined is a hallucination, whatever the syntax:

# Go       detect_undefined_symbols("func main() { process_data() }", "go")  -> ["process_data"]
# Rust     fn main() { let x = load_config() }        -> ["load_config"]
# Java     class A { void m() { connect_db() } }      -> ["connect_db"]
# C        int main() { ghost(); return 0; }          -> ["ghost"]
# Kotlin   fun main() { fetch_users() }               -> ["fetch_users"]
# Swift    func run() { connect() }                   -> ["connect"]
# Ruby     def run; authenticate; end                 -> ["authenticate"]
# TypeScript function run() { connectDb() }           -> ["connectDb"]

Verified across Go · Rust · Java · C · C++ · C# · PHP · Ruby · Kotlin · Swift · TypeScript · Dart · Lua · R · Zig — every language flags its invented call, and clean code in each language reports zero false positives.

Client-enforced hook mode

Skills persuade; hooks enforce at the client boundary. Register AgentSeed as a Claude Code hook and every Write/Edit/MultiEdit is scanned automatically — no prompt can skip it:

python3 server/guard_hook.py register --client claude   # idempotent, merges settings
python3 server/guard_hook.py --file path/to/source.py   # scan any file directly

• PreToolUse inspects the incoming content before it lands on disk; a blocking finding exits 2, and the agent must fix the flagged lines.
• PostToolUse re-checks saved files on write paths without inline content.
• Failure policy (honest): infrastructure problems (bad stdin, unreadable files) never block work — fail-open; only positive scan findings block.

Platform support

* honest states: formats are spec-compatible and expected to work, but not yet exercised by the maintainers. If you verify one, open a PR updating this table.

Optional dependencies

pip install -r server/requirements.txt

Configuration (agentseed.config.json)

Unknown keys are warned on stderr — a typo is never silently ignored.

⚠️ Security note: sandbox_run executes real processes with your user's permissions. Gate it behind user approval; set sandbox_allowed_prefixes in shared/CI environments. Commands resolve through PATH to absolute paths before execution, so a hostile cwd cannot shadow an allowlisted binary; unmatched commands are refused (exit -10) without running.

Compatibility & graceful degradation

Built-in guardrail library (EN / 中文 / 日本語)

PROMPT-POOL (copy-paste guardrail prompts) · HALLUCINATION-PATTERNS (failure-mode catalog) · VERIFICATION-CHECKLIST (executable end-of-task checklist) · SDD-CONTRACT (the contract every task must satisfy) · DEFAULT-NORMS (senior-engineer operating norms, mapped to the gate that enforces each; English only) · VENDOR-SOLUTIONS (adoption map of vendor techniques). Every library lives under skills/verify-before-code/references/, and the SKILL files list them.

Why AgentSeed vs. alternatives

FAQ

Does it need a specific LLM? No — client-agnostic and model-agnostic; the gate is enforced by skill + MCP + hooks + CI, not by any model.

Zero dependencies? Yes. The MCP server is pure Python standard library.

Does it work with our existing AGENTS.md / CLAUDE.md? Yes — it complements them. Those files carry project facts (prose, persuasive); AgentSeed carries the behavior contract and the hard enforcement.

How do I extend it to another language? Add a LangSpec registry entry in server/engine/symbols.py — one config, no engine change.

Contributing

Issues, PRs and ideas welcome — or open an issue for a hallucination pattern we haven't catalogued yet. See CONTRIBUTING.md.

License

Apache-2.0 © AgentSeed. See LICENSE.