aemeathcli

v1.1.0

Published

2 months ago

Next-generation multi-model CLI coding tool with agent teams and split-panel coordination

0High
0Medium
0Low

cli ai multi-model claude openai gemini coding agent terminal

  ╔══════════════════════════════════════════════╗
  ║           Welcome to AemeathCLI              ║
  ║    Multi-Model CLI Coding Tool v1.0.10       ║
  ╚══════════════════════════════════════════════╝

AemeathCLI orchestrates multiple AI models across parallel agent teams in your terminal. Route Claude for planning, GPT for coding, Gemini for reviews -- with real-time streaming, tmux-backed visual orchestration when enabled, cost tracking, and enterprise-grade security.

Why AemeathCLI

Most AI coding tools lock you into a single model. AemeathCLI breaks that ceiling:

Multi-model orchestration -- Use the right model for each task. Claude Opus for architecture, GPT-5.2 for implementation, Gemini 2.5 Pro for code review -- in one session.
Agent teams -- Describe what you need in plain English and the LLM designs the team. Agents can run under the orchestrator with tmux-backed visual panes when enabled, while a leader orchestrates, teammates execute, and results are synthesized through a shared board.
Smart routing -- Define role-based routing rules. When you switch to "review" mode, the system automatically picks the best model for reviewing code.
Cost-aware -- Real-time token counting, per-model cost tracking, configurable budget warnings and hard stops. Know exactly what you're spending.
Skills & MCP -- Extend functionality with YAML-defined skills and Model Context Protocol servers. Your tools, your workflow.
Enterprise-grade -- OS keychain storage, AES-256-GCM encryption, HMAC-SHA256 IPC auth, sandboxed execution, structured logging, typed error hierarchy.

Quick Start

# Install globally
npm install -g aemeathcli

# Authenticate with your providers
aemeathcli login

# For orchestrator mode, also configure API keys
export ANTHROPIC_API_KEY=your_key_here
export OPENAI_API_KEY=your_key_here

# Start coding
aemeathcli "Refactor the authentication module to use JWT tokens"

That's it. AemeathCLI detects your project, picks the best model, and starts streaming.

Installation

Requirements

Node.js >= 20.0.0
npm >= 9 (or pnpm / yarn)
tmux (optional, for Linux split-panel swarm panes; macOS and Windows use native terminal splits)
Native build tools for Node modules such as node-pty and better-sqlite3
- macOS: Xcode Command Line Tools
- Linux: Python, make, and a C/C++ compiler
- Windows: Visual Studio Build Tools or an equivalent MSVC toolchain

Install

npm install -g aemeathcli

The CLI installs two commands: aemeathcli and the shorthand ac.

Verify

aemeathcli --version
# 1.0.10

First Run

aemeathcli config init

This launches an interactive setup wizard that walks you through provider authentication, detects installed agent CLIs, and lets you choose the master provider used for swarm orchestration. SDK-backed swarm features still need aemeathcli auth set-key <provider> or matching environment variables when browser login is not enough.

Authentication

AemeathCLI supports four cloud providers with native OAuth PKCE login:

# Browser-based OAuth login (recommended)
aemeathcli auth login claude        # Anthropic
aemeathcli auth login codex         # OpenAI
aemeathcli auth login gemini        # Google
aemeathcli auth login kimi          # Moonshot

# Or set API keys directly
aemeathcli auth set-key claude sk-ant-api03-...
aemeathcli auth set-key codex sk-...
aemeathcli auth set-key gemini AIza...

# Check status
aemeathcli auth status

  claude   ● Logged in ([email protected]) — Pro plan
  codex    ● Logged in ([email protected]) — Plus plan
  gemini   ● Logged in ([email protected])
  kimi     ○ Not logged in

Credentials are stored in your OS keychain (macOS Keychain, Windows Credential Vault, or Linux libsecret). An AES-256-GCM encrypted fallback is used when keychain is unavailable.

# Manage sessions
aemeathcli auth logout codex        # Single provider
aemeathcli auth logout --all        # All providers
aemeathcli auth switch claude       # Set default provider

Usage

Interactive Chat

# Start interactive session
aemeathcli 

# Start with a message
aemeathcli "Explain the architecture of this project"

# Specify model and role
aemeathcli chat --model gpt-5.2 --role coding "Add input validation to the API"

# With a custom system prompt
aemeathcli chat --system "You are a security auditor" "Review this codebase"

Task-Specific Modes

# Planning mode — uses Claude Opus by default
aemeathcli plan "Design a caching layer for the API"

