Skip to main content

Project Oracle 🧠

CI PyPI Python License: MIT

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.

oracle-lint reporting three contradictory rules and two noise rules in a real AGENTS.md

A real run, unedited: oracle-lint on a project whose AGENTS.md had drifted — three rules contradicted by the repository, two unfalsifiable, one verified, exit 1.

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@v3
  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 .env is 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, dist and 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-vendored restores the old walk-everything behaviour, and the choice is recorded in the report so oracle-check re-counts the same way
  • Cross-platform — pathlib everywhere, 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 was iruzen-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

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. The rules are in AGENTS.md and the workflow — including how to add a lint rule — is in CONTRIBUTING.md. Security reports go through SECURITY.md.

The short version: 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.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for project-oracle 3.0.2
File Size Uploaded Provenance Actions
project_oracle-3.0.2.tar.gz 99.8 kB With provenance Details for project_oracle-3.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for project-oracle 3.0.2
File Interpreter ABI Platform Actions
project_oracle-3.0.2-py3-none-any.whl Python 3 none any Details for project_oracle-3.0.2-py3-none-any.whl

Total release size: 167.3 kB

Release files / project_oracle-3.0.2.tar.gz

Download URL project_oracle-3.0.2.tar.gz
Size 99.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e4ee5e4a903df40f82ebf6fa1a3ef292647aab43639d5e7ec2ade4fdcdd60f2f
BLAKE2b-256 checksum
How to use checksums
a1b115bb1e3d6fb117c779ee5fc637773b569346f407994394e1c71882b4e8a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Release files / project_oracle-3.0.2-py3-none-any.whl

Download URL project_oracle-3.0.2-py3-none-any.whl
Size 67.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ae308b6c8270325e8338c3fe209efebd912903d0ce4dc60ab461fafb206bdc5a
BLAKE2b-256 checksum
How to use checksums
fa1aa66401f42d02885dd9aa7aecaa37682e79a4fed4e0e9ef686c7c4ddb50b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 17, 2026.

Transparency log

Security for project-oracle 3.0.2

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for project_oracle-3.0.2.tar.gz

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 Nov 17, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page