HyoDo
Open, model-agnostic evidence and verification for AI-assisted systems.
HyoDo is an open trust framework, delivered today as a public Python CLI for
fail-closed quality gates, evidence, and policy checks. Reuse the tests and
linters you already run. Missing evidence stays UNOBSERVED; review signals
never authorize approval.
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 |
Boundaries and current status
HyoDo provides local checks and evidence contracts; it does not grant execution
authority or turn missing evidence into a pass. hyodo safe is an early-warning
scan, not a full security audit, and callers must enforce DENY decisions. The
package stores evidence digests and receipts, not captured payloads. See the
product boundary, measured state snapshot,
and security model for the authoritative details.
The HyoDo Integrity Score is advisory only. The score command retains an older
method that combines five inputs with a geometric mean; HYOGOOK V5 is its
internal name. That compatibility method is being replaced. Current source
status may differ from the latest published package.
Use your existing CI
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install hyodo
- run: hyodo safe --strict --json
- uses: lofibrainwav/HyoDo/.github/actions/hyodo@vX.Y.Z
init detects existing test and lint tooling. Empty or malformed gate
configuration exits 2, not 0. See the gate configuration reference.
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.
mcp.hyodo.app is contract-only, not this path.
Install and support
Python 3.10+: pipx install hyodo or pip install -U hyodo.
- Docs index:
docs/README.md - Command contracts and first-run steps:
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.6
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.6.tar.gz | 292.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hyodo-4.19.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 585.7 kB
Release files / hyodo-4.19.6.tar.gz
| Download URL | hyodo-4.19.6.tar.gz |
|---|---|
| Size | 292.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e5bc7f08dfc6d04080d8f20bcd70bd357645941b0fa0032c0f93d11e04171bb
|
|
BLAKE2b-256 checksum How to use checksums |
1274dba5030a8c43256f0dec3f90f5aa6230f9348006858203eaff443b8db540
|
| 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 15, 2026.
Transparency logRelease files / hyodo-4.19.6-py3-none-any.whl
| Download URL | hyodo-4.19.6-py3-none-any.whl |
|---|---|
| Size | 293.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36951fabae489caec00cb477e5a8543922a32d599462a6739df75ed76484ed88
|
|
BLAKE2b-256 checksum How to use checksums |
84c9549119b6bff1bddca2e154209da02b4336134d7f167faaca5d3c76796bb2
|
| 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 15, 2026.
Transparency log
