shugo

Documentation · Quickstart · Repo Structure · Policies · Roadmap

A guardrail should not merely tell an agent what it should do. The system should enforce what the agent is allowed to do.

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.

Related MCP server: flux7-mesh

⚡ 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

📦 Release notes — v0.1.0 (2026-07-30)

First release. Everything in the sections above is now real code you can install with uvx shugo.

What ships:

• Guard proxy over stdio — SHUGO speaks MCP to both your client and any number of upstream servers, namespaces tools as <server>__<tool>, and applies policy on every tools/call.

• Policy engine — deny-by-default, first-match-wins, fnmatch globs on server/tool, nested-equality on args. Decisions: allow, deny, escalate.

• Human approvals — file-drop queue at ~/.shugo/pending/ resolved by either shugo approve --watch (Rich TUI) or an opt-in local HTTP UI (shugo serve --approvals http).

• Hash-chained audit log — append-only JSONL, rolling SHA-256, NFC-canonical JSON, per-line fsync. shugo audit verify detects any post-hoc edit.

• Evidence bundles — shugo evidence -f <owasp-llm|nist-ai-rmf|eu-ai-act|iso-42001> produces a control-mapped report, policy snapshot, filtered audit-log window, and SHA-256 manifest.

• shugo init — reads Claude Desktop / Code / Cursor / VS Code MCP configs, enumerates upstream tools, writes a starter policy, prints the exact JSON snippet to paste.

• Kill switch — shugo halt denies everything until shugo unhalt.

Quality: 102 fast tests + 1 e2e test (real @modelcontextprotocol/server-filesystem via npx). CI on Python 3.11–3.13 × macOS / Ubuntu / Windows. All dependencies MIT / BSD-3 / Apache-2.0; no copyleft, no BSL.

Full changelog: CHANGELOG.md · GitHub release: v0.1.0

🗺️ 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.