codex-workspace-bootstrap

Make Windows repositories Codex-ready with automated environment checks, project instructions, safety audits, and maintainer workflows.

日本語ガイド · Examples · Roadmap · Releases

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

What problem does it solve?

Codex works better when a repository clearly states its toolchain, validation commands, constraints, and maintenance workflow. On Windows, those details are often scattered across README files, shell history, and machine-specific assumptions.

codex-workspace-bootstrap gives maintainers one repeatable entry point to:

• audit Git, Python, Node.js, npm, PowerShell, WSL, and Codex availability;
• inspect repository basics such as README, license, ignore rules, manifests, and AGENTS.md;
• warn about common secret-bearing filenames without reading their contents;
• distinguish tracked risky files from ignored or untracked files when Git is available;
• generate a project-aware AGENTS.md for Python, Node.js, mixed, or unknown projects;
• write machine-readable JSON and SARIF 2.1.0 reports;
• fail CI on blocking findings with --strict;
• validate releases through automated tests, self-audit, and build checks.

Why Windows-first?

The project targets a real repository-readiness problem around Windows and Windows+WSL development. It does not claim to fix upstream Codex product bugs. See docs/MOTIVATION.md for the scope and public upstream references.

30-second start

Install the pinned v0.3.0 wheel:

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

Audit the current repository:

codex-workspace-bootstrap audit .

Generate project instructions:

codex-workspace-bootstrap init-agents .

Check the installed version:

codex-workspace-bootstrap --version

For more examples, see docs/EXAMPLES.md.

Why a pinned release instead of irm ... | iex?

The recommended quick start installs a specific published wheel so users can see exactly which release they are installing. A PowerShell helper script remains available in scripts/install.ps1, but piping remote scripts directly into PowerShell is not the recommended path.

GitHub Action

Use the tool directly in an OSS repository workflow:

- uses: actions/checkout@v7
- uses: actions/setup-python@v7
  with:
    python-version: "3.13"
- uses: kohli217/codex-workspace-bootstrap@v0.3.0
  with:
    path: .
    strict: "true"

See docs/GITHUB_ACTION.md for the full workflow and input reference.

Commands

Audit a repository

codex-workspace-bootstrap audit .

Write JSON output:

codex-workspace-bootstrap audit . --json audit-report.json

Use strict mode in CI:

codex-workspace-bootstrap audit . --strict

SARIF / Code Scanning

codex-workspace-bootstrap audit . --sarif codex-workspace-bootstrap.sarif

Blocking findings are emitted as SARIF errors and other warnings as SARIF warnings. See docs/SARIF.md for GitHub Code Scanning integration.

Generate AGENTS.md

codex-workspace-bootstrap init-agents .

The generator inspects common project manifests and layout signals, then writes conservative validation guidance. Existing AGENTS.md files are never overwritten unless --force is explicit.

Safety model

• The core audit path performs local inspection only.
• The tool does not read or print the contents of suspected secret files.
• The tool does not send repository contents to a remote service.
• A passing audit is evidence about the checks performed, not a security guarantee.
• File modifications are opt-in; existing AGENTS.md files are protected by default.

See SECURITY.md for reporting guidance.

Maintainer workflow

This project uses an issue → branch → pull request → CI → merge → release workflow.

Current automated checks include:

• Windows and Ubuntu test matrices on Python 3.10 and 3.13;
• built-wheel smoke testing;
• strict self-audit before releases;
• CodeQL static analysis;
• weekly dependency update checks for Python and GitHub Actions;
• validated one-click GitHub releases with attached wheel and source distribution.

Release history began with v0.1.0.

Codex-oriented workflow

A practical repository workflow is:

1. run audit;
2. review warnings and blocking findings;
3. generate or review AGENTS.md;
4. give Codex a scoped issue or task;
5. run the repository tests and the audit again;
6. inspect the diff before merge;
7. release only after CI passes.

See AGENTS.md for this repository's own agent instructions and skills/codex-workspace-bootstrap/SKILL.md for the reusable skill.

Project scope

In scope

• Windows-first repository readiness checks;
• Codex-oriented project instructions;
• maintainer automation that is deterministic and reviewable;
• CI-friendly reporting and safe defaults.

Not in scope

• claiming that a repository is secure because an audit passed;
• silently changing user configuration;
• uploading repository contents by default;
• replacing project-specific documentation or human review.

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 are welcome. See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SUPPORT.md.

Maintainer and adoption

Primary maintainer identity and responsibilities are documented in MAINTAINERS.md.

If you use the project, please share a real usage report through the GitHub issue template. The project deliberately avoids fabricated testimonials or adoption claims. See docs/ADOPTION.md.

Roadmap

See docs/ROADMAP.md.

Releasing

Maintainers can create a tested GitHub release from the Actions UI. See docs/RELEASING.md.

Citation

Machine-readable citation metadata is available in CITATION.cff.

License

MIT. See LICENSE.