AgentSeed

Why you need this

LLMs hallucinate — and in code that means invented APIs, undefinedidentifiers, 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 skipit. AgentSeed binds the instruction to a hard gate — the evidence comesfrom 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 threepromises:

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 scoresprecision 1.0 · recall 1.0 (tp=100, fp=0, fn=0) — locked in by aregression 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 runtimeclaims with sandbox_run; validate structure with schema_validate.
4. Language audit — completion reports attach evidence; overclaimvocabulary 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 theagentseed 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 itships 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 arraybelongs to args. npx agentseed-mcp needs no editing at all: the npm shimpicks the interpreter per platform.

The 8 MCP tools

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

Language coverage (honest scope)

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

Honest limits: attribute calls (obj.m()), macros, and cross-file symbolsare 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 symbolthat 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 itsinvented call, and clean code in each language reports zero falsepositives.

Client-enforced hook mode

Skills persuade; hooks enforce at the client boundary. Register AgentSeedas a Claude Code hook and every Write/Edit/MultiEdit is scannedautomatically — 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; ablocking 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, unreadablefiles) never block work — fail-open; only positive scan findings block.

Platform support

* honest states: formats are spec-compatible and expected to work, but not yetexercised 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'spermissions. Gate it behind user approval; set sandbox_allowed_prefixes inshared/CI environments. Commands resolve through PATH to absolute pathsbefore 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-taskchecklist) · SDD-CONTRACT (the contract every task must satisfy) ·DEFAULT-NORMS (senior-engineer operating norms, mapped to the gate thatenforces each; English only) · VENDOR-SOLUTIONS (adoption map of vendortechniques). Every library lives underskills/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; thegate 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 — itcomplements 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 inserver/engine/symbols.py — one config, no engine change.

Contributing

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

License

Apache-2.0 © AgentSeed. See LICENSE.