Metadata-Version: 2.4
Name: infinite-neo
Version: 0.2.0
Summary: An AI-native project context and handoff system for coding agents.
Author: Navneet Singh
License-Expression: MIT
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: mcp<3,>=2; extra == "test"
Requires-Dist: pytest<9,>=8.4; extra == "test"
Provides-Extra: integrations
Requires-Dist: mcp<3,>=2; extra == "integrations"
Provides-Extra: dev
Requires-Dist: build<2,>=1.5; extra == "dev"
Requires-Dist: mcp<3,>=2; extra == "dev"
Requires-Dist: mypy<3,>=2.0; extra == "dev"
Requires-Dist: pytest<9,>=8.4; extra == "dev"
Requires-Dist: ruff<1,>=0.15; extra == "dev"
Requires-Dist: twine<7,>=6.2; extra == "dev"
Dynamic: license-file

# 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/vision.md)
- [`docs/philosophy.md`](docs/philosophy.md)
- [`docs/anti-goals.md`](docs/anti-goals.md)
- [`docs/architecture.md`](docs/architecture.md)
- [`docs/roadmap.md`](docs/roadmap.md)
- [`docs/glossary.md`](docs/glossary.md)
- [`docs/ADR/`](docs/ADR/) for accepted architectural decisions

Contributor and project policies:

- [`CONTRIBUTING.md`](CONTRIBUTING.md)
- [`SECURITY.md`](SECURITY.md)
- [`CHANGELOG.md`](CHANGELOG.md)
- [`docs/releasing.md`](docs/releasing.md)

## Install

Install the current release from PyPI:

```powershell
py -m pip install --upgrade infinite-neo
```

Verify:

```powershell
neo --version
```

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

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

To install from this repository instead:

From this repository:

```powershell
py -m pip install -e .
```

Verify the source installation:

```powershell
neo --version
```

## Initialize a project

Inside any project:

```powershell
neo init
```

Or pass a path:

```powershell
neo init C:\Projects\sample-fastapi
```

## Check readiness

```powershell
neo doctor
```

## Show current project state

```powershell
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:

```powershell
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

```powershell
neo prompt start
neo prompt handoff
neo prompt debug
neo prompt deploy
```

## Connect Codex automatically

Install the optional local MCP transport:

```powershell
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`](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`](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

```text
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:

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

Run the same quality gates used by CI:

```powershell
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`](CONTRIBUTING.md) for the complete contribution workflow.

## Typical workflow

```powershell
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:

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