cli-ai-runner 1.0.0

Agent-agnostic CLI runner with loop control for Codex, Gemini, and Claude.

cli-ai-runner

The Deterministic Task Execution Engine for Agentic CLIs.

cli-ai-runner provides a professional, stable wrapper for running AI agents like Codex, Claude, and Gemini in automated loops. It solves the "completion problem" by enforcing a structured protocol between the human, the runner, and the AI.

---

🚀 Why cli-ai-runner?

• Deterministic Control: Stop guessing if an agent finished. Rely on explicit RUN_STATUS signals.
• Multi-Agent Support: Swappable adapters for the industry's leading agentic CLIs.
• Strict Completion Gating: Automated verification against your project's Roadmap and Test suites before claiming victory.
• Windows-First Reliability: Deep integration with Windows command resolution and PTY handling.

---

🛠 Installation

cli-ai-runner is distributed via PyPI and requires Python 3.11+.

pip install cli-ai-runner

---

🏁 Quick Start

1. Check your environment

See which agents are ready to work:

cli-ai-runner status

2. Setup missing agents

Automatically provision the necessary agent CLIs:

cli-ai-runner setup --yes

3. Run a project task

Execute a task with automatic continuation and verification:

cli-ai-runner "Implement the login module and add unit tests" --agent claude

---

📖 Documentation

• User Guide: Detailed command references, environment variables, and troubleshooting.
• Architecture: Deep dive into the adapter pattern and deterministic loop logic.
• Roadmap: Future plans for multi-agent orchestration and cross-platform support.

---

⌨️ CLI Command Reference

Command	Usage	Description
run	cli-ai-runner run "task" [options]	Primary command. Starts a task loop.
status	cli-ai-runner status	Lists detected agents and their binary paths.
setup	cli-ai-runner setup [--agent X]	Installs missing agent binaries via NPM.

Global Options for run:

• --agent {codex,gemini,claude}: Which adapter to use. (Default: codex)
• --max-loops N: Exit after N iterations to prevent runaway costs. (Default: 50)
• --no-strict-completion: Disable the mandatory verification pass.

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for local development setup and testing guidelines.

⚖️ License

Distributed under the MIT License. See LICENSE for more information.