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 · Roadmap · Releases

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

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.

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.7.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.

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.7.0/codex_workspace_bootstrap-0.7.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.