Metadata-Version: 2.4
Name: to-do-fixer
Version: 0.0.3
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
- GitHub CLI (`gh`), authenticated when a repository must be cloned or created
- An installed and authenticated `codex` CLI

## 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 must be `Repository: OWNER/REPO`. The second line must be
`Type: goal` or `Type: task`. The third line must start with `Model: `. A
non-empty model overrides the Codex model for that execution; an empty value
uses the default model from Codex configuration. Every remaining byte of UTF-8
text, beginning on the fourth line, is used as the Codex prompt. Goals and tasks
use the same execution flow; the type and selected model are included in the
run log.

```text
Repository: kaizten/example-repository
Type: task
Model: gpt-6.1-sol
Implement the requested feature, run its tests, and update the documentation.
```

To use the configured default model, leave the value empty while retaining the
required metadata line:

```text
Model:
```

Repository clones are identified from their GitHub `origin` remote rather than
from their directory name. If no local clone exists, the runner checks GitHub
using the authenticated `gh` account. An existing repository is cloned into
`<repos-root>/<owner>/<repo>`; a repository that returns HTTP 404 is created as
private and then cloned there. Authentication, network, permission, clone-path
collision, and multiple-local-clone errors cause the 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
```

If the selected task directory does not exist, the command prints a message,
creates it and any missing parent directories, and then continues normally.
An existing path that is not a directory remains an error.

Create the default task directory, including its parent directories, with:

```bash
to-do-fixer --create-tasks-directory
```

This initialization option must be used on its own and exits after ensuring the
directory exists.

Codex runs sequentially with `--approve-for-me`, which uses automatic approval
review with the `workspace-write` sandbox. A structured final response is
required before a task is considered complete.

At startup and again when execution finishes, the command prints a task summary
table with pending, done, failed, and total counts. The final table is also
printed when execution stops early or is interrupted.

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

