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://gitcode.com/badhope/AgentSeed/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://gitcode.com/badhope/AgentSeed.git
# mirrors: https://gitcode.com/badhope/AgentSeed · https://gitee.com/badhope/AgentSeed

1. Drop the AgentSeed/ 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      # 160+ unit tests
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 scan src/ --strict

Windows note: mcp.json launches the server via python3. On many
Windows installs that alias is a Microsoft Store stub; change command to
["python", "server/guard_server.py"] or use your interpreter's absolute path.

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 — 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 (20+ copy-paste guardrail prompts) · HALLUCINATION-PATTERNS
(5-class failure-mode catalog) · VERIFICATION-CHECKLIST (executable
end-of-task checklist) · SDD-CONTRACT (the contract every task must
satisfy) · VENDOR-SOLUTIONS (adoption map of vendor techniques).

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.