# Code review — analyzes specified files
aemeathcli review src/auth/ src/api/middleware.ts

# Test generation — uses Haiku/Flash for speed
aemeathcli test "Generate tests for the recent changes"

Swarm Mode

Swarm orchestration now lives inside the default TUI:

# Start the CLI
aemeathcli

# Or start with a first task
aemeathcli "Refactor the authentication module"

Inside the TUI:

Press Shift+Tab to switch into swarm mode.
The onboarding flow detects supported native agent CLIs and stores your preferred master provider.
The master agent owns the left half of the split layout; worker agents stack on the right.
AemeathCLI automatically detects your terminal and projects the swarm into native split panes (iTerm2, Ghostty, Terminal.app on macOS; Windows Terminal on Windows; tmux on Linux) while keeping the same hub-and-spoke model.

SDK-backed swarm planning still needs a tool-calling-capable provider, so browser login alone may not be enough; configure an API key or environment variable for the provider you want to sponsor the swarm.

┌───────────────────────┬───────────────────────┐
│ LeadArchitect         │ BackendDev            │
│ (Claude Opus 4.6)     │ (Claude Sonnet 4.6)   │
│ Role: planning        │ Role: coding          │
│                       ├───────────────────────┤
│ Coordinates team,     │ SecurityAuditor       │
│ synthesizes results   │ (GPT-5.2 Codex)       │
│                       │ Role: review          │
└───────────────────────┴───────────────────────┘

Supported Models

AemeathCLI ships with 9 models across 5 providers:

| Model | Provider | Context | Output | Input $/M | Output $/M | |:------|:---------|--------:|-------:|----------:|-----------:| | claude-opus-4-6 | Anthropic | 200K | 32K | $15.00 | $75.00 | | claude-sonnet-4-6 | Anthropic | 200K | 16K | $3.00 | $15.00 | | claude-haiku-4-5 | Anthropic | 200K | 8K | $0.80 | $4.00 | | gpt-5.2 | OpenAI | 256K | 32K | $2.50 | $10.00 | | gpt-5.2-mini | OpenAI | 256K | 16K | $0.15 | $0.60 | | o3 | OpenAI | 256K | 100K | $10.00 | $40.00 | | gemini-2.5-pro | Google | 2M | 64K | $1.25 | $10.00 | | gemini-2.5-flash | Google | 2M | 64K | $0.15 | $0.60 | | kimi-k2.5 | Moonshot | 128K | 8K | $0.50 | $2.00 |

Local models via Ollama (Llama, Mistral, etc.) are also supported with a configurable base URL.

Role-Based Model Routing

AemeathCLI automatically selects the best model for each task through a 4-step resolution pipeline:

User Override  →  Role Config  →  Fallback Chain  →  System Default

Default Role Assignments

| Role | Primary Model | Fallback Chain | |:-----|:--------------|:---------------| | Planning | Claude Opus 4.6 | GPT-5.2 → Gemini 2.5 Pro | | Coding | Claude Sonnet 4.6 | GPT-5.2 → Gemini 2.5 Flash | | Review | Claude Opus 4.6 | Gemini 2.5 Pro | | Testing | Claude Haiku 4.5 | Gemini 2.5 Flash | | Bugfix | Claude Sonnet 4.6 | GPT-5.2 | | Documentation | Gemini 2.5 Flash | Claude Haiku 4.5 |

Override at any time:

# Session-level override
aemeathcli chat --model gpt-5.2 --role planning

# Or interactively
/model gemini-2.5-pro
/role review

Customize routing in ~/.aemeathcli/config.json:

{
  "roles": {
    "coding": {
      "primary": "gpt-5.2",
      "fallback": ["claude-sonnet-4-6", "gemini-2.5-flash"]
    }
  }
}

Agent Teams

Create parallel agent teams through the default swarm experience. The master agent sponsors specialized workers, optional tmux panes open when enabled, and every team follows a hub-and-spoke model.

How It Works

Master-led orchestration -- Start aemeathcli, press Shift+Tab, and describe the task. The configured master agent decomposes the work.
Profile-driven delegation -- The supervisor chooses specialized worker profiles such as developer, reviewer, tester, and architect.
Split-panel mode -- Each worker gets its own native terminal pane. Supports iTerm2, Ghostty, macOS Terminal.app, Windows Terminal, and tmux.
Hub-and-spoke coordination -- A lead agent orchestrates the effort. Workers execute bounded tasks and results are synthesized by the supervisor.
Cross-model teams -- Different providers can be assigned per worker: Claude for planning, Codex for coding, Gemini for documentation and testing.

