🛡️ AgentSeed

Why AgentSeed

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

• 15.1% of code hallucinations are knowledge-conflicting: calling APIs that don't exist or were never imported (arXiv:2404.00971).
• <10% of hallucinated code fails tests — most slips through CI (arXiv:2404.00971).
• 60%+ of model-output errors are unverifiable — no way to tell fact from fiction (FAVA, cited in SoK).

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

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

What it does

Five MCP tools — zero required dependencies, enhanced by optional extras:

Live demo

$ verify_code(source="def f():\n    return magic_unknown()\n", language="python")
{
  "language": "python",
  "suspects": ["magic_unknown"]      # ← hallucinated API caught
}

$ scan_hallucination(source="The feature is production ready, all tests pass. Trust me.")
{
  "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                      # ← overclaim caught
}

$ check_plugin(path="/path/to/AgentSeed")
{ "ok": true, "errors": [], "warnings": [] }   # ← strict 1.0.0 conformance

Quick start

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

# grab the latest asset from https://github.com/weed33834/AgentSeed/releases
# or use the installer, which drops it into a client of your choice:
bash install.sh --client auto        # macOS / Linux
./install.ps1 -Client auto           # Windows PowerShell
# --client: claude | opencode | cursor | manual

Option B — clone:

git clone https://github.com/weed33834/AgentSeed.git
# or: https://gitcode.com/badhope/AgentSeed · https://gitee.com/badhope/AgentSeed

1. Drop the AgentSeed/ directory into any client that supports Agent Plugins 1.0.0 (Cursor, VS Code, Claude Code, Copilot…). No build, no install; zero required dependencies (optional extras below).
2. The client auto-discovers the verify-before-code skill and the agentseed MCP server from plugin.json + mcp.json.
3. That's it. The skill now gates every coding task: contract → implement → verify → evidence.

Run it standalone for a self-check:

python3 server/guard_engine.py              # conformance + demos
python3 -m unittest discover -s server      # 50+ unit tests

Gate a human PR with the same rules (CI mode):

python3 server/guard_cli.py check . --ci    # plugin conformance, exit 1 on errors
python3 server/guard_cli.py scan src/ --strict   # hallucination scan, blocking severities only

Windows note: mcp.json launches the server via python3. On manyWindows installs that alias is a Microsoft Store stub; if the server failsto start, change command to ["python", "server/guard_server.py"] orpoint it at your interpreter's absolute path.

Optional dependencies

AgentSeed runs on the Python standard library alone. Installing the extrasupgrades two tools to industry-standard engines (auto-detected, gracefulfallback either way):

pip install -r server/requirements.txt

Use an absolute path to guard_server.py; the server resolves everythingelse from its own location, so no special cwd is required.

Compatibility & graceful degradation

AgentSeed adapts to whatever the host supports, degrading one level at a time— never silently skipping verification:

The skill itself carries the degradation path: when the MCP tools are absent,it instructs the agent to run guard_cli.py verify/scan through the shell andapply the same blocking rules to exit codes.

Platform support

* honest states: the formats are spec-compatible and expected to work, but wehave not run AgentSeed in these clients ourselves. Verified = actually exercisedby the maintainers. If you verify one, open a PR updating this table.

Clients honoring the full spec also set ${PLUGIN_DATA}; AgentSeed readsagentseed.config.json from there (allowlist, severity map, sandbox timeout).

Client setup — exact configuration

AgentSeed has two halves; both are needed for the full gate:

1. Skill (skills/verify-before-code/) — teaches the agent the workflow.
2. MCP server (server/guard_server.py) — provides the 5 tools.

The installers wire step 1 and print step 2 for your client. Manual setup:

Claude Code

# skill: copy it flat so SKILL.md sits directly in the folder
cp -R skills/verify-before-code ~/.claude/skills/verify-before-code
# MCP server:
claude mcp add agentseed -- python /path/to/AgentSeed/server/guard_server.py

opencode — copy skills/verify-before-code/ to~/.config/opencode/skill/verify-before-code, then add to opencode.json:

{
  "mcp": {
    "agentseed": {
      "type": "local",
      "command": ["python", "/path/to/AgentSeed/server/guard_server.py"],
      "enabled": true
    }
  }
}

Cursor / other MCP clients — register a stdio server withcommand: python, args: ["/path/to/AgentSeed/server/guard_server.py"],and copy the skill folder per your client's skills location.

Use an absolute path to guard_server.py; the server resolves everythingelse from its own location, so no special cwd is required.

Changelog

See CHANGELOG.md.

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

How the gate works

1. Before coding — load the SDD contract, state it in one sentence.
2. Implement — real code only: no placeholders, no invented APIs.
3. Before "done" — call 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.

Why AgentSeed vs. alternatives

Roadmap

• Hybrid Skill + MCP guardrail, 5 tools — first strict 1.0.0 linter
• Prompt pool + pattern library + grouped signals + vendor techniques
• verify_code for TypeScript / JavaScript (zero-dependency lexical pass)
• verify_code for Go
• Grammar-constrained decoding for structured outputs
• Optional remote fact-checker (HHEM-style) MCP server

FAQ

Does it need a specific LLM? No — it's client-agnostic and model-agnostic. The gate is enforced by the skill + MCP server, not by any model.

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

Conformant? check_plugin validates the plugin against 1.0.0 §5/§6/§7 — and AgentSeed passes its own linter (ok: true).

Contributing

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

License

MIT © AgentSeed. See LICENSE.