HyoDo
Local AI agent guardrails for FDE work and CI — audit evidence, policy DENY, fail-closed quality gates.
Not a pre-commit clone. HyoDo helps Forward Deployed Engineers and AI-assisted teams prove what ran, block unauthorized tools, and absorb your existing tests/linters without replacing them.
Review signals never grant automatic approval. Unobserved is never green.
Why HyoDo (vs pre-commit alone)
| Need | HyoDo |
|---|---|
| Agent step audit trail | event record → .hyodo/agent-events.jsonl |
| Tool / path / step policy | policy check (ALLOW / DENY; missing = exit 2) |
| Keep existing CI tools | BYOG init absorbs pytest/ruff/npm/go/… |
| Fake-green resistance | fail-closed score + SKIP ≠ PASS |
| Air-gapped / on-prem | loopback dashboard, offline-safe design |
pre-commit + ruff is still excellent for hooks. HyoDo adds agent
evidence + policy gates + honest measurement for FDE deployment defense.
Start here (any repository)
pipx install hyodo
cd your-project
hyodo safe # early-warning scan, no setup
hyodo safe --strict # exit 1 on high-severity findings
hyodo safe --json # machine-readable findings for CI
# GitHub Actions
- run: pipx install hyodo
- run: hyodo safe --strict --json
hyodo safe is an early-warning scanner, not a full security audit.
Bring your own gates (optional)
hyodo init # detect tools → write .hyodo/gates.toml
hyodo check # run absorbed gates
hyodo dashboard --open # local evidence panel (127.0.0.1)
init reads tooling you already own (pytest/ruff/mypy/pyright,
npm scripts, go.mod, Cargo.toml, Makefile targets). It does not
reinvent them. Empty detection → commented starter (no guessing).
Malformed or zero executed gates → exit 2 (not a pass).
Agent evidence spine (opt-in FDE)
hyodo event validate --file step.json
hyodo event record --file step.json --root . --policy .hyodo/policy.toml
hyodo policy check --file step.json --config .hyodo/policy.toml
hyodo schema check --schema agent.schema.json --payload step.json --json
Default storage is digest-only. DENY is recorded for audit; the
caller must stop the agent — HyoDo is a gate, not a runtime
interceptor. Examples: examples/fde-evidence-spine/.
schema check validates a local JSON payload deterministically. It returns
0 for valid, 1 for a schema violation, and 2 when the schema or payload
cannot be observed or trusted. --json emits structured reasons for tools.
Optional local MCP stdio
pip install 'hyodo[mcp]'
hyodo mcp stdio --root .
This starts a local standard-input/output MCP process only. It wraps the
existing safe, check, event record, and policy check CLI contracts
for the configured host workspace. It never opens a network listener or
exposes files outside that workspace.
Optional private-network MCP
hyodo mcp serve --bind tailscale --bind-ip 100.99.88.77 \
--token "$HYODO_MCP_TOKEN" --root .
This explicit connector binds only to the supplied Tailscale 100.64.0.0/10
address and requires a non-empty bearer token before it listens. It serves the
host workspace only; a second device must be on the same private network and
does not gain access to its own unrelated files. Public listeners are not
supported.
Engineering map (branding kept, terms first)
| DevSecOps label | Pillar | Measured by |
|---|---|---|
| Static types | Truth (眞 / 진) | Command gate (typechecker) |
| Tests + safety | Goodness (善 / 선) | Tests + safe |
| Lint / format | Beauty (美 / 미) | Command gate (linter) |
| Public surface | Benevolence (仁 / 인) | Native AST scan |
| Data privacy | Hyo (孝 / 효) | Native consent/data scan |
| Audit trail | Yeong (永 / 영) | .hyodo/history.jsonl |
Command gates are absorbed tools. AST / ledger pillars are never
shell-faked. Missing sources show Not measured. Fail-closed geometric
mean (HYOGOOK V5 formula, philosophy V6 labels): any pillar at 0
collapses the review signal. Detail: PHILOSOPHY.md.
Local instrument panel
hyodo dashboard --open
# → http://127.0.0.1:8768
Loopback only; 15s poll of /api/evidence; no composite invention.
Measure again now is token-protected.
Install
Python 3.10+. pip install -U hyodo or pipx install hyodo.
See Quick Start.
Commands
| Command | Purpose |
|---|---|
hyodo safe |
Safety findings (early warning) |
hyodo init |
Write .hyodo/gates.toml (BYOG) |
hyodo check |
Absorbed gates or checkout preset |
hyodo event … |
Agent event validate / record |
hyodo policy check |
Agent policy ALLOW / DENY |
hyodo schema / eval / report |
Local validation, eval, evidence report |
hyodo mcp stdio |
Optional local MCP CLI adapter |
hyodo mcp serve |
Explicit loopback or authenticated Tailscale MCP adapter |
hyodo mcp doctor |
Diagnose local MCP setup |
hyodo mcp access-log / rules |
MCP audit trail / agent rules |
hyodo score … / dashboard |
Optional review signal / evidence panel |
safe: 0 findings · 1 high+--strict · 2 bad path.
check: 0 all executed PASS · 1 FAIL · 2 none/malformed.
event/policy: 0 ok/ALLOW · 1 invalid/DENY · 2 unobserved.
schema check: 0 valid · 1 validation error · 2 unobserved input.
Scope
| Surface | Status |
|---|---|
hyodo/ package and CLI |
Public release surface |
tests/ and CI workflows |
Release verification |
Model-agnostic ≠ language-agnostic. Export PDF audit packs and full runtime interceptors are roadmap items — not claimed shipped.
For contributors
git clone https://github.com/lofibrainwav/HyoDo.git && cd HyoDo
python -m venv .venv && source .venv/bin/activate
python -m pip install -e ".[dev]" && ./.venv/bin/hyodo check
Documentation
License
HyoDo is available under the MIT License.
1 maintainer
Release files for hyodo 4.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hyodo-4.11.0.tar.gz | 160.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hyodo-4.11.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 247.6 kB
Release files / hyodo-4.11.0.tar.gz
| Download URL | hyodo-4.11.0.tar.gz |
|---|---|
| Size | 160.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3e44153f48d54ce388b33961d409aa46a30366f209be3d92cf5ccd229d4d28f8
|
|
BLAKE2b-256 checksum How to use checksums |
dd2faed92df8f477f537f166635dc087ecc612cddfb82ee370ac419982412b20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / hyodo-4.11.0-py3-none-any.whl
| Download URL | hyodo-4.11.0-py3-none-any.whl |
|---|---|
| Size | 86.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
19162f13a97986285b8e70843fc9572b92941919bf022674d5a716304f2d5e03
|
|
BLAKE2b-256 checksum How to use checksums |
fa149b7154c3fa3b626862a4431ce28a156ccaeeaf5cb52f905a4ca60f9c1552
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency log