Split-Panel Backends

AemeathCLI auto-detects your terminal and picks the best split backend:

| Environment | Backend | How | |:------------|:--------|:----| | macOS — iTerm2 | AppleScript | Splits sessions via iTerm2's native AppleScript dictionary | | macOS — Ghostty | System Events | Simulates Ghostty keybindings (Cmd+D / Cmd+Shift+D) for hub-spoke splits | | macOS — Terminal.app | System Events | Simulates Cmd+D to create native split panes | | Windows — Windows Terminal | wt.exe | Uses wt split-pane commands for hub-spoke layout | | Linux (any terminal) | tmux | Creates or reuses a tmux session with split panes | | Fallback | In-process | Tab-switchable agent panels when no native pane support is detected |

macOS — iTerm2 Split Panel

Windows Terminal Split Panel

Hub-and-Spoke Coordination

Following the patterns established by Claude Code Agent Teams and OpenAI Codex Multi-Agent:

                  ┌─────────────────────┐
                  │     Shared Board    │
                  │  /tmp/aemeathcli-*/ │
                  │    board/           │
                  └──┬──────┬──────┬───┘
                     │      │      │
              ┌──────┘      │      └──────┐
              │             │             │
        ┌─────┴─────┐ ┌────┴────┐ ┌──────┴─────┐
        │   Lead    │ │ Agent 2 │ │  Agent 3   │
        │ Writes:   │ │ Writes: │ │ Writes:    │
        │ coord.md  │ │ own .md │ │ own .md    │
        │ SUMMARY.md│ │         │ │            │
        └───────────┘ └─────────┘ └────────────┘

Team manifest (team-manifest.json) -- Full team structure visible to every agent: names, roles, models, output file paths
Lead agent writes coordinator.md with the task breakdown and assignments, then reads all agent outputs to produce SUMMARY.md
Non-lead agents check the coordinator plan, do their bounded work, and write results to their output file
File-based protocol -- No complex IPC needed for coordination. Agents read/write markdown files in the shared board directory.

Cross-Model Teams

Each agent runs a different model selected by the LLM based on role suitability:

[
  { "name": "AuthArchitect", "model": "claude-opus-4-6", "role": "planning" },
  { "name": "BackendDev", "model": "claude-sonnet-4-6", "role": "coding" },
  { "name": "SecurityReviewer", "model": "gpt-5.2-codex", "role": "review" },
  { "name": "TestWriter", "model": "gemini-2.5-flash", "role": "testing" }
]

Team Controls

| Action | How | |:-------|:----| | Enter swarm mode | Start aemeathcli and press Shift+Tab | | Run one task | aemeathcli "Build X" then switch to swarm mode if needed | | Focus next agent | Tab | | Cycle input mode | Shift+Tab | | Stop the active team | /team stop |

Skills System

Extend AemeathCLI with reusable, model-agnostic skill files.

Built-in Skills

| Skill | Trigger | Description | |:------|:--------|:------------| | Code Review | $review | Structured code review with severity ratings | | Commit | $commit | Conventional commit message generation | | Plan | $plan | Architecture and implementation planning | | Debug | $debug | Systematic debugging with hypothesis testing | | Test | $test | Test generation with coverage analysis | | Refactor | $refactor | Safe refactoring with before/after validation |

Custom Skills

Create a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: Custom skill for my workflow
version: 1.0.10
triggers:
  - $my-skill
  - my-skill
allowed-tools:
  - read
  - write
  - bash
model-requirements:
  preferred-role: coding
  min-context: 100000
---

# My Custom Skill

Instructions for the AI when this skill is active...

Skill resolution priority: Project (.aemeathcli/skills/) > User (~/.aemeathcli/skills/) > Built-in

MCP Integration

Connect external tools via the Model Context Protocol:

// ~/.aemeathcli/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"],
      "env": {}
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Features:

stdio + Streamable HTTP transport
Automatic tool discovery -- MCP tools appear alongside built-in tools
Namespaced -- mcp__serverName__toolName prevents conflicts
Rate-limited -- Configurable per-server call limits
Health-checked -- Auto-restart on consecutive failures
Hot-reload -- File watching with live config updates

Interactive Commands

During a chat session:

| Command | Description | |:--------|:------------| | /help | Show available commands | | /model [name] | Switch model or show current | | /model list | List all available models | | /role [name] | Switch role (planning, coding, review, testing, bugfix) | | /cost | Show session cost breakdown | | /clear | Clear conversation history | | /compact | Compress context to free token budget | | /quit | Exit the session |

