AiTer Control Skill

This skill enables you to control the AiTer terminal client through CLI commands, allowing orchestration of multiple projects and agents.

Prerequisites

• AiTer must be running: The AiTer desktop application must be open for CLI commands to work
• Socket connection: Commands communicate via Unix socket at /tmp/aiter-{uid}.sock

Command Reference

All commands output JSON for easy parsing. Use jq for extraction when needed.

Project Management

List Projects

aiter project list

Returns all projects with their IDs, names, and paths.

Response:

{
  "success": true,
  "data": [
    {
      "id": "project-1234567890-abc123",
      "name": "my-frontend",
      "path": "/path/to/frontend",
      "isGitRepo": true
    }
  ]
}

Create Project

aiter project create "<name>" "<path>"

Creates a new project. Initializes Git repo if not already one.

Example:

aiter project create "ecommerce-frontend" "./frontend"

Response:

{
  "success": true,
  "data": {
    "id": "project-1234567890-xyz789",
    "name": "ecommerce-frontend",
    "path": "/absolute/path/to/frontend",
    "isGitRepo": true
  }
}

Open/Focus Project

aiter project open <project-id>

Brings the project into focus in AiTer UI.

Terminal Management

List Terminals

# List all terminals
aiter terminal list

# List terminals for specific project
aiter terminal list --project <project-id>

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "projectId": "project-123",
      "name": "my-frontend | npm start",
      "cwd": "/path/to/frontend",
      "pid": 12345
    }
  ]
}

Create Terminal

# Create with startup command (default: runs 'minto')
aiter terminal create <project-id>

# Create without startup command
aiter terminal create <project-id> --skip-startup

Response:

{
  "success": true,
  "data": {
    "terminalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "projectId": "project-123",
    "name": "my-frontend | >",
    "cwd": "/path/to/frontend",
    "pid": 12345
  }
}

Write to Terminal

aiter terminal write <terminal-id> "<text>"

Writes text to the terminal and presses Enter.

Example:

aiter terminal write term-123 "npm install"

Important: The text is automatically followed by a carriage return (\r), so commands execute immediately.

Read Terminal Output

# Read all buffered output
aiter terminal read <terminal-id>

# Read last N lines
aiter terminal read <terminal-id> --lines 50

Response:

{
  "success": true,
  "data": {
    "lines": [
      "$ npm install",
      "added 1234 packages in 15s",
      "$ "
    ],
    "totalLines": 150
  }
}

Note: ANSI escape codes are stripped from output for clean text.

Kill Terminal

aiter terminal kill <terminal-id>

Gracefully closes the terminal (sends SIGTERM, then SIGKILL if needed).

File Server Management

Start File Server

aiter server start <project-id>

Starts HTTP server for the project (used for HTML preview).

Response:

{
  "success": true,
  "data": {
    "projectId": "project-123",
    "port": 3001,
    "baseUrl": "http://localhost:3001/?token=abc123..."
  }
}

Get File URL

aiter server url <project-id> "<relative-path>"

Example:

aiter server url project-123 "dist/index.html"

Stop File Server

aiter server stop <project-id>

Server Statistics

aiter server stats

Status Query

aiter status

Returns overview of AiTer state including projects, terminals, and file servers.

---

Inter-Agent Communication Protocol

When dispatching tasks to sub-agents in other terminals, use this communication protocol:

Notification Format

Sub-agents notify the Meta Agent by writing structured messages to the Meta Agent's terminal:

# Progress update
aiter terminal write <meta-terminal-id> "[PROGRESS:<source-terminal-id>] 45% - Description"

# Question/Decision needed
aiter terminal write <meta-terminal-id> "[QUESTION:<source-terminal-id>] Your question here"

# Task completed
aiter terminal write <meta-terminal-id> "[DONE:<source-terminal-id>] Completion summary"

# Error occurred
aiter terminal write <meta-terminal-id> "[ERROR:<source-terminal-id>] Error description"

Task Dispatch Template

When dispatching a task to a sub-agent, include:

You are the {project-name} development agent.

## Your Task
{detailed task description}

## Constraints
{any constraints or requirements}

## Communication Protocol

Your terminal ID is: {child-terminal-id}
The Meta Agent's terminal ID is: {meta-terminal-id}

When you need to communicate:
- Progress: aiter terminal write {meta-terminal-id} "[PROGRESS:{child-terminal-id}] percentage - description"
- Questions: aiter terminal write {meta-terminal-id} "[QUESTION:{child-terminal-id}] your question"
- Done: aiter terminal write {meta-terminal-id} "[DONE:{child-terminal-id}] summary"
- Errors: aiter terminal write {meta-terminal-id} "[ERROR:{child-terminal-id}] error details"

## Start Working
Begin by analyzing the task and creating a plan. Report progress as you complete milestones.

---

Common Patterns

Pattern 1: Create Project and Start Agent

# 1. Create project
result=$(aiter project create "my-app" "./my-app")
project_id=$(echo "$result" | jq -r '.data.id')

# 2. Create terminal (starts Minto automatically)
result=$(aiter terminal create "$project_id")
terminal_id=$(echo "$result" | jq -r '.data.terminalId')

# 3. Wait for Minto to initialize
sleep 3

# 4. Send task to the agent
aiter terminal write "$terminal_id" "Please implement user authentication..."

Pattern 2: Monitor Multiple Agents

# Get all terminals
terminals=$(aiter terminal list | jq -r '.data[].id')

# Check each terminal's output for status markers
for tid in $terminals; do
  output=$(aiter terminal read "$tid" --lines 20)

  # Check for completion
  if echo "$output" | jq -r '.data.lines[]' | grep -q '\[DONE\]'; then
    echo "Terminal $tid completed"
  fi

  # Check for errors
  if echo "$output" | jq -r '.data.lines[]' | grep -q '\[ERROR\]'; then
    echo "Terminal $tid has error"
  fi
done

Pattern 3: Cascading Project Setup

# Create multiple related projects
for name in "frontend" "backend" "shared"; do
  aiter project create "$name" "./$name"
done

# List all projects
aiter project list | jq '.data[] | "\(.id): \(.name)"'

---

Error Handling

Connection Errors

If AiTer is not running:

{
  "success": false,
  "error": "AiTer is not running. Please start AiTer first."
}

Invalid Parameters

{
  "success": false,
  "error": "Missing required parameter: projectId"
}

Terminal Not Found

{
  "success": false,
  "error": "Terminal not found: invalid-id"
}

---

Best Practices

1. Always check success field before accessing data
2. Use --lines flag when reading output to limit data transfer
3. Implement retry logic for transient connection errors
4. Poll at reasonable intervals (5+ seconds) to avoid overwhelming the system
5. Clean up terminals when tasks complete to free resources
6. Use --skip-startup when you want to control what runs in the terminal