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>/:

goal.md
plan.toon
state.toon
standards.md

The repo-local task config lives at:

.agent/controller-loop/task.toon

Commands

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:

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:

{
  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:

{
  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:

nix-build
nix-env -f . -i

Release generation

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).