ZacharyZhang-NY/AemeathCLI

 A E M E A T H 

Next-generation multi-model CLI coding tool
Agent teams · Split-panel coordination · Role-based routing

  ╔══════════════════════════════════════════════╗
  ║           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.

Table of Contents

• Why AemeathCLI
• Quick Start
• Installation
• Authentication
• Usage
• Supported Models
• Role-Based Model Routing
• Agent Teams
• Skills System
• MCP Integration
• Interactive Commands
• Configuration
• Architecture
• Security
• Development
• License

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 (user@example.com) — Pro plan
  codex    ● Logged in (user@example.com) — Plus plan
  gemini   ● Logged in (user@gmail.com)
  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

1. Master-led orchestration -- Start aemeathcli, press Shift+Tab, and describe the task. The configured master agent decomposes the work.
2. Profile-driven delegation -- The supervisor chooses specialized worker profiles such as developer, reviewer, tester, and architect.
3. Split-panel mode -- Each worker gets its own native terminal pane. Supports iTerm2, Ghostty, macOS Terminal.app, Windows Terminal, and tmux.
4. Hub-and-spoke coordination -- A lead agent orchestrates the effort. Workers execute bounded tasks and results are synthesized by the supervisor.
5. 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