HyoDo
Honest local guardrails for AI-assisted development.
HyoDo is a model-agnostic Python CLI that helps teams prove which checks ran, record agent actions, enforce local tool and path policy, and reuse existing tests and linters without turning missing evidence into a green result. Review signals never grant automatic approval. Unobserved is never green.
Why HyoDo exists
AI coding tools can move quickly, but a normal green check does not always answer:
- Did the check actually run?
- Did the agent touch only approved tools and paths?
- Was missing or unreadable evidence treated as a pass?
HyoDo makes those boundaries explicit with local evidence, policy decisions, and fail-closed exit contracts.
30-second start
pipx install hyodo
cd your-project
hyodo safe --strict
hyodo init
hyodo check
safe works immediately in any repository. init is optional: it detects
tools you already use and writes .hyodo/gates.toml; check then runs those
gates. No detected tooling means no invented green check. See
docs/GATES_SYNTAX.md for every gates.toml field.
Commit .hyodo/gates.toml and .hyodo/policy.toml (team-shared policy); keep
the rest of .hyodo/ out of version control — see
what to commit for the .gitignore split.
What it does
| Need | HyoDo surface |
|---|---|
| Early-warning safety scan | hyodo safe |
| Reuse existing project checks | hyodo init → hyodo check |
| Agent action audit trail | hyodo event record |
| Tool / path / step policy | hyodo policy check |
| Schema / eval / evidence report | hyodo schema, eval, report |
| Local evidence panel | hyodo dashboard --open |
| Optional MCP adapter | hyodo mcp stdio / serve |
| MCP diagnostics and audit | hyodo mcp doctor, access-log, rules |
| Onboarding, harness and host wiring | hyodo start, connect, mcp config |
| Lens, absorption, graph, eye | hyodo skills, inspect, graph, eye |
| Reader vocabulary, host continuity | --audience, hyodo mcp continuity |
Current claim lock
Measured Run #1: receipt.
| Capability | Status | Evidence boundary |
|---|---|---|
| gates / ledger / friction preview | SHIPPED | Local preview/export; ledger. |
| Graph v1 | SHIPPED (site DEMO FIXTURE) | Local dashboard; fixed demo site. |
| Graph v2 join | NOT BUILT | No join runtime/viewer; SCC oracle only. |
| Cursor/Codex hooks | UNOBSERVED | No verified host adapter. |
| remote MCP / ChatGPT | CONTRACT ONLY | Hosted contract; runtime unobserved. |
| ACL runtime / Wisdom Reflex | RESEARCH | Hypothesis; no automatic router. |
| friction collector | NOT BUILT | No collector/uploader; transport disabled. |
Honest boundaries
HyoDo is deliberately narrow:
- It is not a runtime sandbox or process interceptor.
hyodo safeis an early-warning scanner, not a full security audit.- A DENY result must still be enforced by the caller.
- HyoDo Integrity Score: advisory only, never approval; HYOGOOK V5 lineage.
- The public MCP server supports loopback or authenticated Tailscale binding;
public
0.0.0.0listeners are not supported. - Missing, unreadable, or unmeasured evidence is never reported as healthy.
- Embeddings, model calls, capture tools, and remote inventories stay outside the package: HyoDo keeps digests, hashes, and receipts, never the payload.
Use your existing CI
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install hyodo
- run: hyodo safe --strict --json
Composite action: pin a signed ref; SARIF needs security-events: write.
- uses: lofibrainwav/HyoDo/.github/actions/hyodo@vX.Y.Z
hyodo init && hyodo check
init can absorb pytest, Ruff, mypy, Pyright, npm scripts, Go, Cargo, and
Makefile targets. Empty or malformed gate configuration exits 2, not 0.
Hooks and SARIF
Pin a signed release containing the hooks (v4.11.0 predates them):
- repo: https://github.com/lofibrainwav/HyoDo
rev: vX.Y.Z
hooks: [{id: hyodo-check}, {id: hyodo-safe-strict}]
hyodo report --format sarif writes a SARIF 2.1.0 visibility report.
Measured DENY and unreadable-ledger conditions become alerts; hyodo check
remains the fail-closed gate for missing or unmeasured quality evidence.
Optional agent evidence
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 event storage is digest-only. See
examples/fde-evidence-spine/ for a demo
event and examples/host-policies/ for a
dual-host allowed_tools list (not a Cursor hook). Policy trust:
docs/POLICY_TRUST.md.
Optional MCP
pip install 'hyodo[mcp]'
hyodo mcp stdio --root . # local stdio
hyodo mcp serve --bind tailscale --bind-ip 100.99.88.77 \
--token "$HYODO_MCP_TOKEN" --root . # private-network connector
The MCP adapter uses the same CLI contracts rather than a second engine.
SDK v1/v2 are in CI. mcp.hyodo.app is contract-only, not this path.
Exit contracts
| Command | Contract |
|---|---|
safe |
0 report · 1 strict high finding · 2 bad path |
check |
0 executed gates passed · 1 gate failed · 2 none/malformed |
event, policy |
0 valid/ALLOW; 1 invalid/DENY; 2 unobserved; 3 ASK |
schema check |
0 valid · 1 validation error · 2 unobserved input |
Engineering model
See PHILOSOPHY.md for evidence pillars and score lineage.
Install and support
Python 3.10+: pipx install hyodo or pip install -U hyodo.
- Docs index:
docs/README.md - Quick start:
QUICK_START.md - Node.js:
docs/onboarding-nodejs.md - Security:
SECURITY.md; Issues: GitHub Issues - Contributing:
CONTRIBUTING.md; Changelog:CHANGELOG.md
License
MIT. See LICENSE.
1 maintainer
Release files for hyodo 4.19.1
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.19.1.tar.gz | 472.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hyodo-4.19.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 744.7 kB
Release files / hyodo-4.19.1.tar.gz
| Download URL | hyodo-4.19.1.tar.gz |
|---|---|
| Size | 472.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cec249c7d77d1bb43bc53142cb3647fd32d2cbfa27c1f081d38c32dae4d9b12c
|
|
BLAKE2b-256 checksum How to use checksums |
22ef591b5ad5a9cc26eca4fb79af2407de2e3fcaff3678d1bf39ff45796d16a3
|
| 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 10, 2026.
Transparency logRelease files / hyodo-4.19.1-py3-none-any.whl
| Download URL | hyodo-4.19.1-py3-none-any.whl |
|---|---|
| Size | 272.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4a3cb7c68246ddf9e13e16562cfda4ab79364855f8d30bea08b32b98252f509
|
|
BLAKE2b-256 checksum How to use checksums |
ff5f51621722852f7914240e1c00ab121122b33ff38c6b9ea89f02ec589b740d
|
| 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 10, 2026.
Transparency log
