codex-workspace-bootstrap

Preflight your repository before an AI coding agent touches it — and catch instruction drift before different agents follow different rules.

Windows-first. Local by default. CI-friendly. Designed for repositories used with Codex, Copilot, Cline, Claude Code, Gemini CLI, Continue, Cursor, and similar coding agents.

日本語ガイド · Examples · GitHub Action · GitHub App · Free GitHub App deployment · Cloud Run alternative · Integration contract · Roadmap · Releases

Community-maintained project. Not an official OpenAI product and not affiliated with OpenAI.

Why add this to your repository?

AI coding agents can move fast, but they can also follow stale or conflicting repository instructions. codex-workspace-bootstrap adds one repeatable check before that happens.

It is local-first: the core preflight does not send repository contents to a remote AI service.

The 20-second demo

py -m pip install codex-workspace-bootstrap
cwb preflight .

Typical output:

AI Repository Preflight
State: NEEDS ATTENTION
Project: Python
AI instructions: none detected
Audit: 10 passed, 4 warnings, 0 blocking
Instruction integrity: 0 findings, 0 drift, 0 invalid commands, 0 metadata
Next actions:
  [P1] Add repository instructions for AI coding agents -> cwb init-agents .
  [P2] Make the Codex CLI available when local Codex workflows are intended -> codex --version

Fix the highest-value gap:

cwb init-agents .
cwb preflight .

See it catch real mistakes

A reproducible demo creates a temporary repository where the project uses pnpm but AGENTS.md tells the agent to use npm and references a nonexistent lint script.

py examples/first-run-demo/run_demo.py

Expected outcome:

=== BEFORE ===
State: NEEDS ATTENTION
Findings:
  - package-manager-mismatch
  - missing-package-script

=== AFTER ===
State: READY
Findings: none

Demo verification: PASS

See examples/first-run-demo for the full reproducible demo. It uses disposable temporary Git repositories and is verified in CI.

Try it on your repository

py -m pip install codex-workspace-bootstrap
cwb preflight .

If the result is useful, noisy, or surprising, open a Usage report. Public references are optional; do not include private repository contents, credentials, or secret values.

Useful feedback includes false positives, missing repository layouts, monorepo behavior, and which check saved you time.

The goal is not a vanity score. The result is one of:

• READY — core repository signals and AI instructions are present, with no blocking finding;
• NEEDS ATTENTION — usable, but important repository or AI-instruction signals are missing;
• BLOCKED — a blocking finding such as a tracked secret-risk filename needs review.

What it checks

Repository readiness

• Git repository
• README
• license
• .gitignore
• common project manifests, including Python, Node.js, Go, Rust, JVM, and .NET roots
• local Git / Python / Node.js / repository-selected package manager / PowerShell / WSL / Codex signals

AI instruction coverage

The preflight detects repository instruction/config signals for:

• Codex / OpenAI agents — AGENTS.md
• GitHub Copilot — repository instructions
• Cline
• Claude Code
• Gemini CLI
• Continue
• Cursor

It does not claim these files are correct merely because they exist. It tells you what was detected so a maintainer can review the actual instructions.

Cross-agent instruction integrity

When multiple AI instruction files exist, cwb reads executable-looking commands and checks them against repository evidence. It understands nested AGENTS.md / AGENTS.override.md, nested CLAUDE.md, Gemini CLI hierarchical context files (including project context.fileName overrides), nested Cursor .cursor/rules, and common path-specific frontmatter such as Copilot applyTo and rule globs. It can flag:

• package-manager mismatches against packageManager and lockfiles;
• cross-agent package-manager drift;
• missing package.json scripts referenced by instructions;
• conflicting test/lint/build validation commands when instruction files have no shared command for the same validation family.

The lint is intentionally conservative: different files may contain additional commands without being treated as conflicts when they share a compatible validation baseline. Commands from different scopes are not compared as if they were global rules. Path-specific rules are validated individually against repository evidence but are not cross-compared for drift unless their full selector semantics can be represented safely. A repository is not marked READY when it only has nested/path-specific instructions and no repository-wide instruction baseline.

Risk signals

The audit warns about common secret-bearing filenames without printing their contents, including environment-specific .env.* files while excluding common template names such as .env.example and .env.sample. When Git is available, it distinguishes tracked, ignored, and untracked/unknown candidates. Tracked risky filenames can become blocking findings in strict mode.

This is intentionally a lightweight preflight check, not a replacement for deep scanners such as Gitleaks or Trivy.

Why this exists

AI coding tools are good at editing code. They are not a substitute for repository hygiene.

Before handing a repository to an agent, maintainers still need answers to questions such as:

• Is this the right repository root?
• Is the expected toolchain available?
• Does the repository explain how to validate changes?
• Are AI instructions present?
• Are risky files accidentally tracked?
• Can CI surface the same checks for every pull request?

codex-workspace-bootstrap turns those questions into one repeatable preflight.

Short CLI

The package installs both command names:

cwb --version
codex-workspace-bootstrap --version

Use cwb for day-to-day work.

Commands

One-command preflight

cwb preflight .

Write reports for automation or review:

cwb preflight . --json preflight.json
cwb preflight . --markdown preflight.md
cwb preflight . --sarif preflight.sarif

