HyoDo
See which checks ran on AI-assisted work, what they found, and what remains unknown.
HyoDo is an open-source Python tool that runs on your computer. It reuses the
tests and linters your project already has, reports their results, and marks
missing evidence UNOBSERVED. That means there is not enough evidence to say
whether a check passed or failed. HyoDo helps people review work; it does not
approve merges or deployments.
Why HyoDo exists
HyoDo helps you inspect AI-assisted work: which project checks ran, what they found, and what remains unknown. Its guiding idea, Hyo (孝), is that technology should respect people's time and choices, and carry its share of the burden instead of passing it back to them. HyoDo records evidence; people decide what to do with it.
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 legacy HyoDo Integrity Score command is advisory only. It retains a
five-input geometric-mean method for compatibility; HYOGOOK V5 is its
internal name.
HyoDo's replacement evaluation model is being updated; it does not define the
six reference values as one canonical score. The current package does not yet
provide a general per-axis evaluator. 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. For an unattended feature queue
that calls these gates from a host loop, see
examples/factory-loop/.
Optional MCP
pip install 'hyodo[mcp]' # pipx: pipx install --force '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 extra has to land in the same environment that runs hyodo; a pipx
install is isolated, so pip install 'hyodo[mcp]' after pipx install hyodo
installs into a different interpreter and the SDK stays missing.
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.20.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.20.0.tar.gz | 331.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hyodo-4.20.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 658.2 kB
Release files / hyodo-4.20.0.tar.gz
| Download URL | hyodo-4.20.0.tar.gz |
|---|---|
| Size | 331.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37038649bce6cb879bae21670611232bad65b955f2b81ac2a17ae5c9f43dba40
|
|
BLAKE2b-256 checksum How to use checksums |
e41e4f8a7dac5c6bbd92d0b89a9ad3f1f61ecd36a890b1f86e2958c459b7a197
|
| 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 20, 2026.
Transparency logRelease files / hyodo-4.20.0-py3-none-any.whl
| Download URL | hyodo-4.20.0-py3-none-any.whl |
|---|---|
| Size | 327.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b96759ca26c067e9c12890ebf9a6b88011df541002840002ae0c7fd1fedb735b
|
|
BLAKE2b-256 checksum How to use checksums |
1382c72b510028e2f1c5340945e00e1b356795b82e8746a2d0f7d127c9cb1ff5
|
| 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 20, 2026.
Transparency log
