114 lines
2.4 KiB
Markdown
114 lines
2.4 KiB
Markdown
# `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).
|