|
2 | 2 | <img src=".github/logo.svg" alt="aictrl.dev" width="240" /> |
3 | 3 | </p> |
4 | 4 |
|
5 | | -<h3 align="center">The Lightweight Headless Runtime for AI Agent Skills</h3> |
| 5 | +<h3 align="center">Headless execution engine for AI agent skills</h3> |
6 | 6 |
|
7 | | ---- |
8 | | - |
9 | | -Aictrl CLI is a 100% headless, server-side execution harness designed for autonomous agentic workflows. It provides a secure, modular environment to run, measure, and scale agent skills without the bloat of a desktop or terminal UI. |
| 7 | +<p align="center"> |
| 8 | + <a href="https://www.npmjs.com/package/@aictrl/cli"><img src="https://img.shields.io/npm/v/@aictrl/cli" alt="npm" /></a> |
| 9 | + <a href="https://github.com/aictrl-dev/cli/blob/main/LICENSE"><img src="https://img.shields.io/github/license/aictrl-dev/cli" alt="license" /></a> |
| 10 | +</p> |
10 | 11 |
|
11 | | -## Key Features |
| 12 | +--- |
12 | 13 |
|
13 | | -- **Headless First:** Built specifically for server-side automation, Cloud Run, and CI/CD pipelines. |
14 | | -- **Skill-Native:** Native support for the `SKILL.md` format for modular procedural knowledge. |
15 | | -- **Agent Teams:** Robust support for subagent delegation and parallel execution. |
16 | | -- **Deep Telemetry:** Instrumented with granular hooks for measuring skill usage and subagent lifecycles. |
17 | | -- **Vendor Agnostic:** Compatible with Anthropic, OpenAI, Gemini, and local models via Ollama. |
18 | | -- **MCP Support:** Seamless integration with Model Context Protocol servers. |
| 14 | +Aictrl is a headless, server-side runtime for autonomous AI agent workflows. Run agent skills in CI/CD pipelines, Cloud Run, or any environment — no terminal UI required. |
19 | 15 |
|
20 | | -## Installation |
| 16 | +## Install |
21 | 17 |
|
22 | 18 | ```bash |
23 | 19 | npm i -g @aictrl/cli |
24 | 20 | ``` |
25 | 21 |
|
26 | | -## Quick Start |
| 22 | +## Usage |
27 | 23 |
|
28 | | -Run a task headlessly: |
| 24 | +### Run a task |
29 | 25 |
|
30 | 26 | ```bash |
31 | 27 | aictrl run "analyze the security of this repository" |
32 | 28 | ``` |
33 | 29 |
|
| 30 | +### Use a specific model |
| 31 | + |
| 32 | +```bash |
| 33 | +aictrl run --model anthropic/claude-sonnet-4-20250514 "refactor the auth module" |
| 34 | +``` |
| 35 | + |
| 36 | +### JSON output for pipelines |
| 37 | + |
| 38 | +```bash |
| 39 | +aictrl run --format json "review this PR" | jq '.type' |
| 40 | +``` |
| 41 | + |
| 42 | +### Attach files |
| 43 | + |
| 44 | +```bash |
| 45 | +aictrl run --file screenshot.png "what's wrong with this UI?" |
| 46 | +``` |
| 47 | + |
| 48 | +## Configuration |
| 49 | + |
| 50 | +Aictrl reads configuration from `.aictrl/` directories (project-level and `~/.config/aictrl/` global). |
| 51 | + |
| 52 | +### Models |
| 53 | + |
| 54 | +Any model from any supported provider. Set the API key as an env var: |
| 55 | + |
| 56 | +| Provider | Env Var | Example Model | |
| 57 | +|----------|---------|---------------| |
| 58 | +| Anthropic | `ANTHROPIC_API_KEY` | `anthropic/claude-sonnet-4-20250514` | |
| 59 | +| OpenAI | `OPENAI_API_KEY` | `openai/gpt-4o` | |
| 60 | +| Google | `GOOGLE_API_KEY` | `google/gemini-2.5-pro` | |
| 61 | +| OpenRouter | `OPENROUTER_API_KEY` | `openrouter/...` | |
| 62 | +| ZhipuAI | `ZHIPU_API_KEY` | `zai-coding-plan/glm-5` | |
| 63 | + |
| 64 | +Run `aictrl models` for the full list. |
| 65 | + |
| 66 | +### Skills |
| 67 | + |
| 68 | +Skills are modular agent capabilities defined as `SKILL.md` files. Place them in: |
| 69 | + |
| 70 | +- `.aictrl/skills/` (project-level) |
| 71 | +- `~/.config/aictrl/skills/` (global) |
| 72 | + |
| 73 | +### MCP Servers |
| 74 | + |
| 75 | +Configure MCP servers for external tool integration: |
| 76 | + |
| 77 | +```bash |
| 78 | +aictrl mcp add my-server --url http://localhost:8080 |
| 79 | +``` |
| 80 | + |
| 81 | +### Custom Tools |
| 82 | + |
| 83 | +Drop TypeScript files in `.aictrl/tool/` or `.aictrl/tools/` to register custom tools. |
| 84 | + |
| 85 | +## Commands |
| 86 | + |
| 87 | +| Command | Description | |
| 88 | +|---------|-------------| |
| 89 | +| `aictrl run <message>` | Execute a task headlessly | |
| 90 | +| `aictrl models` | List available models | |
| 91 | +| `aictrl mcp` | Manage MCP servers | |
| 92 | +| `aictrl session` | Manage sessions | |
| 93 | +| `aictrl upgrade` | Upgrade the CLI | |
| 94 | +| `aictrl pr` | PR workflow helpers | |
| 95 | + |
| 96 | +## SDK |
| 97 | + |
| 98 | +For programmatic use: |
| 99 | + |
| 100 | +```typescript |
| 101 | +import { createAictrl } from "@aictrl/sdk" |
| 102 | + |
| 103 | +const client = await createAictrl() |
| 104 | +``` |
| 105 | + |
| 106 | +## Monorepo |
| 107 | + |
| 108 | +| Package | Description | |
| 109 | +|---------|-------------| |
| 110 | +| `@aictrl/cli` | The CLI and headless runtime | |
| 111 | +| `@aictrl/sdk` | Programmatic SDK for embedding | |
| 112 | +| `@aictrl/plugin` | Plugin authoring utilities | |
| 113 | +| `@aictrl/util` | Shared utilities | |
| 114 | + |
| 115 | +## Development |
| 116 | + |
| 117 | +```bash |
| 118 | +bun install |
| 119 | +bun run --conditions=browser packages/cli/src/index.ts |
| 120 | +``` |
| 121 | + |
| 122 | +Build platform binaries: |
| 123 | + |
| 124 | +```bash |
| 125 | +cd packages/cli && bun run build --single |
| 126 | +``` |
| 127 | + |
34 | 128 | ## Attribution |
35 | 129 |
|
36 | | -Aictrl is a fork of the [OpenCode](https://opencode.ai) project by [anomalyco](https://github.com/anomalyco/opencode) and is licensed under the MIT License. |
| 130 | +Aictrl is a fork of the [OpenCode](https://opencode.ai) project and is licensed under the MIT License. |
37 | 131 |
|
38 | 132 | --- |
39 | | -© 2026 [aictrl.dev](https://aictrl.dev) |
| 133 | +[aictrl.dev](https://aictrl.dev) |
0 commit comments