You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 34c17d5
Browse filesBrowse the repository at this point in the historyBrowse files
Aictrl is a headless, server-side runtime for autonomous AI agent workflows. It is designed for engineers who want to automate complex tasks using agentic models in CI/CD pipelines, cron jobs, or embedded within other applications.
21
+
**aictrl CLI** (`@aictrl/cli`) runs an AI coding agent as one non-interactive command in CI/CD pipelines, scheduled jobs, and isolated containers.
22
+
23
+
Interactive coding agents are built for a person at a terminal: in automation they can hang on permission prompts nobody is watching, exit `0` after a provider error, or bury structured answers in prose. **aictrl CLI has no interactive mode.** Permission prompts are rejected immediately, every run streams a versioned NDJSON event log (`EVENTS.md`), final results are validated against your JSON Schema with corrective turns, and exit codes tell your pipeline whether to proceed, retry, or fail.
24
+
25
+
## Why a dedicated headless harness?
26
+
27
+
Engineers running terminal-first coding agents in CI and batch workflows repeatedly hit the same failure modes:
28
+
29
+
| What breaks in automation | How `aictrl run` handles it |
30
+
| :--- | :--- |
31
+
|**Silent hangs** (`claude-code-action#865`, `goose#11164`) |**No terminal UI or interactive prompts.** Any unpermitted tool request is rejected immediately; optional stream idle timeouts stop stalled model calls. |
32
+
|**False `exit 0` on failure** (`claude-code#79500`, `goose#11909`, `gemini-cli#1088`) |**Distinct exit codes:**`0` accepted result, `1` provider/runtime/timeout error, `2` configuration error, `3` missing or schema-invalid result, `130`/`143` on `SIGINT`/`SIGTERM`. |
33
+
|**Unparseable prose or broken JSON** (`codex#19816`, `claude-code#18536`, `gemini-cli#4665`) |**Enforced JSON Schema (`--output-schema`)** with bounded corrective turns and atomic file output (`--output-result`). No prose fallback. |
34
+
|**`--dangerously-skip-permissions` in CI**|**Declarative per-tool allow/deny rules.** Tools denied for all patterns are stripped from the model request entirely, saving tokens and shrinking the attack surface. Subagents inherit caller denials. |
35
+
|**Cost & token blind spots** (`claude-code#8245`, `codex#13733`) |**608-token system prompt** and a [versioned NDJSON event stream](EVENTS.md) on stdout reporting per-call token usage, cost, tool timing, and permission decisions. |
36
+
|**Background auto-updates & telemetry** (`claude-code-action#1290`) |**Zero telemetry, no auto-update, built-in model catalog.** Outbound traffic goes only to the model provider, MCP servers, and web tools you configure. |
15
37
16
38
## Install
17
39
@@ -21,35 +43,113 @@ npm i -g @aictrl/cli
21
43
22
44
## Quick Start
23
45
24
-
```bash
25
-
# Run a one-off task
26
-
aictrl run "analyze the security of this repository"
46
+
### 1. Validated JSON output in a terminal or container
27
47
28
-
# Use a specific model
29
-
aictrl run --model anthropic/claude-3-5-sonnet-latest "refactor the auth module"
30
-
```
48
+
```bash
49
+
export ANTHROPIC_API_KEY=<your-key># or OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, etc.
31
50
32
-
## Automation & Headless Usage
51
+
# Stream NDJSON events and write a schema-validated result atomically
52
+
aictrl run --format json \
53
+
--model anthropic/claude-sonnet-4-5 \
54
+
--output-schema findings.schema.json \
55
+
--output-result findings.json \
56
+
"Review the changes on this branch and report security or reliability bugs"
33
57
34
-
Aictrl is "headless first". When run in a non-TTY environment, it automatically switches to a mode optimized for automation.
58
+
# Pipe input from stdin
59
+
git diff origin/main...HEAD | aictrl run --model openai/gpt-5 "Summarize breaking API changes"
Save as `.github/workflows/aictrl-review.yml`. No step holds both the model API key and the GitHub token, and the agent runs with read-only tools (`read`, `glob`, `grep` only—no `bash`, no `write`, no repo config):
You can pipe content directly into `aictrl`. This is useful for processing logs, code, or command output.
132
+
## Headless CLI Benchmark (6 Harnesses Compared)
39
133
40
-
```bash
41
-
cat logs.txt | aictrl run "summarize these errors"
42
-
```
134
+
We benchmarked six coding-agent CLIs (`aictrl 0.5.4`, `pi 1.3.0`, `Goose 1.55.0`, `Codex 0.163.0`, `OpenCode 2.1.0`, and `Hermes v0.22.2`) in fresh 2-CPU Docker containers against a deterministic 50 ms local stub model to isolate harness overhead from remote LLM latency. Full runner, raw JSON captures, and methodology are open in [`aictrl-dev/skill-md-research`](https://github.com/aictrl-dev/skill-md-research/tree/main/experiments/headless-cli-benchmark) and analyzed in the [benchmark post](https://aictrl.dev/blog/headless-coding-agent-cli-benchmark?utm_source=github&utm_medium=readme&utm_campaign=headless-readme).
For programmatic consumption, use `--format json`to get raw events.
148
+
*\*Codex's shell reader truncates each 800-line file to its first and last ~80 lines, holding ~1/5th of the file in context. `pi`, `Goose`, and `Hermes` ran without a subagent tool in the tested profile; restricting `aictrl` to `pi`'s 4 tools via permission config drops its first request from 3,442 to 2,091 tokens.*
47
149
48
-
```bash
49
-
aictrl run --format json "review this PR"| jq '.type'
50
-
```
150
+
## Core Contracts for Automation
51
151
52
-
### Validated Final Results
152
+
### Validated Final Results (`--output-schema`)
53
153
54
154
`aictrl run --output-schema <file>`validates the final JSON result.
55
155
Use `--output-schema-retries <n>` for additional corrective turns (0–10, default 2)
@@ -66,21 +166,24 @@ provider failures and stream timeouts use **1**, signals use **130**/**143**.
66
166
See the [full contract](packages/cli/README.md#validated-final-results)
- **Model & cost accounting:** `message_complete` and `subagent_message_complete` with input/output/reasoning/cache tokens, cost, and context-window utilization
In headless mode, `aictrl` automatically rejects any action that would prompt a human. You can scope permissions per tool or command pattern in `aictrl.json` or inline via `AICTRL_CONFIG_CONTENT`. Any tool denied for all patterns (e.g. `"webfetch": "deny"`, `"task": "deny"`) is omitted from the model request, saving tool-definition tokens on every turn.
84
187
85
188
Tool descriptions describe tools; they are not a security boundary. Block
86
189
dangerous commands with `permission.bash` rules, for example denying force
@@ -89,6 +192,16 @@ which also blocks harmless `-c` uses). The CLI ships no such rules by default. S
`aictrl run`does not list skills from `~/.claude`, `~/.agents` or `~/.opencode`;
198
+
list them explicitly in config `skills.paths` (e.g. `["~/.claude/skills"]`) to use
199
+
them. Project skills, the global aictrl
200
+
config directories (`~/.config/aictrl`, `~/.aictrl`) and config
201
+
`skills.paths`/`skills.urls` are still listed. Pass `--skill <name>` (repeatable)
202
+
or set config `skills.allow` to list and load only the named skills.
203
+
See the [full contract](packages/cli/README.md#skill-scope).
204
+
92
205
### Model Stream Idle Timeout
93
206
94
207
Model stream idle timeouts are disabled by default. Set
@@ -100,21 +213,20 @@ resets after every stream event, so responses that keep making progress are unaf
100
213
Tool execution (local or provider-executed) uses a ceiling twelve times the
101
214
configured model timeout, capped at 2147483647 ms (one hour for a five-minute timeout).
102
215
103
-
## MCP & Custom Tools
216
+
### Models, MCP & Custom Tools
217
+
218
+
`aictrl`ships a built-in provider catalog supporting **Anthropic**, **OpenAI**, **Google**, **Amazon Bedrock**, **Google Vertex**, **Azure**, **OpenRouter**, and any OpenAI-compatible local or proxy endpoint (`--model provider/model`).
104
219
105
-
Aictrl supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
220
+
It also supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) and custom TypeScript tools in `.aictrl/tool/`:
Aictrl is a fork of the [OpenCode](https://opencode.ai) project and is licensed under the MIT License.
245
+
- **[Headless Agent Harness Overview (`aictrl.dev/agent`)](https://aictrl.dev/agent?utm_source=github&utm_medium=readme&utm_campaign=headless-readme)** — architecture principles, interactive telemetry explorer, and CI patterns
246
+
- **[Headless Coding-Agent CLI Benchmark](https://aictrl.dev/blog/headless-coding-agent-cli-benchmark?utm_source=github&utm_medium=readme&utm_campaign=headless-readme)** — 6 CLIs measured on startup, turn overhead, memory, image footprint, and tokens
247
+
- **[NDJSON Event Stream Reference (`EVENTS.md`)](EVENTS.md)** — full specification of all versioned stdout events
Copy file name to clipboardExpand all lines: packages/cli/README.md
+10-4Lines changed: 10 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,18 @@
1
1
# @aictrl/cli
2
2
3
-
Headless execution engine for AI agent skills.
3
+
The headless agent harness for CI, cron jobs, and container workflows.
4
+
5
+
-**[Overview & CI Quickstart (`aictrl.dev/agent`)](https://aictrl.dev/agent?utm_source=npmjs&utm_medium=readme&utm_campaign=headless-readme)**
-**Headless First:** Designed for automation, CI/CD, and server-side runtimes.
8
-
-**MCP Protocol:** First-class support for [Model Context Protocol](https://modelcontextprotocol.io).
9
-
-**Custom Tools:** Easy extensibility via TypeScript files.
11
+
-**Headless Only:** Built for non-interactive runs in CI/CD, scheduled jobs, and containers—no terminal UI, no hanging permission prompts, and distinct exit codes (`0` accepted, `1` provider/runtime/timeout error, `2` config error, `3` missing/invalid schema result).
12
+
-**Schema-Validated Results:** Pass `--output-schema` and `--output-result` to enforce a JSON Schema with corrective turns and atomic file output.
13
+
-**Versioned NDJSON Event Stream:**`--format json` streams every lifecycle step, tool call, permission decision, and per-call token/cost count to stdout.
14
+
-**Declarative Permissions:** Per-tool allow/deny rules (`permission` config); tools denied everywhere are stripped from the model request to save tokens.
0 commit comments