Configuration

File Locations

~/.aemeathcli/
  config.json          # Global configuration
  credentials.enc      # Encrypted credential fallback
  mcp.json             # MCP server definitions
  skills/              # User-level custom skills
  teams/               # Team configurations
  tasks/               # Task persistence
  db/aemeathcli.db     # SQLite database (WAL mode)
  logs/                # Structured logs (pino)

.aemeathcli/           # Project-level overrides
  config.json          # Project configuration (merges over global)
  skills/              # Project-specific skills
  mcp.json             # Project-specific MCP servers
  AGENTS.md            # Agent instructions

Key Settings

{
  "defaultModel": "claude-sonnet-4-6",
  "permissions": {
    "mode": "standard",
    "allowedPaths": ["./"],
    "blockedCommands": ["rm -rf /", "git push --force"]
  },
  "splitPanel": {
    "enabled": true,
    "backend": "auto",
    "defaultLayout": "auto",
    "maxPanes": 6
  },
  "cost": {
    "budgetWarning": 5.00,
    "budgetHardStop": 20.00,
    "currency": "USD"
  }
}

Permission Modes

| Mode | Behavior | |:-----|:---------| | strict | All operations require explicit approval | | standard | Reads auto-approved; writes and shell require approval | | permissive | All operations auto-approved (trusted environments only) |

aemeathcli --permission-mode strict "Delete all unused imports"

Architecture

aemeathcli/
  src/
    cli/           Command-line interface (Commander.js)
    ui/            Terminal UI components (Ink 5 / React)
    core/          Model router, event bus, context manager, cost tracker
    providers/     AI provider adapters (Vercel AI SDK)
    tools/         Built-in tools (bash, read, write, edit, glob, grep, git, web-fetch)
    auth/          OAuth PKCE login, credential store, session management
    teams/         Agent process management, message bus, task store
    panes/         Split-pane backends (iTerm2, Ghostty, Terminal.app, Windows Terminal, tmux), IPC hub, layout engine
    skills/        Skill loader, registry, executor
    mcp/           MCP client, server manager, tool bridge
    storage/       SQLite store, config store, conversation persistence
    types/         TypeScript type definitions, error hierarchy
    utils/         Logger, sanitizer, path resolver, retry, token counter

Technology Stack

| Layer | Technology | |:------|:-----------| | Runtime | Node.js 20+ | | Language | TypeScript 5.7+ (maximum strict mode) | | CLI Framework | Commander.js 13 | | Terminal UI | Ink 5 (React 18 for CLI) | | AI Integration | Vercel AI SDK + provider adapters | | Database | better-sqlite3 (WAL mode) | | Validation | Zod | | Logging | pino (structured, redacted) | | Auth | keytar (OS keychain) + AES-256-GCM fallback | | Build | tsup (ESM-only, sourcemaps, DTS) | | Testing | Vitest | | Linting | ESLint v9 + typescript-eslint (strict type-checked) |

Security

AemeathCLI is built with defense-in-depth:

Credential storage -- OS keychain primary (macOS Keychain, Windows Credential Vault, Linux libsecret). AES-256-GCM encrypted file fallback with scrypt key derivation (N=32768, r=8, p=1) and per-file random salt.
IPC authentication -- HMAC-SHA256 message signing for all inter-agent communication over Unix domain sockets. Socket permissions set to 0o700.
Shell sandboxing -- Dangerous command blocklist, sensitive environment variable filtering, configurable permission modes with per-operation approval.
Path traversal protection -- All file operations validate resolved paths against the project root boundary.
SSRF protection -- Web fetch blocks private IP ranges (RFC 1918, loopback, link-local, cloud metadata).
Secret redaction -- pino structured logging with 15+ credential field paths redacted. Regex-based secret scrubbing for API keys in command output.
File permissions -- All sensitive files written with 0o600, directories with 0o700.
Typed error hierarchy -- 14 error classes with codes, user messages, diagnostic details, and recovery suggestions. No untyped catch(e) anywhere.

Development

Setup

git clone https://github.com/AemeathCLI/AemeathCLI.git
cd AemeathCLI
npm install

Scripts

npm run build          # Build with tsup
npm run dev            # Watch mode
npm run typecheck      # tsc --noEmit
npm run lint           # ESLint (strict type-checked)
npm run format         # Prettier
npm run test           # Vitest
npm run test:coverage  # With coverage report

License

MIT