Neo Codex OS

An AI Engineering Operating System for durable project continuity.

Neo preserves engineering context, understands project state, and guides developers through the software lifecycle so they can spend less time reconstructing context and more time building.

Project constitution

Neo's founding direction is documented in:

• docs/vision.md
• docs/philosophy.md
• docs/anti-goals.md
• docs/architecture.md
• docs/roadmap.md
• docs/glossary.md
• docs/ADR/ for accepted architectural decisions

Contributor and project policies:

• CONTRIBUTING.md
• SECURITY.md
• CHANGELOG.md
• docs/releasing.md

Install locally

From this repository:

py -m pip install -e .

Verify:

neo --version

Initialize a project

Inside any project:

neo init

Or pass a path:

neo init C:\Projects\sample-fastapi

Check readiness

neo doctor

Show current project state

neo status
neo status C:\Projects\sample-fastapi --verbose

Status reports where the project is, including explicit uncertainty and conflicts. It does not recommend what to do next.

Create a verified handoff

Record explicit human continuation intent for a fresh coding-agent thread:

neo handoff --next-step "Run the focused regression test."
neo handoff --question "What causes the failing test?"

At least one of --next-step or --question is required. Neo always shows the complete proposed HANDOFF.md and asks for explicit authorization before its protected one-file replacement. Repeating an equivalent handoff is a verified, non-mutating skip. These values are human statements, not Neo recommendations.

Print reusable prompts

neo prompt start
neo prompt handoff
neo prompt debug
neo prompt deploy

Generated project files

AGENTS.md
HANDOFF.md
TASKS.md
DECISIONS.md
.neo/
  context-authoring.md
  start-thread.md
  end-thread.md
  debug.md
  deploy.md

Existing files are preserved unless --force is used.

Before editing Schema 0.1 structured sections, read .neo/context-authoring.md. It documents the exact writable grammar without acting as another context document or ProjectState source.

Development

Install Neo with its bounded development toolchain:

py -m pip install -e ".[dev]"

Run the same quality gates used by CI:

py -m ruff format --check src tests
py -m ruff check src tests
py -m mypy
py -m pytest
py -m build
py -m twine check dist/*

Use py -m ruff format src tests to apply formatting. GitHub Actions runs the test suite on Windows and Linux across Python 3.10 through 3.14 and smoke-tests built distributions on both operating systems.

See CONTRIBUTING.md for the complete contribution workflow.

Typical workflow

cd C:\Projects\my-project
neo init
neo doctor
neo status
neo handoff --question "What should the next session investigate?"
neo prompt start

Official skills

Neo's first repository-owned skill is:

skills/
  neo-architect/
    SKILL.md
    agents/openai.yaml

neo-architect guides architecture and substantial software work through an adaptive SDLC, integrating with Neo context files when they exist. It is currently a repository asset; the neo CLI and Python package do not yet install skills into an agent environment.