Headless execution engine for AI agent skills

---

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.

Install

npm i -g @aictrl/cli

Quick Start

# Run a one-off task
aictrl run "analyze the security of this repository"

# Use a specific model
aictrl run --model anthropic/claude-3-5-sonnet-latest "refactor the auth module"

Automation & Headless Usage

Aictrl is "headless first". When run in a non-TTY environment, it automatically switches to a mode optimized for automation.

Stdin Piping

You can pipe content directly into aictrl. This is useful for processing logs, code, or command output.

cat logs.txt | aictrl run "summarize these errors"

JSON Output

For programmatic consumption, use --format json to get raw events.

aictrl run --format json "review this PR" | jq '.type'

Non-Interactive Execution

In headless mode, Aictrl automatically rejects all interactive permission requests (like question or plan_enter), ensuring your pipelines never hang.

CI/CD Integration

Set AICTRL_HEADLESS=true in your environment to force headless behavior even in pseudo-TTYs.

GitHub Integration

Aictrl includes a specialized GitHub agent that can be installed into your repositories to automate PR reviews, issue triage, and code generation.

Setup

# Install the GitHub agent in the current repo
aictrl github install

Features

• Auto-Push: The agent can commit and push changes directly to your branches.
• PR Creation: It can automatically open Pull Requests for its changes.
• Context Aware: In GitHub Actions, it automatically fetches PR diffs, issue comments, and review history.
• Social Cards: Generates visual summaries of agent sessions.

Developer Workflow

PR Checkout

Engineers can quickly checkout a PR and import the associated agent session:

aictrl pr 123

This command will:

1. Fetch and checkout PR #123.
2. Detect if an Aictrl session was used to generate the PR.
3. Import that session locally so you can continue the conversation.

MCP & Custom Tools

Aictrl supports the Model Context Protocol (MCP).

# Add an MCP server
aictrl mcp add my-tool --url http://localhost:8080

# Add custom TypeScript tools
# Just drop them in .aictrl/tool/

Programmatic SDK

Embed Aictrl directly into your TypeScript applications.

import { createAictrlClient } from "@aictrl/sdk"

const client = createAictrlClient({
  baseUrl: "http://localhost:4096"
})

const session = await client.session.create({
  title: "My Automation Task"
})

Agent Client Protocol (ACP)

Aictrl implements the Agent Client Protocol, allowing other ACP-compatible agents to communicate with Aictrl headlessly.

aictrl acp

Attribution

Aictrl is a fork of the OpenCode project and is licensed under the MIT License.

---

aictrl.dev