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

Install the current release from PyPI:

py -m pip install --upgrade infinite-neo

Verify:

neo --version

For the optional Codex, Claude Code, and MCP integration entry points:

py -m pip install --upgrade "infinite-neo[integrations]"

To install from this repository instead:

From this repository:

py -m pip install -e .

Verify the source installation:

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

Connect Codex automatically

Install the optional local MCP transport:

py -m pip install "infinite-neo[integrations]"

Neo also installs the internal neo-codex-hook adapter. To load bounded Neo context at Codex session start and immediately after Codex compacts a session, review docs/integrations/codex-hooks.json and copy it to the project's .codex/hooks.json only when you want to enable that trusted project hook. Codex requires review of project-local hooks before they run.

The adapter reads the official SessionStart JSON from standard input and returns at most 10,000 UTF-8 bytes of factual, provenance-aware developer context. The underlying MCP resume policy supports an explicit budget up to 16 KiB. Neo does not read the transcript, estimate hidden context usage, write project files, or recommend a next action. neo-mcp exposes the same state through five optional read-only tools for on-demand evidence access.

Claude Code uses the same provider-neutral contract through the internal neo-claude-hook adapter. Review docs/integrations/claude-settings.json and merge its SessionStart hook into the project's .claude/settings.json when you choose to enable it. Claude Code reports the same explicit compact source, so Neo reloads bounded project context without guessing from token usage.

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.