Metadata-Version: 2.4
Name: litectrl
Version: 0.2.3
Summary: A small deterministic local controller for OpenAI Codex
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# LiteCtrl

LiteCtrl is a small deterministic local controller for OpenAI Codex.

> **Status:** community project. LiteCtrl is not an OpenAI product and is not
> affiliated with or endorsed by OpenAI.

A human supplies one bounded task specification. LiteCtrl prepares an
exact-commit Git worktree, starts a fresh Codex implementation thread, audits
the resulting file scope, runs deterministic verification outside the model
loop, and returns durable `READY` or `STOPPED` evidence.

## Install

LiteCtrl requires Python 3.11 or newer, Git, and an authenticated local `codex`
CLI with stable App Server v2 support.

```bash
python3 -m pip install litectrl
```

The runtime uses only the Python standard library.

## Quick start

From the Git repository you want Codex to work on:

```bash
litectrl task create
litectrl task list
litectrl task show <task-id>
litectrl task validate <task-id> --runtime
litectrl run <task-id>
```

Review the exact goal, base commit, write scope, verification commands, model,
and limits before starting a run.

## Safety model

- Authority and scope are explicit inputs.
- Scope, quota, timeout, token-budget, and verification failures stop the run.
- Verification runs outside the model turn and is rejected if it mutates the
  candidate workspace.
- An interrupted model turn becomes uncertain; LiteCtrl does not silently start
  a duplicate turn.
- Commit, push, pull-request creation, merge, release, and deployment remain
  separate human-controlled operations.

`write_paths` is an audited post-execution boundary, not an operating-system
sandbox.

## License

Apache License 2.0.
