shugo 0.1.0

A practical, readable AI agent guardrails framework —
and a working example of how agents should be governed.

Documentation · Quickstart · Repo Structure · Policies · Roadmap

shugo_repo  ->  shugo_policy  ->  shugo_runtime

🧱 Five Guardrail Layers

Layers ③ and ⑤ ship complete in v0.1. The others ship at the minimum depth needed to make those two credible, then deepen along the roadmap.

⚙️ How it works

SHUGO presents itself to your agent as a standard MCP server and sits between the agent and the tools it calls. Every tools/call is evaluated against a human-readable policy file before it reaches an upstream server. No protocol changes. No agent code changes.

┌──────────────┐   MCP    ┌───────────┐   MCP    ┌──────────────────┐
│  MCP client  │ ───────▶ │   SHUGO   │ ───────▶ │ Upstream MCP     │
│ (any agent)  │ ◀─────── │   guard   │ ◀─────── │ servers (n)      │
└──────────────┘          └─────┬─────┘          └──────────────────┘
                                │
                    ┌───────────┼───────────┐
                    ▼           ▼           ▼
              guardrails    audit log    approval
                 .yaml      (JSONL)       channel

Works with Claude Desktop, Claude Code, Cursor, VS Code, and any framework with an MCP adapter — LangGraph, CrewAI, the OpenAI Agents SDK, n8n.

⚡ Quickstart

uvx shugo init      # scaffold a policy from your existing MCP config
uvx shugo serve     # start guarding

Point your MCP client at SHUGO instead of your servers:

{
  "mcpServers": {
    "shugo": {
      "command": "uvx",
      "args": ["shugo", "serve", "--config", "guardrails.yaml"]
    }
  }
}

Your agent now sees only the tools policy allows, blocks on anything needing approval, and writes an audit record for every call it makes.

📜 Policy as code

The most important file in the project. Design target: a risk lead can read it unaided, and a reviewer can diff it in a pull request.

version: "0.1"

defaults:
  decision: deny            # deny by default; allowlist upward
  on_error: deny            # fail closed

rules:
  - id: read-only-github
    match:
      server: github
      tool: ["get_*", "list_*", "search_*"]
    decision: allow

  - id: no-force-push
    description: Force push can destroy history irrecoverably
    match:
      server: github
      tool: push
      args: { force: true }
    decision: deny
    reason: Force push is prohibited for autonomous agents.
    controls: [OWASP-LLM06, NIST-AI-RMF-MANAGE-2.2]

  - id: ticket-write-needs-approval
    match:
      server: tickets
      tool: ["update_ticket", "close_ticket"]
    decision: escalate
    approval:
      channel: cli
      timeout_seconds: 300
      on_timeout: deny
    controls: [EU-AI-ACT-ART-14]

Deny by default. First match wins, top to bottom. Globs, not regex — readability is the constraint.

🧾 Evidence, not just logs

Enforcement without evidence is unauditable. Evidence without enforcement is theatre. SHUGO does both.

shugo evidence --framework owasp-llm --since 30d --out evidence/

Reads the audit log and produces a control-by-control bundle: which rules were in force, how often each fired, approval latency, exceptions, coverage gaps, and a hash-chain integrity check.

Framework mappings ship as data files sourced from public standards only — NIST AI RMF, EU AI Act, OWASP Top 10 for LLM Applications, and ISO/IEC 42001 control identifiers.

Scope note. SHUGO produces evidence about the guardrail layer. It does not certify an organisation as compliant with any standard.

🧰 CLI

🗺️ Roadmap

🤝 Contributing

SHUGO is built in public, and the contribution ladder is deliberately low to the ground:

policy pack → scenario test → framework mapping → core

A new policy pack is a self-contained YAML file. You do not need to read the codebase to ship one. Start with CONTRIBUTING.md and the good first issues.

📄 License

Released under the MIT License. Use it, fork it, adapt it to your own agent architecture — that is the point.

_{守護 — shugo, to guard and protect.}