Metadata-Version: 2.4
Name: to-do-fixer
Version: 0.0.2
Summary: Execute directory-backed Codex tasks against local GitHub repositories.
Author: Kaizten Analytics
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# To-do Fixer

`to-do-fixer` executes directory-backed tasks in fresh Codex sessions. It
selects pending files randomly and processes them one at a time until the
directory is empty or Codex reports a global usage or authentication limit.

## Requirements

- Python 3.10 or newer
- Git
- An installed and authenticated `codex` CLI
- Local GitHub repository clones beneath the selected repository root

## Installation

From this directory:

```bash
python3 -m pip install .
```

## Task format

Each non-hidden regular file directly inside the task directory is a pending
task. The first line is the GitHub repository in `OWNER/REPO` format. Every
remaining byte of UTF-8 text is used as the Codex prompt.

```text
kaizten/example-repository
Implement the requested feature, run its tests, and update the documentation.
```

Repository clones are identified from their GitHub `origin` remote rather than
from their directory name. A missing clone or multiple matching clones causes
that task to fail.

## Usage

```bash
to-do-fixer
```

Tasks are read from `~/.to-do-fixer/tasks` and repositories are searched
recursively beneath `~` by default. Select other locations with:

```bash
to-do-fixer --tasks-directory ~/codex-tasks --repos-root ~/workspaces
```

Codex runs sequentially with the `workspace-write` sandbox and
`--approve-for-me`. A structured final response is required before a task is
considered complete.

Completed tasks move into `done/`. Invalid, missing, ambiguous, blocked, or
otherwise failed tasks move into `failed/`. Existing files in either directory
are never overwritten. If Codex reaches a usage, quota, rate, credit, or
authentication limit, the current task remains pending and the command stops.

Only one `to-do-fixer` process may use a task directory at a time. Pressing
Ctrl-C stops the active Codex process and leaves its task pending.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Every pending task was processed. Some may have moved to `failed/`. |
| `1` | Startup or configuration failed. |
| `2` | A global Codex limit or authentication failure stopped processing. |
| `130` | The user interrupted processing. |

## Development

```bash
python3 -m unittest discover -s tests -v
./build-package.sh
```

