npm package: @galileodev/cli
Description: Galileo ACE — Agentic Context Engineering CLI
Latest version: 0.10.6

# @galileodev/cli

**The human interface — 21 commands, interactive TUI, web dashboard, and conversational auto-pilot for the Galileo cognitive engine.**

[![Version](https://img.shields.io/badge/version-0.7.9-blue)](./package.json)
[![Node](https://img.shields.io/badge/node-%3E%3D22-green)](./package.json)

## Overview

`@galileodev/cli` is the primary interface between humans and the Galileo cognitive engine. It exposes every capability of `@galileodev/core`, `@galileodev/meta`, and `@galileodev/verify` through a rich command-line interface with human-friendly output formatting, an interactive terminal UI (TUI) for real-time pipeline observation, a web dashboard with analytics and chat, and a conversational auto-pilot that decomposes natural language requests into executable plans.

## Install

```bash
npm install -g @galileodev/cli
```

## Quick Start

```bash
# Initialize Galileo in your project
cd your-project
galileo init

# Generate, verify, and learn from a task
galileo build "Add rate limiting to the API"

# See what Galileo remembers
galileo memory

# Start the interactive auto-pilot
galileo start
```

## Commands

### Core Workflow

| Command | Description |
|---------|-------------|
| `galileo init` | Initialize a `.galileo/` directory with config, starter playbook, and SQLite store |
| `galileo build <instruction>` | Full AC/DC cycle: generate → verify → remediate → learn |
| `galileo analyze <instruction>` | Run the learning pipeline without writing files (extract insights only) |
| `galileo verify` | Run all verification plugins (tsc, eslint, semgrep, tests) on the current project |
| `galileo solve` | Attempt automated remediation of verification failures |

### Memory & Evaluation

| Command | Description |
|---------|-------------|
| `galileo memory` | Display the current playbook with theme-clustered insights |
| `galileo eval <suite.json>` | A/B evaluation: aligned vs. random selection across an instruction suite |
| `galileo benchmark <suite.json>` | Longitudinal benchmark with learning curve tracking |
| `galileo auto-refine <suite.json>` | Bayesian parameter optimization (TPE) for pipeline tuning |

### Prompt Evolution

| Command | Description |
|---------|-------------|
| `galileo evolve <stage>` | Evolve prompt templates via the RatchetOptimizer |
| `galileo prompts` | View active prompt configurations per stage |
| `galileo prompts --history <stage>` | Show template evolution lineage |

### Code Optimization

| Command | Description |
|---------|-------------|
| `galileo optimize-code` | Karpathy tree search for metric-driven code optimization |

### Interactive Modes

| Command | Description |
|---------|-------------|
| `galileo start` | Launch conversational auto-pilot with TUI (default) |
| `galileo start --no-tui` | Launch auto-pilot in legacy REPL mode |
| `galileo dashboard` | Open the web dashboard at `http://localhost:3141` |

### Project Orchestration

| Command | Description |
|---------|-------------|
| `galileo init-project` | Interactive Q&A to generate a phased project plan |
| `galileo self-improve <suite.json>` | Autonomous self-improvement cycles on the playbook |

### Maintenance

| Command | Description |
|---------|-------------|
| `galileo update` | Check for and install Galileo updates |
| `galileo migrate-store` | Migrate playbook from JSONL to SQLite |

## Interactive TUI

When launched via `galileo start`, Galileo presents a full terminal UI built on `@mariozechner/pi-tui` with differential rendering:

**Layout:**
- **Status Bar** (top) — Current pipeline stage, elapsed time, token usage, playbook entry count. Color-coded: blue (running), green (completed), yellow (degraded), red (error).
- **Message List** (middle) — Scrollable history of pipeline events, stage outputs, and user interactions. Renders markdown for trajectories, lessons, and diffs.
- **Input Area** (bottom) — Multi-line editor for instructions and checkpoint decisions.

**Checkpoint Interaction:**
When the pipeline hits a configured checkpoint (e.g., after generation), the TUI presents the stage output and an action menu: Continue, Edit (opens JSON editor with pre-filled content), or Abort (with reason prompt).

**Keyboard shortcuts:** `Ctrl+C` aborts the current stage or quits if idle. `Escape` cancels current input.

## Conversational Auto-Pilot

The `galileo start` command launches a session orchestrator that transforms natural language into executed pipeline actions:

1. **IntentParser** — Regex rules with LLM fallback classify user input into intents (build, analyze, memory, verify, evolve, help, etc.)
2. **Decomposer** — Complex requests are broken into independent, testable steps using the `DEFAULT_DECOMPOSER_TEMPLATE`
3. **PlanExecutor** — Executes steps sequentially with retry/skip/abort support and cross-step context passing
4. **SessionOrchestrator** — Wires parser, decomposer, and executor together with session state management

## Web Dashboard

`galileo dashboard` launches an HTTP server (default port 3141) with:

- **Analytics pages** — Pipeline run history, learning curves, playbook growth
- **Chat interface** — Conversational Q&A about the playbook powered by a read-only `PlaybookAgent` that dispatches tool calls against the playbook store
- **Responsive navbar** — Navigate between analytics, history, and chat views

## Output Formatting

Every command produces human-friendly formatted output through dedicated formatters:

| Formatter | What It Formats |
|-----------|----------------|
| `formatRunResult` | Pipeline run output — insights, artifacts, metadata |
| `formatPlaybook` | Memory display with keyword-based theme clustering |
| `formatBuildResult` | AC/DC cycle results — verification status, remediation attempts |
| `formatVerifyResult` | Verification findings grouped by severity |
| `formatSolveResult` | Remediation outcomes with before/after diffs |
| `formatEvalResult` | A/B comparison tables — aligned vs. random performance |
| `formatOptimizeResult` | Template evolution experiment results |
| `formatTemplates` | Active prompt configurations per stage |
| `formatTuneResult` | Bayesian parameter tuning trial summary |

## Configuration

Galileo reads configuration from `.galileo/config.json` (created by `galileo init`):

```json
{
  "apiKey": "sk-ant-...",
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic",
  "baseUrl": null,
  "pipeline": {
    "isolation": "inline",
    "checkpoints": []
  }
}
```

**Provider options:**
- `"anthropic"` — Direct Anthropic API (default)
- `"pi-ai"` — Multi-provider via pi-ai (set `baseUrl` for local model endpoints)
- `"cli"` — Delegate to Claude CLI

**Pipeline isolation modes:**
- `"inline"` — Stages run in the same process (default, fastest)
- `"isolated"` — Each stage runs in a subprocess
- `"subagent"` — Stages run as independent agents

## Architecture

```
                              galileo CLI
    init · build · analyze · verify · solve · eval · auto-refine
    optimize-code · start · dashboard · evolve · benchmark ·
    prompts · memory · init-project · self-improve · update ·
    migrate-store

    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ Commands │───→│ Config   │───→│ Provider │
    │ (18)     │    │ Loader   │    │ Factory  │
    └──────────┘    └──────────┘    └──────────┘
         │                               │
         v                               v
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ Format   │    │  Session │    │  TUI /   │
    │ Layer    │    │  Orch.   │    │Dashboard │
    └──────────┘    └──────────┘    └──────────┘
```

## Dependencies

| Dependency | Purpose |
|------------|---------|
| `@galileodev/core` | Pipeline engine, playbook store, LLM providers, all core types |
| `@galileodev/meta` | Prompt templates, optimizer, validator |
| `@galileodev/verify` | Verification plugins, AC/DC orchestrator, Karpathy loop |
| `@inquirer/prompts` | Interactive prompts for `init`, `init-project` |
| `@mariozechner/pi-tui` | Terminal UI framework for `galileo start` |
| `@mariozechner/pi-web-ui` | Dashboard web components |
| `commander` | CLI framework and argument parsing |
| `ulid` | Unique ID generation for tasks and sessions |

## Claude Code Plugin

Galileo ships as a Claude Code plugin with 16 skills, 5 pipeline agents, and a session-start hook. The plugin bridges Galileo's cognitive engine with Claude Code's coding agent capabilities — Claude Code writes the code, Galileo ensures each generation is informed by accumulated knowledge.

The postinstall script (`scripts/postinstall.mjs`) displays a welcome banner and points users to `galileo init`.

## Testing

```bash
npm test -w packages/cli
```

Tests cover command execution, output formatting, session orchestration, auto-pilot integration, project management, dashboard API routes, TUI components, and config loading.

## License

See the root [LICENSE](../../LICENSE) file.