╔═══════════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ ██████╗ ██████╗ ██████╗ ██████╗██╗ ██╗███████╗███████╗████████╗██████╗ █████╗ ║ ║ ██╔════╝██╔═══██╗██╔══██╗██╔════╝██║ ██║██╔════╝██╔════╝╚══██╔══╝██╔══██╗██╔══██╗║ ║ ██║ ██║ ██║██║ ██║██║ ███████║███████╗█████╗ ██║ ██████╔╝███████║║ ║ ██║ ██║ ██║██║ ██║██║ ██╔══██║╚════██║██╔══╝ ██║ ██╔══██╗██╔══██║║ ║ ╚██████╗╚██████╔╝██████╔╝╚██████╗██║ ██║███████║███████╗ ██║ ██║ ██║██║ ██║║ ║ ╚═════╝ ╚═════╝ ╚═════╝ ╚═════╝╚═╝ ╚═╝╚══════╝╚══════╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝║ ║ ║ ║ Loop-based AI Orchestration for the Terminal ║ ║ "The AI is the worker. Codchestra is the conductor." ║ ║ ║ ║ Created by: Mustafa Kemal Çıngıl ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝
🚀 Autonomous AI orchestration CLI — Codex & ChatGPT
Codchestra is a terminal-native development orchestrator that runs an AI coding agent (Codex or ChatGPT CLI) in a loop until all tasks are complete. You define tasks in codchestra.tasks.md; Codchestra feeds context and prompts to the AI, parses STATUS blocks, and stops when the AI signals completion or when limits (max loops, timeout, stagnation) are hit.
| Feature | Description |
|---|---|
| 🔁 Loop engine | Max loops, repeated-output detection, stagnation detection, per-call timeout |
| 📋 Task system | Markdown task list (codchestra.tasks.md) — pending / in-progress / done |
| ⚙️ Config | .codchestrarc — maxLoops, timeoutMinutes, aiCommand, verbosity, outputFormat |
| 🤖 Codex & ChatGPT | Default: chatgpt or codex; non-interactive exec, stdin prompt, workspace-write |
| 📊 Live TUI | Banner + loop status + last STATUS + errors (TTY); session logs in .codchestra/logs/ |
| ✏️ Prompt UI | Run starts with prompt choice: Enter = default, e = add task, c = custom (paste in terminal) |
| 🔌 Plugins | .codchestra/plugins/ — beforeRun, afterRun, beforeLoop, afterLoop |
npm install -g @mustafakemal0146/codchestraOr from source:
git clone https://github.com/mustafakemal0146/codchestra.git
cd codchestra
npm install
npm run build
npm linkcd your-project
codchestra init
# Edit codchestra.tasks.md with [ ], [-], [x] tasks
codchestra run- Enter = start with default prompt
- e = add a task (multi-line in terminal, empty line + Enter to finish)
- c = custom prompt (paste in terminal, empty line + Enter to finish)
| Command | Description |
|---|---|
codchestra init |
Create .codchestra/, codchestra.tasks.md, CODCHESTRA_PROMPT.md, .codchestrarc |
codchestra run |
Prompt UI → AI loop (Codex/ChatGPT) until exit or limits |
codchestra status |
Show run state and task progress |
codchestra reset |
Clear .codchestra state |
codchestra tasks |
List tasks (option: --json) |
codchestra monitor |
Live dashboard (loop #, progress, stagnation) |
codchestra doctor |
Check environment and config |
- Default: Tries
chatgpt, thencodexon PATH. - chatgpt: Prompt sent via stdin.
- Codex (OpenAI):
codex exec - --full-auto -s workspace-write -C <cwd> --skip-git-repo-check -; prompt from stdin. Install:npm i -g @openai/codex. Runcodex loginif needed. - Override: In
.codchestrarcsetaiCommandand optionallyaiArgs.
The AI must end each response with:
STATUS:
progress: <0-100>
tasks_completed: <number>
tasks_total: <number>
EXIT_SIGNAL: <true|false>
summary: <one line>
Codchestra stops successfully when EXIT_SIGNAL: true and all tasks are [x]. Use CODCHESTRA_PROMPT.md in the project to enforce this.
| Key | Default | Description |
|---|---|---|
maxLoops |
50 | Max loop iterations |
timeoutMinutes |
120 | Wall-clock timeout |
aiCallTimeoutMinutes |
10 | Per-call AI timeout |
aiCommand |
"" |
Override AI CLI (default: chatgpt/codex) |
aiArgs |
(auto for codex) | Extra args (e.g. for codex exec) |
verbosity |
"normal" |
quiet | normal | verbose |
outputFormat |
"text" |
text | json |
Place .js plugins in .codchestra/plugins/. Each module can export:
name: stringbeforeRun(cwd)afterRun(cwd, result)beforeLoop({ cwd, loop })afterLoop({ cwd, loop, stdout })
codchestra/
├── src/
│ ├── cli/ # Commands: init, run, status, reset, tasks, monitor, doctor
│ ├── config/ # .codchestrarc loader
│ ├── core/ # State, exit analyzer (STATUS parse)
│ ├── loop/ # Runner, live UI
│ ├── tasks/ # Task parser & manager
│ ├── plugins/ # Plugin loader
│ └── utils/ # Logger, session log, paths, git, aiCommand
├── CODCHESTRA_PROMPT.md
├── package.json
└── README.md
npm install
npm run build
npm run testMustafa Kemal Çıngıl — github.com/mustafakemal0146
MIT — see LICENSE.
Codchestra — The AI is the worker. Codchestra is the conductor.