Project Oracle 🧠
Your AGENTS.md says npm run test. The repository deleted that script six
months ago. Every coding agent reads the context file as truth and nobody
checks it. Project Oracle checks it: which lines the repository backs, which it
contradicts, and which are unfalsifiable noise — then writes the file in the
first place when you don't have one.
Zero dependencies: pure Python 3.11+ standard library, cross-platform (Windows, Linux, macOS).
The problem
A context file rots exactly the way any untested doc rots. A script gets renamed, a folder is deleted, a "convention" is copied from another project — and the agent follows all of it with total confidence, then spends your tokens rediscovering what the repository already knew. It is the one file in the repo that nothing verifies.
Audit the file you already have
pipx install project-oracle
oracle-lint AGENTS.md
Three verdicts, each one earned against the repository rather than guessed:
| Verdict | Means | Real output |
|---|---|---|
| ✗ contradicted | the repo disproves the rule | `npm run test` does not exist (scripts: build, lint, start) |
| ⚠ noise | nothing in it is checkable | no definition of 'clean' to verify against |
| ✓ verified | the repo backs the rule | `npm run build` exists in package.json |
It judges a rule by looking for the claim inside it: a cited script against
package.json, a declared tool (pytest, vitest, jest, eslint, ruff,
black, mypy, prettier, typescript) against the manifests, a cited config
file against the filesystem — any path or dotted name (config/ruff.toml,
tsconfig.build.json) plus recognisable names like tsconfig.json,
pyproject.toml or docker-compose.yml — and a TypeScript strict claim
against tsconfig.json. A citation introduced by "add" or "create" is advice
about a file that does not exist yet, not a false description of the repository,
so it is left alone. Anchored rules it cannot judge are reported as not judged
instead of being silently counted — --all lists them.
Exit is non-zero when too much of the file is noise, so it can gate CI:
oracle-lint AGENTS.md --max-noise 20 # allow 20% noise (default 50)
oracle-lint CLAUDE.md --strict # any noise at all fails
oracle-lint AGENTS.md --json # machine-readable
Works on files you did not generate. That is the point: an agent wrote your
CLAUDE.md, or you copied it from another project, or it drifted for a year
while nobody read it.
Stop the drift in CI
oracle-check re-reads the repository and exits non-zero when the generated
context no longer matches it — so the stale file fails the build instead of
lying to the next agent:
oracle-check --path . --agents AGENTS.md
As a GitHub Action, with no install step — it runs the scripts from its own checkout:
- uses: actions/checkout@v5
- uses: iruzen-dono/project-oracle@v2
with:
agents: AGENTS.md
lint: "true" # also audit the file for noise
max-noise: "20" # fail above 20% noise
Generate the file
When there is no context file yet, the scanner writes one — and it keeps the part no scan can see. It interviews you for the project's intent and known pitfalls, then embeds both, so the agent reads the landmines before it touches code.
# 1. Scan a project (writes <project>/.oracle/scan-report.json,
# and adds .oracle/ to the project's .gitignore when missing)
oracle-scan --path /path/to/project --output /path/to/project/.oracle/
# 2. Generate AGENTS.md, embedding the interview answers
oracle-generate \
--scan .oracle/scan-report.json \
--template agents-md \
--output /path/to/project/AGENTS.md \
--intent-file .oracle/intent.json
# 3. (Optional) push a note into your Obsidian vault
oracle-vault --scan .oracle/scan-report.json --vault ~/Documents/"Obsidian Vault"
Four templates (agents-md, claude-md, an Obsidian note, or all in one pass),
--output accepting a directory (.oracle/ or .oracle) or an explicit JSON
file path, and safe regeneration: content between <!-- oracle:start/end -->
markers is refreshed in place so your edits outside survive; anything else
requires --force and keeps a .bak backup.
What the scanner gets right
- Every framework, not just the first — a Next.js + Express + Socket.IO + React project lists all four
- Real, runnable commands — npm scripts captured with their actual shell command, not just the name
- Environment variable names — read from
.env.example; values are never copied and the real.envis never opened - Secret-safe git context — remote URLs are credential-masked (
https://***@host/...) and de-duplicated - 28 languages detected — Python, Java, Kotlin, TypeScript, Go, Rust, PHP, C#, Ruby, and more
- Build system + test detection — Maven, Gradle, npm/yarn/pnpm/bun, uv/pip, Cargo, Go modules, Composer; Jest, Vitest, pytest, JUnit, and test-file counts
- Monorepo aware — nested manifests discovered up to 2 levels deep
- Honest numbers, fast —
node_modules,.venv,.next,distand the rest are pruned during the walk instead of filtered afterwards, so a TypeScript project is reported as TypeScript (not 71 % JavaScript from its dependencies) and a 46 s scan of a Next.js repo finishes in under a second.--include-vendoredrestores the old walk-everything behaviour, and the choice is recorded in the report sooracle-checkre-counts the same way - Cross-platform —
pathlibeverywhere, no platform-specific code
Install
Five commands land on your PATH: oracle-scan, oracle-generate,
oracle-vault, oracle-check, oracle-lint.
pipx install project-oracle
# or
uv tool install project-oracle
Renamed in 3.0.0. The package used to be published as
hermes-project-oracle, and the repository wasiruzen-dono/hermes-project-oracle. The old name still installs: its final release is an empty pointer that depends on this package, so an existing install migrates itself on upgrade. New installs use the name above.
As a skill — for Claude Code, Cursor, Codex, Hermes. The zip carries only
what the skill needs (SKILL.md, scripts/, references/, plus LICENSE and
README.md), no .git/, tests or build artifacts:
git clone https://github.com/iruzen-dono/project-oracle.git
cd project-oracle
python package_skill.py # builds project-oracle.zip + validates it
# Claude Code / generic SKILL.md agents
unzip project-oracle.zip -d ~/.claude/skills/
# Hermes Agent
unzip project-oracle.zip -d ~/.hermes/skills/
On Windows (PowerShell): Expand-Archive project-oracle.zip -DestinationPath $HOME\.claude\skills\
Running from a skill install instead? Prefix with python $SKILL/scripts/
(SKILL=~/.claude/skills/project-oracle) — the flags are identical. Run
any script with --help for all flags.
Scripts
| Script | Purpose |
|---|---|
scripts/oracle_lint.py |
Audit a context file: verified / contradicted / noise |
scripts/oracle_check.py |
Fail CI when the context has drifted from the repo |
scripts/oracle_scan.py |
Deep project scan → JSON report (28 languages, credential-safe) |
scripts/oracle_generate.py |
Report → context files (4 templates + optional intent file) |
scripts/oracle_vault.py |
Push a structured note into an Obsidian vault |
Docs
- Full skill instructions:
SKILL.md - Interview script (intent + pitfalls):
references/interview-script.md - Example intent file:
references/intent-example.json - Example generated output:
references/agents-md-example.md
Development
pip install -e ".[dev]"
ruff check . # lint (deterministic via ruff.toml)
mypy scripts/ --ignore-missing-imports
pytest tests/ -v # unit + end-to-end (scan → generate → vault)
pytest tests/ --cov=scripts # coverage (currently 77%)
The end-to-end test builds a fixture Node project, runs the full pipeline, and asserts the output is safe (no leaked tokens, no env values, no absolute paths) and complete (commands, frameworks, env names, pitfalls).
Contributing
PRs welcome! Keep it cross-platform, add tests, preserve the zero-dependency promise, and never introduce network calls or credential collection.
License
MIT
Metadata
Release files for project-oracle 3.0.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 | Provenance | Actions |
|---|---|---|---|---|
| project_oracle-3.0.0.tar.gz | 99.6 kB | Without provenance | Details for project_oracle-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| project_oracle-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for project_oracle-3.0.0-py3-none-any.whl |
Total release size: 166.9 kB
Release files / project_oracle-3.0.0.tar.gz
| Download URL | project_oracle-3.0.0.tar.gz |
|---|---|
| Size | 99.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7c72fbb4c4518ef41b99ed2f7ddfc646f5e9922e59a07f437177186ef89cedbf
|
|
BLAKE2b-256 checksum How to use checksums |
2461a0af17d803687dc08f47f6e06ccf4e8668a3367e836b5596af11af2e6ed2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / project_oracle-3.0.0-py3-none-any.whl
| Download URL | project_oracle-3.0.0-py3-none-any.whl |
|---|---|
| Size | 67.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
57191b5161f3b32e745bf8b6a6648f4b3c9e1ea4b830f71c5b7bbe21eba25b10
|
|
BLAKE2b-256 checksum How to use checksums |
11fb1dd72acfb7684d27d2c4c5c912a0077255c93df464b27877cc0f23a80832
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for project-oracle 3.0.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.