# `codex-controller-loop`

Rust TUI-first autonomous controller with TOON-backed machine state.

## Product Shape

`codex-controller-loop` now targets a single full-screen terminal experience:

- center session stream for planning and execution events
- persistent plan board on the right
- bottom composer for planning replies or execution commands
- Codex-backed planning and Codex-backed per-step execution

The controller has a hard two-phase model:

1. Planning
   - user can provide the goal or answer Codex follow-up questions
2. Executing
   - controller runs autonomously
   - user can only pause, resume, stop, inspect status, or update the goal

## Storage

Controller-local artifacts live under `.agent/controllers/<id>/`:

```text
goal.md
plan.toon
state.toon
standards.md
```

The repo-local task config lives at:

```text
.agent/controller-loop/task.toon
```

## Commands

```bash
codex-controller-loop
codex-controller-loop init --task-id controller-loop
codex-controller-loop status
codex-controller-loop run
```

`codex-controller-loop` defaults to the TUI.

## Build

Use Nix or Cargo:

```bash
nix develop -c cargo test
nix develop -c cargo run
```

## Nix package consumption

This repo is a flake and exposes `codex-controller-loop` under `packages` plus an exported overlay.

From another flake:

```nix
{
  inputs.codex-controller-loop.url = "github:your-org/codex-controller-loop";

  outputs = { self, nixpkgs, codex-controller-loop, ... }:
  let
    system = "x86_64-linux";
  in
  {
    packages.${system}.default = codex-controller-loop.packages.${system}.default;
  };
}
```

Through the overlay:

```nix
{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  inputs.codex-controller-loop.url = "github:your-org/codex-controller-loop";

  outputs = { self, nixpkgs, codex-controller-loop, ... }:
  let
    system = "x86_64-linux";
    pkgs = import nixpkgs {
      inherit system;
      overlays = [ codex-controller-loop.overlays.default ];
    };
  in
  {
    packages.${system}.default = pkgs.codex-controller-loop;
  };
}
```

Non-flake usage also works:

```bash
nix-build
nix-env -f . -iA codex-controller-loop
```

## Release generation

```bash
python scripts/release-orchestrator.py --version 0.1.0 --target x86_64-unknown-linux-gnu
```

Generated artifacts are written to a canonical `dist/` layout and tracked by `dist/index.json` (legacy alias: `dist/{distribution_contract_version}/index.json` until 2026-07-01).