Use strict mode when blocking findings should return a non-zero exit code:

cwb preflight . --strict

Fail CI on any instruction-integrity finding:

cwb preflight . --fail-on-integrity

Require the full preflight state to be READY:

cwb preflight . --require-ready

Use --require-ready when CI should reject both NEEDS ATTENTION and BLOCKED, including missing repository-wide AI instructions or essential repository markers.

For a remote service such as a GitHub App, skip host-machine tool availability checks while keeping repository evidence, Git tracking, risk filenames, and instruction integrity checks:

cwb preflight . --repository-only

This prevents a remote scanner from reporting the scanner host's Node.js, package-manager, WSL, PowerShell, or Codex availability as if it belonged to the inspected repository.

Detailed audit

cwb audit .
cwb audit . --json audit.json
cwb audit . --sarif audit.sarif
cwb audit . --strict

Safe fix preview

cwb fix .

This is preview-only by default. To apply only low-risk supported fixes:

cwb fix . --apply

Existing conflicting instruction files are never auto-rewritten. They remain human-review findings.

Non-destructive doctor

cwb doctor .

doctor prints remediation guidance only. It does not install software or modify system configuration.

Generate AGENTS.md

cwb init-agents .

Generation is evidence-based: the tool identifies common Python, Node.js, Go, Rust, JVM, and .NET project roots, then only emits validation commands that have direct repository evidence. Python/Node-specific validation is cross-checked against package-manager evidence, package scripts, pytest configuration, and README commands. Plausible but unconfirmed commands are separated for maintainer review. Existing AGENTS.md files are never overwritten unless --force is explicit.

GitHub Action

The reusable Action is published on GitHub Marketplace.

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
  with:
    python-version: "3.13"
- uses: kohli217/codex-workspace-bootstrap@v0.8.0
  with:
    path: .
    strict: "true"
    fail_on_integrity: "true"
    require_ready: "true"

The Action adds the preflight Markdown report to the GitHub Actions job summary, so maintainers get a readable readiness snapshot without digging through raw logs. Optional SARIF output contains both repository-audit and instruction-integrity findings and can be uploaded to GitHub Code Scanning.

See docs/GITHUB_ACTION.md.

Read-only evaluations against real public repositories are documented in docs/PUBLIC_REPO_EVALUATIONS.md. They are reproducible technical evaluations, not claims of third-party adoption.

GitHub App

For public OSS repositories, CWB can also run as a self-hosted GitHub App. A verified push or pull_request event triggers repository-only preflight against the exact event revision and publishes a CWB Preflight Check Run on that commit.

The preferred zero-cost development deployment uses:

GitHub App
  -> Cloudflare Worker + Queue (Free)
  -> GitHub Actions in this public repository
  -> short-lived repository-scoped installation token
  -> CWB Preflight Check

This path does not require a Google Cloud billing account. It is intentionally public-repository-only: private-repository events are rejected before they are queued into the public Actions worker.

The App keeps the minimum repository permissions documented by the project: Checks read/write, Contents read-only, and Pull requests read-only.

See docs/GITHUB_APP.md for the integration contract and deploy/cloudflare/README.md for the completely free development deployment.

Integration boundary

The CLI, reusable GitHub Action, GitHub App, and future AI-agent skills share one preflight engine and one policy evaluator. Machine-readable reports declare a schema version so integrations can detect incompatible changes instead of silently drifting.

See docs/INTEGRATIONS.md. The minimum GitHub App permissions and webhook subscriptions are defined in docs/GITHUB_APP.md and mirrored by code-level regression tests.

Where it fits

This project is a preflight layer, not an AI coding agent and not a deep security scanner.

The intent is to complement those tools, not replace them.

Safety model

• Core checks run locally.
• Suspected secret files are not opened or printed by the filename-risk check.
• Repository contents are not sent to a remote AI service by the core audit.
• Instruction files are read locally for deterministic linting; extracted commands are never executed by the integrity lint.
• Repository instruction/configuration and project-marker inputs are not trusted through symbolic links.
• init-agents and automatic fixes refuse symlinked AGENTS.md targets rather than writing through them.
• Existing regular AGENTS.md files are protected unless overwrite is explicit.
• A passing preflight is evidence about the checks performed, not a security guarantee.

See SECURITY.md.

Maintainer workflow

The project itself uses issue → branch → pull request → CI → merge → release.

Automated validation includes:

• Windows and Ubuntu;
• Python 3.10 and 3.13;
• built-wheel smoke tests;
• Action self-tests;
• strict self-audit;
• CodeQL;
• Dependabot;
• SARIF validation;
• PyPI publishing through GitHub OIDC Trusted Publishing.

Install

PyPI:

py -m pip install codex-workspace-bootstrap

Pinned GitHub release artifact:

py -m pip install "https://github.com/kohli217/codex-workspace-bootstrap/releases/download/v0.8.0/codex_workspace_bootstrap-0.8.0-py3-none-any.whl"

Development

git clone https://github.com/kohli217/codex-workspace-bootstrap.git
cd codex-workspace-bootstrap
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e . pytest
pytest -q

Contributions and real-world usage reports are welcome. See CONTRIBUTING.md, SUPPORT.md, CODE_OF_CONDUCT.md, and docs/ADOPTION.md.

License

MIT. See LICENSE.