### Example flow: mom installing tools and requesting credentials

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/sandbox.md

Example conversation showing how mom installs tools and asks for credentials when needed.

```text
User: "@mom check the spine-runtimes repo"
Mom:  "I need gh CLI. Installing..."
      (runs: apk add github-cli)
Mom:  "I need a GitHub token. Please provide one."
User: "ghp_xxxx..."
Mom:  (runs: echo "ghp_xxxx" | gh auth login --with-token)
Mom:  "Done. Checking repo..."
```

--------------------------------

### Install dependencies

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/web-ui/example/README.md

Run this command to install the required npm packages for the example project.

```bash
npm install
```

--------------------------------

### Install gpt-oss and start vLLM with demo tool server

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/docs/gpt-oss.md

Install the gpt-oss package and start vLLM with the demo tool server. Requires EXA_API_KEY for the search backend and either Docker or PYTHON_EXECUTION_BACKEND=UV for Python execution.

```bash
uv pip install gpt-oss

vllm serve ... --tool-server demo
```

--------------------------------

### Setup: git clone, npm install, build

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/development.md

Commands to clone the repository, install dependencies, and build the project.

```bash
git clone https://github.com/badlogic/pi-mono
cd pi-mono
npm install
npm run build
```

--------------------------------

### Quick Start: Install, Login, and Run AemeathCLI

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/README.md

Quick start commands to install, authenticate, and run AemeathCLI. Requires Node.js >= 20.0.0 and npm >= 9. For orchestrator mode, set ANTHROPIC_API_KEY and OPENAI_API_KEY environment variables.

```bash
npm install -g aemeathcli

aemeathcli login

export ANTHROPIC_API_KEY=your_key_here
export OPENAI_API_KEY=your_key_here

aemeathcli "Refactor the authentication module to use JWT tokens"
```

--------------------------------

### Start GPT-OSS models with pi start

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Commands to set up and start GPT-OSS models. Requires a special vLLM build during setup. GPT-OSS-20B fits on 16GB+ VRAM, GPT-OSS-120B needs 60GB+ VRAM.

```bash
# Requires special vLLM build during setup
pi pods setup gpt-pod "ssh root@1.2.3.4" --models-path /workspace --vllm gpt-oss

# GPT-OSS-20B - Fits on 16GB+ VRAM
pi start openai/gpt-oss-20b --name gpt20

# GPT-OSS-120B - Needs 60GB+ VRAM
pi start openai/gpt-oss-120b --name gpt120
```

--------------------------------

### Quick Start example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/tui/README.md

Shows basic usage of the TUI with Text and Editor components.

```typescript
import { TUI, Text, Editor, ProcessTerminal } from "@mariozechner/pi-tui";

// Create terminal
const terminal = new ProcessTerminal();

// Create TUI
const tui = new TUI(terminal);

// Add components
tui.addChild(new Text("Welcome to my app!"));

const editor = new Editor(tui, editorTheme);
editor.onSubmit = (text) => {
  console.log("Submitted:", text);
  tui.addChild(new Text(`You said: ${text}`));
};
tui.addChild(editor);

// Start
tui.start();
```

--------------------------------

### Quick start: set environment variables and use pi commands

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Sets required environment variables (HF_TOKEN, PI_API_KEY) and demonstrates core pi commands: pod setup, model start, agent messaging, interactive chat, and OpenAI-compatible client configuration.

```bash
# Set required environment variables
export HF_TOKEN=your_huggingface_token      # Get from https://huggingface.co/settings/tokens
export PI_API_KEY=your_api_key              # Any string you want for API authentication

# Setup a DataCrunch pod with NFS storage (models path auto-extracted)
pi pods setup dc1 "ssh root@1.2.3.4" \
  --mount "sudo mount -t nfs -o nconnect=16 nfs.fin-02.datacrunch.io:/your-pseudo /mnt/hf-models"

# Start a model (automatic configuration for known models)
pi start Qwen/Qwen2.5-Coder-32B-Instruct --name qwen

# Send a single message to the model
pi agent qwen "What is the Fibonacci sequence?"

# Interactive chat mode with file system tools
pi agent qwen -i

# Use with any OpenAI-compatible client
export OPENAI_BASE_URL='http://1.2.3.4:8001/v1'
export OPENAI_API_KEY=$PI_API_KEY
```

--------------------------------

### Complete Agent Session Setup

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/sdk.md

A comprehensive example demonstrating authentication storage, model registry, custom tool definition, settings management, and session initialization.

```typescript
import { getModel } from "@mariozechner/pi-ai";
import { Type } from "@sinclair/typebox";
import {
  AuthStorage,
  bashTool,
  createAgentSession,
  DefaultResourceLoader,
  defineTool,
  ModelRegistry,
  readTool,
  SessionManager,
  SettingsManager,
} from "@mariozechner/pi-coding-agent";

// Set up auth storage (custom location)
const authStorage = AuthStorage.create("/custom/agent/auth.json");

// Runtime API key override (not persisted)
if (process.env.MY_KEY) {
  authStorage.setRuntimeApiKey("anthropic", process.env.MY_KEY);
}

// Model registry (no custom models.json)
const modelRegistry = ModelRegistry.create(authStorage);

// Inline tool
const statusTool = defineTool({
  name: "status",
  label: "Status",
  description: "Get system status",
  parameters: Type.Object({}),
  execute: async () => ({
    content: [{ type: "text", text: `Uptime: ${process.uptime()}s` }],
    details: {},
  }),
});

const model = getModel("anthropic", "claude-opus-4-5");
if (!model) throw new Error("Model not found");

// In-memory settings with overrides
const settingsManager = SettingsManager.inMemory({
  compaction: { enabled: false },
  retry: { enabled: true, maxRetries: 2 },
});

const loader = new DefaultResourceLoader({
  cwd: process.cwd(),
  agentDir: "/custom/agent",
  settingsManager,
  systemPromptOverride: () => "You are a minimal assistant. Be concise.",
});
await loader.reload();

const { session } = await createAgentSession({
  cwd: process.cwd(),
  agentDir: "/custom/agent",

  model,
  thinkingLevel: "off",
  authStorage,
  modelRegistry,

  tools: [readTool, bashTool],
  customTools: [statusTool],
  resourceLoader: loader,

  sessionManager: SessionManager.inMemory(),
  settingsManager,
});

session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt("Get status and list files.");
```

--------------------------------

### Quick Start: Streaming and Tool Calls with @mariozechner/pi-ai

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/ai/README.md

Quick start example showing how to use @mariozechner/pi-ai with OpenAI's gpt-4o-mini. It defines a tool with TypeBox schema, builds a Context, streams events (start, text, thinking, toolcall, done, error), handles tool calls, and demonstrates both streaming and non-streaming completion.

```typescript
import { Type, getModel, stream, complete, Context, Tool, StringEnum } from '@mariozechner/pi-ai';

// Fully typed with auto-complete support for both providers and models
const model = getModel('openai', 'gpt-4o-mini');

// Define tools with TypeBox schemas for type safety and validation
const tools: Tool[] = [{
  name: 'get_time',
  description: 'Get the current time',
  parameters: Type.Object({
    timezone: Type.Optional(Type.String({ description: 'Optional timezone (e.g., America/New_York)' }))
  })
}];

// Build a conversation context (easily serializable and transferable between models)
const context: Context = {
  systemPrompt: 'You are a helpful assistant.',
  messages: [{ role: 'user', content: 'What time is it?' }],
  tools
};

// Option 1: Streaming with all event types
const s = stream(model, context);

for await (const event of s) {
  switch (event.type) {
    case 'start':
      console.log(`Starting with ${event.partial.model}`);
      break;
    case 'text_start':
      console.log('\n[Text started]');
      break;
    case 'text_delta':
      process.stdout.write(event.delta);
      break;
    case 'text_end':
      console.log('\n[Text ended]');
      break;
    case 'thinking_start':
      console.log('[Model is thinking...]');
      break;
    case 'thinking_delta':
      process.stdout.write(event.delta);
      break;
    case 'thinking_end':
      console.log('[Thinking complete]');
      break;
    case 'toolcall_start':
      console.log(`\n[Tool call started: index ${event.contentIndex}]`);
      break;
    case 'toolcall_delta':
      // Partial tool arguments are being streamed
      const partialCall = event.partial.content[event.contentIndex];
      if (partialCall.type === 'toolCall') {
        console.log(`[Streaming args for ${partialCall.name}]`);
      }
      break;
    case 'toolcall_end':
      console.log(`\nTool called: ${event.toolCall.name}`);
      console.log(`Arguments: ${JSON.stringify(event.toolCall.arguments)}`);
      break;
    case 'done':
      console.log(`\nFinished: ${event.reason}`);
      break;
    case 'error':
      console.error(`Error: ${event.error}`);
      break;
  }
}

// Get the final message after streaming, add it to the context
const finalMessage = await s.result();
context.messages.push(finalMessage);

// Handle tool calls if any
const toolCalls = finalMessage.content.filter(b => b.type === 'toolCall');
for (const call of toolCalls) {
  // Execute the tool
  const result = call.name === 'get_time'
    ? new Date().toLocaleString('en-US', {
        timeZone: call.arguments.timezone || 'UTC',
        dateStyle: 'full',
        timeStyle: 'long'
      })
    : 'Unknown tool';

  // Add tool result to context (supports text and images)
  context.messages.push({
    role: 'toolResult',
    toolCallId: call.id,
    toolName: call.name,
    content: [{ type: 'text', text: result }],
    isError: false,
    timestamp: Date.now()
  });
}

// Continue if there were tool calls
if (toolCalls.length > 0) {
  const continuation = await complete(model, context);
  context.messages.push(continuation);
  console.log('After tool execution:', continuation.content);
}

console.log(`Total tokens: ${finalMessage.usage.input} in, ${finalMessage.usage.output} out`);
console.log(`Cost: $${finalMessage.usage.cost.total.toFixed(4)}`);

// Option 2: Get complete response without streaming
const response = await complete(model, context);

for (const block of response.content) {
  if (block.type === 'text') {
    console.log(block.text);
  } else if (block.type === 'toolCall') {
    console.log(`Tool: ${block.name}(${JSON.stringify(block.arguments)})`);
  }
}
```

--------------------------------

### Run MCP SSE servers and start vLLM with them

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/docs/gpt-oss.md

Run the example MCP SSE servers for browser and Python tools, then start vLLM with the tool-server flag pointing to their URLs. The servers must implement 'instructions' in server info and well-documented tools.

```bash
mcp run -t sse browser_server.py:mcp
mcp run -t sse python_server.py:mcp

vllm serve ... --tool-server ip-1:port-1,ip-2:port-2
```

--------------------------------

### Quick Start: Set up storage, agent, and chat panel

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/web-ui/README.md

TypeScript example showing how to configure IndexedDB storage for settings, provider keys, and sessions, create an Agent with a system prompt and model, then create and append a ChatPanel to the page. Requires the main package imports and the app.css file.

```typescript
import { Agent } from '@mariozechner/pi-agent-core';
import { getModel } from '@mariozechner/pi-ai';
import {
  ChatPanel,
  AppStorage,
  IndexedDBStorageBackend,
  ProviderKeysStore,
  SessionsStore,
  SettingsStore,
  setAppStorage,
  defaultConvertToLlm,
  ApiKeyPromptDialog,
} from '@mariozechner/pi-web-ui';
import '@mariozechner/pi-web-ui/app.css';

// Set up storage
const settings = new SettingsStore();
const providerKeys = new ProviderKeysStore();
const sessions = new SessionsStore();

const backend = new IndexedDBStorageBackend({
  dbName: 'my-app',
  version: 1,
  stores: [
    settings.getConfig(),
    providerKeys.getConfig(),
    sessions.getConfig(),
    SessionsStore.getMetadataConfig(),
  ],
});

settings.setBackend(backend);
providerKeys.setBackend(backend);
sessions.setBackend(backend);

const storage = new AppStorage(settings, providerKeys, sessions, undefined, backend);
setAppStorage(storage);

// Create agent
const agent = new Agent({
  initialState: {
    systemPrompt: 'You are a helpful assistant.',
    model: getModel('anthropic', 'claude-sonnet-4-5-20250929'),
    thinkingLevel: 'off',
    messages: [],
    tools: [],
  },
  convertToLlm: defaultConvertToLlm,
});

// Create chat panel
const chatPanel = new ChatPanel();
await chatPanel.setAgent(agent, {
  onApiKeyRequired: (provider) => ApiKeyPromptDialog.prompt(provider),
});

document.body.appendChild(chatPanel);
```

--------------------------------

### SSH git install examples

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/packages.md

Shows SSH-based git installs: shorthand requires `git:` prefix, `ssh://` protocol format, and version ref usage. SSH URLs use configured SSH keys automatically.

```bash
# git@host:path shorthand (requires git: prefix)
pi install git:git@github.com:user/repo

# ssh:// protocol format
pi install ssh://git@github.com/user/repo

# With version ref
pi install git:git@github.com:user/repo@v1.0.0
```

--------------------------------

### SKILL.md format example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/skills.md

Complete example of a SKILL.md file with frontmatter, setup instructions, and usage. Includes nested bash code blocks.

```markdown
---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

# My Skill

## Setup

Run once before first use:
```bash
cd /path/to/skill && npm install
```

## Usage

```bash
./scripts/process.sh <input>
```
```

--------------------------------

### Start custom models with --vllm

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Commands to start custom models not in the predefined list by passing arguments directly to vLLM with --vllm. Examples include DeepSeek with tensor parallelism, Mistral with pipeline parallelism, and any model with a specific tool parser.

```bash
# DeepSeek with custom settings
pi start deepseek-ai/DeepSeek-V3 --name deepseek --vllm \
  --tensor-parallel-size 4 --trust-remote-code

# Mistral with pipeline parallelism
pi start mistralai/Mixtral-8x22B-Instruct-v0.1 --name mixtral --vllm \
  --tensor-parallel-size 8 --pipeline-parallel-size 2

# Any model with specific tool parser
pi start some/model --name mymodel --vllm \
  --tool-call-parser hermes --enable-auto-tool-choice
```

--------------------------------

### Quick Start: Create Agent Session and Stream Output

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/sdk.md

Minimal setup for creating an agent session with in-memory storage and streaming text deltas to stdout. Requires the @mariozechner/pi-coding-agent package.

```typescript
import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@mariozechner/pi-coding-agent";

// Set up credential storage and model registry
const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt("What files are in the current directory?");
```

--------------------------------

### Start Model with Custom vLLM Arguments

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Pass custom vLLM arguments after --vllm when starting a model. This example enables AWQ quantization, prefix caching, sets max sequences to 256, and GPU memory utilization to 0.95.

```bash
# Pass any vLLM argument after --vllm
pi start model --name custom --vllm \
  --quantization awq \
  --enable-prefix-caching \
  --max-num-seqs 256 \
  --gpu-memory-utilization 0.95
```

--------------------------------

### Vim Keybindings Example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/keybindings.md

An example configuration mapping common Vim-style navigation keys.

```json
{
  "tui.editor.cursorUp": ["up", "alt+k"],
  "tui.editor.cursorDown": ["down", "alt+j"],
  "tui.editor.cursorLeft": ["left", "alt+h"],
  "tui.editor.cursorRight": ["right", "alt+l"],
  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
}
```

--------------------------------

### Quick Start: Create container and run mom with Docker sandbox

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/sandbox.md

Creates and starts the Docker container, then runs mom with the Docker sandbox. The data directory is mounted as /workspace.

```bash
cd packages/mom
./docker.sh create ./data

# 2. Run mom with Docker sandbox
mom --sandbox=docker:mom-sandbox ./data
```

--------------------------------

### Install the package

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/web-ui/README.md

Command to install the web UI package along with its core dependencies.

```bash
npm install @mariozechner/pi-web-ui @mariozechner/pi-agent-core @mariozechner/pi-ai
```

--------------------------------

### Start Qwen models with pi start

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Commands to start Qwen models using pi start. Qwen2.5-Coder-32B fits on a single H100/H200, Qwen3-Coder-30B offers advanced reasoning with tool use, and Qwen3-Coder-480B runs on 8xH200 in data-parallel mode.

```bash
# Qwen2.5-Coder-32B - Excellent coding model, fits on single H100/H200
pi start Qwen/Qwen2.5-Coder-32B-Instruct --name qwen

# Qwen3-Coder-30B - Advanced reasoning with tool use
pi start Qwen/Qwen3-Coder-30B-A3B-Instruct --name qwen3

# Qwen3-Coder-480B - State-of-the-art on 8xH200 (data-parallel mode)
pi start Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 --name qwen-480b
```

--------------------------------

### Start DOOM overlay in pi

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/examples/extensions/doom-overlay/README.md

After launching pi with the extension, run this command to start the DOOM overlay.

```bash
/doom-overlay
```

--------------------------------

### Initialize AemeathCLI Configuration

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/README.md

Launches an interactive setup wizard for provider authentication, detection of installed agent CLIs, and selection of the master provider for swarm orchestration. SDK-backed swarm features still require `aemeathcli auth set-key <provider>` or matching environment variables when browser login is not enough.

```bash
aemeathcli config init
```

--------------------------------

### Install @mariozechner/pi-coding-agent

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/sdk.md

Installs the SDK package. The SDK is included in the main package, so no separate installation is needed.

```bash
npm install @mariozechner/pi-coding-agent
```

--------------------------------

### Emacs Keybindings Example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/keybindings.md

An example configuration mapping common Emacs-style navigation and editing keys.

```json
{
  "tui.editor.cursorUp": ["up", "ctrl+p"],
  "tui.editor.cursorDown": ["down", "ctrl+n"],
  "tui.editor.cursorLeft": ["left", "ctrl+b"],
  "tui.editor.cursorRight": ["right", "ctrl+f"],
  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
  "tui.input.newLine": ["shift+enter", "ctrl+j"]
}
```

--------------------------------

### Run SDK example with npx tsx

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/examples/sdk/README.md

Run the minimal SDK example from the coding-agent package directory.

```bash
cd packages/coding-agent
npx tsx examples/sdk/01-minimal.ts
```

--------------------------------

### Run Isolated Mom Instances with Docker Sandbox

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/README.md

Example setup for running separate mom instances with different access levels. The first instance uses limited credentials for general teams, while the second uses privileged credentials for executive teams.

```bash
# General team mom (limited access)
mom --sandbox=docker:mom-general ./data-general

# Executive team mom (full access)
mom --sandbox=docker:mom-exec ./data-exec
```

--------------------------------

### Start pi with --no-tools and extension

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/extensions.md

Start pi without any built-in tools, leaving only extension tools. Use --no-tools with -e to load an extension that provides all tools.

```bash
# No built-in tools, only extension tools
pi --no-tools -e ./my-extension.ts
```

--------------------------------

### Start CLI for swarm mode

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/README.md

Shows how to start the CLI to access swarm mode, either with no arguments or with an initial task.

```bash
# Start the CLI
aemeathcli

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

--------------------------------

### One-Liner Network Setup in VM

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/v86.md

One-liner version of the network setup commands, chaining them with && for quick execution.

```bash
modprobe virtio-net && ip link set eth0 up && udhcpc -i eth0
```

--------------------------------

### Install v86 and ws dependencies

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/v86.md

Install the v86 emulator and the ws WebSocket library using npm.

```bash
npm install v86 ws
```

--------------------------------

### SKILL.md frontmatter example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/README.md

Example of a SKILL.md file with frontmatter defining the skill name and description.

```markdown
---
name: gmail
description: Read, search, and send Gmail via IMAP/SMTP
---

# Gmail Skill
...
```

--------------------------------

### Model management commands (pi start, stop, list, logs)

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Commands to start, stop, list, and view logs for models. Start options include --memory (default 90%), --context, --gpus, --pod, and --vllm for custom vLLM arguments.

```bash
pi start <model> --name <name> [options]  # Start a model
  --memory <percent>      # GPU memory: 30%, 50%, 90% (default: 90%)
  --context <size>        # Context window: 4k, 8k, 16k, 32k, 64k, 128k
  --gpus <count>          # Number of GPUs to use (predefined models only)
  --pod <name>            # Target specific pod (overrides active)
  --vllm <args...>        # Pass custom args directly to vLLM

pi stop [<name>]          # Stop model (or all if no name given)
pi list                   # List running models with status
pi logs <name>            # Stream model logs (tail -f)
```

--------------------------------

### Install Node.js dependencies

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/artifacts-server.md

Initializes a Node.js project in /workspace/artifacts and installs the required packages: express, ws, and chokidar.

```bash
cd /workspace/artifacts
npm init -y
npm install express ws chokidar
```

--------------------------------

### Run chat-simple.ts example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/tui/README.md

Runs the complete chat interface example from the test directory. The example demonstrates markdown messages with custom background colors, a loading spinner, an editor with autocomplete and slash commands, and spacers between messages.

```bash
npx tsx test/chat-simple.ts
```

--------------------------------

### Install vLLM with tool-call support

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/docs/qwen3-coder.md

Creates a virtual environment and installs vLLM with the auto torch backend. Required for Qwen3-Coder tool-call functionality in vLLM v0.10.0 and higher.

```bash
uv venv
source .venv/bin/activate
uv pip install -U vllm --torch-backend auto
```

--------------------------------

### Install pi-coding-agent globally with npm

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/README.md

Install the pi CLI tool globally using npm.

```bash
npm install -g @mariozechner/pi-coding-agent
```

--------------------------------

### Install Cloudflared (Cloudflare Tunnel)

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/artifacts-server.md

Downloads the latest cloudflared binary, moves it to /usr/local/bin, makes it executable, and verifies the installation with --version.

```bash
wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
mv cloudflared-linux-amd64 /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared
cloudflared --version
```

--------------------------------

### Try a package with -e (--extension)

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/packages.md

Try a package without installing it permanently. Installs to a temporary directory for the current run only.

```bash
pi -e npm:@foo/bar
pi -e git:github.com/user/repo
```

--------------------------------

### Clone and install AemeathCLI

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/README.md

Clones the AemeathCLI repository and installs its dependencies. Run these commands in a terminal to set up the project for development.

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

--------------------------------

### pi.getSessionName() get session name

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/extensions.md

Gets the current session name, if set. The example logs the name to the console when it exists.

```typescript
const name = pi.getSessionName();
if (name) {
  console.log(`Session: ${name}`);
}
```

--------------------------------

### Example settings.json

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/settings.md

Shows the full settings structure with default provider, model, thinking level, theme, compaction, retry, enabled models, and packages.

```json
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "packages": ["pi-skills"]
}
```

--------------------------------

### Use your existing subscription

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/README.md

Start pi and use /login to select a provider for subscription-based authentication.

```bash
pi
/login  # Then select provider
```

--------------------------------

### Migration: Before (0.30.x) - Agent with ProviderTransport

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/web-ui/CHANGELOG.md

Shows the old way of creating an Agent with a ProviderTransport and a messageTransformer. This is the 'before' example for the 0.31.0 migration guide.

```typescript
import { Agent, ProviderTransport, type AppMessage } from '@mariozechner/pi-web-ui';

const agent = new Agent({
  transport: new ProviderTransport(),
  messageTransformer: (messages: AppMessage[]) => messages.filter(...)
});
```

--------------------------------

### Usage examples for invoking templates

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/prompt-templates.md

Shows how to invoke templates with `/` and pass arguments.

```text
/review                           # Expands review.md
/component Button                 # Expands with argument
/component Button "click handler" # Multiple arguments

```

--------------------------------

### settings.json npmCommand example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/packages.md

Sets `npmCommand` in `settings.json` to pin npm package lookup and install operations to a specific wrapper command such as `mise` or `asdf`.

```json
{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}
```

--------------------------------

### Launch pi with DOOM Overlay extension

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/examples/extensions/doom-overlay/README.md

Run this command to start pi with the DOOM Overlay extension. The shareware WAD file (~4MB) is auto-downloaded on first run.

```bash
pi --extension ./examples/extensions/doom-overlay
```

--------------------------------

### SettingsStore key-value operations

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/web-ui/README.md

Shows how to set and get key-value settings using the storage.settings API. The example sets a boolean and a string, then retrieves the boolean value.

```typescript
await storage.settings.set('proxy.enabled', true);
await storage.settings.set('proxy.url', 'https://proxy.example.com');
const enabled = await storage.settings.get<boolean>('proxy.enabled');
```

--------------------------------

### packages setting string form example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/settings.md

Loads all resources from the specified npm/git packages.

```json
{
  "packages": ["pi-skills", "@org/my-extension"]
}
```

--------------------------------

### Plan format example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/examples/extensions/plan-mode/README.md

Shows the expected format for a plan output: a 'Plan:' header followed by numbered steps. The agent should output this when asked to create a plan.

```markdown
Plan:
1. First step description
2. Second step description
3. Third step description
```

--------------------------------

### JSONL event stream output

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Example JSONL output from the --json flag, showing the event stream with user message, assistant start, assistant message, and token usage events.

```jsonl
{"type":"user_message","text":"What is 2+2?"}
{"type":"assistant_start"}
{"type":"assistant_message","text":"2 + 2 = 4"}
{"type":"token_usage","inputTokens":10,"outputTokens":5,"totalTokens":15,"cacheReadTokens":0,"cacheWriteTokens":0}
```

--------------------------------

### SettingsManager usage examples

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/sdk.md

Shows how to create a session with default settings, apply overrides, use in-memory settings, and specify custom directories.

```typescript
import { createAgentSession, SettingsManager, SessionManager } from "@mariozechner/pi-coding-agent";

// Default: loads from files (global + project merged)
const { session } = await createAgentSession({
  settingsManager: SettingsManager.create(),
});

// With overrides
const settingsManager = SettingsManager.create();
settingsManager.applyOverrides({
  compaction: { enabled: false },
  retry: { enabled: true, maxRetries: 5 },
});
const { session } = await createAgentSession({ settingsManager });

// In-memory (no file I/O, for testing)
const { session } = await createAgentSession({
  settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
  sessionManager: SessionManager.inMemory(),
});

// Custom directories
const { session } = await createAgentSession({
  settingsManager: SettingsManager.create("/custom/cwd", "/custom/agent"),
});
```

--------------------------------

### Override Active Pod with --pod Flag

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Override the active pod for any command by specifying the --pod flag. This example shows starting a model, listing pods, and stopping a model on specific pods.

```bash
# Override active pod for any command
pi start model --name test --pod dev-pod
pi list --pod prod-pod
pi stop test --pod dev-pod
```

--------------------------------

### package.json for extension with dependencies

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/extensions.md

Example package.json for an extension that uses npm packages. Declares dependencies (zod, chalk) and the pi.extensions entry point. Run npm install in the extension directory to make imports from node_modules work.

```json
// package.json
{
  "name": "my-extension",
  "dependencies": {
    "zod": "^3.0.0",
    "chalk": "^5.0.0"
  },
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}
```

--------------------------------

### Install vLLM with gpt-oss support using uv

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/docs/gpt-oss.md

Creates a virtual environment and installs a prerelease version of vLLM with gpt-oss support, along with nightly PyTorch and other dependencies. Use this in a fresh virtual environment as the first iteration requires cutting-edge kernels.

```bash
uv venv
source .venv/bin/activate

uv pip install --pre vllm==0.10.1+gptoss \
    --extra-index-url https://wheels.vllm.ai/gpt-oss/ \
    --extra-index-url https://download.pytorch.org/whl/nightly/cu128 \
    --index-strategy unsafe-best-match
```

--------------------------------

### Pi Package Installation Commands

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/README.md

Commands to install, remove, list, update, and configure pi packages. Supports npm, git, and SSH sources. Use -l for project-local installs. Git packages install dependencies with npm install --omit=dev.

```bash
pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3      # pinned version
pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1  # tag or commit
pi install git:git@github.com:user/repo
pi install git:git@github.com:user/repo@v1  # tag or commit
pi install https://github.com/user/repo
pi install https://github.com/user/repo@v1      # tag or commit
pi install ssh://git@github.com/user/repo
pi install ssh://git@github.com/user/repo@v1    # tag or commit
pi remove npm:@foo/pi-tools
pi uninstall npm:@foo/pi-tools          # alias for remove
pi list
pi update                               # skips pinned packages
pi config                               # enable/disable extensions, skills, prompts, themes
```

--------------------------------

### Make start-server.sh executable

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/artifacts-server.md

Makes the start-server.sh script executable.

```bash
chmod +x /workspace/artifacts/start-server.sh
```

--------------------------------

### Install AemeathCLI Globally

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/README.md

Installs AemeathCLI globally. The CLI installs two commands: `aemeathcli` and the shorthand `ac`.

```bash
npm install -g aemeathcli
```

--------------------------------

### createAgentSession() quick reference

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/examples/sdk/README.md

Quick reference for createAgentSession() covering minimal, custom model, prompt override, read-only tools, in-memory sessions, and full control with custom auth, registry, resource loader, tools, and settings. Note that the full-control example references myExtension and myTool which are not defined in the snippet.

```typescript
import { getModel } from "@mariozechner/pi-ai";
import {
  AuthStorage,
  createAgentSession,
  DefaultResourceLoader,
  ModelRegistry,
  SessionManager,
  SettingsManager,
  codingTools,
  readOnlyTools,
  readTool, bashTool, editTool, writeTool,
} from "@mariozechner/pi-coding-agent";

// Auth and models setup
const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);

// Minimal
const { session } = await createAgentSession({ authStorage, modelRegistry });

// Custom model
const model = getModel("anthropic", "claude-opus-4-5");
const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });

// Modify prompt
const loader = new DefaultResourceLoader({
  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
});
await loader.reload();
const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });

// Read-only
const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry });

// In-memory
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

// Full control
const customAuth = AuthStorage.create("/my/app/auth.json");
customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
const customRegistry = ModelRegistry.create(customAuth);

const resourceLoader = new DefaultResourceLoader({
  systemPromptOverride: () => "You are helpful.",
  extensionFactories: [myExtension],
  skillsOverride: () => ({ skills: [], diagnostics: [] }),
  agentsFilesOverride: () => ({ agentsFiles: [] }),
  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
});
await resourceLoader.reload();

const { session } = await createAgentSession({
  model,
  authStorage: customAuth,
  modelRegistry: customRegistry,
  resourceLoader,
  tools: [readTool, bashTool],
  customTools: [{ tool: myTool }],
  sessionManager: SessionManager.inMemory(),
  settingsManager: SettingsManager.inMemory(),
});

// Run prompts
session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});
await session.prompt("Hello");
```

--------------------------------

### Install @mariozechner/pi-agent-core with npm

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/agent/README.md

Install the package using npm. This is the standard installation command for the agent core package.

```bash
npm install @mariozechner/pi-agent-core
```

--------------------------------

### pi install <source> [-l]

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/README.md

Installs a package. The -l flag installs the package project-locally. This is a package management subcommand.

```APIDOC
## pi install <source> [-l]

### Description
Installs a package. Use `-l` to install the package project-locally.

### Usage
```bash
pi install <source> [-l]
```

### Parameters
- `source` (string) - Required - The package source to install.
- `-l` (flag) - Optional - Install package project-locally.
```

--------------------------------

### Attachment type example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/rpc.md

Example of the Attachment type.

```json
{
  "id": "img1",
  "type": "image",
  "fileName": "photo.jpg",
  "mimeType": "image/jpeg",
  "size": 102400,
  "content": "base64-encoded-data...",
  "extractedText": null,
  "preview": null
}
```

--------------------------------

### ToolResultMessage type example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/rpc.md

Example of the ToolResultMessage type.

```json
{
  "role": "toolResult",
  "toolCallId": "call_123",
  "toolName": "bash",
  "content": [{"type": "text", "text": "total 48\ndrwxr-xr-x ..."}],
  "isError": false,
  "timestamp": 1733234567890
}
```

--------------------------------

### Create custom theme directory and file

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/themes.md

Create a theme file at ~/.pi/agent/themes/my-theme.json. The directory must exist before creating the file.

```bash
mkdir -p ~/.pi/agent/themes
vim ~/.pi/agent/themes/my-theme.json
```

--------------------------------

### Install Pi on Termux

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/termux.md

Commands to update packages, install dependencies (nodejs, termux-api, git), install Pi globally, create the config directory, and run Pi.

```bash
# Update packages
pkg update && pkg upgrade

# Install dependencies
pkg install nodejs termux-api git

# Install pi
npm install -g @mariozechner/pi-coding-agent

# Create config directory
mkdir -p ~/.pi/agent

# Run pi
pi
```

--------------------------------

### Install blobfile

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/docs/kimi-k2.md

Installs the blobfile package, a prerequisite for TensorRT-LLM deployment.

```bash
pip install blobfile
```

--------------------------------

### Clone and install rootlessRelay

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/v86.md

Clone the rootlessRelay repository and install its npm dependencies.

```bash
git clone https://github.com/obegron/rootlessRelay.git
cd rootlessRelay
npm install
```

--------------------------------

### Start GLM models with pi start

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Commands to start GLM models. GLM-4.5 requires 8-16 GPUs and includes thinking mode, while GLM-4.5-Air is a smaller version needing 1-2 GPUs.

```bash
# GLM-4.5 - Requires 8-16 GPUs, includes thinking mode
pi start zai-org/GLM-4.5 --name glm

# GLM-4.5-Air - Smaller version, 1-2 GPUs
pi start zai-org/GLM-4.5-Air --name glm-air
```

--------------------------------

### Basic CLI Usage: pi [options] [@files...] [messages...]

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/README.md

Shows the general syntax for invoking the pi command. Use this as a starting point for any pi invocation.

```bash
pi [options] [@files...] [messages...]
```

--------------------------------

### Install dependencies from requirements.txt

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/docs/gml-4.5.md

Install required Python packages using pip as specified in requirements.txt.

```shell
pip install -r requirements.txt
```

--------------------------------

### Launch vLLM server with Data Parallelism and Expert Parallelism (H200 example, node 0 and node 1)

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/docs/kimi-k2.md

Run Kimi-K2 on a 16-GPU cluster with Data Parallelism and Expert Parallelism. Commands are for node 0 and node 1, each using 8 GPUs. Requires DeepEP and DeepGEMM libraries and vLLM v0.10.0rc1 or later.

```bash
# node 0
vllm serve $MODEL_PATH --port 8000 --served-model-name kimi-k2 --trust-remote-code --data-parallel-size 16 --data-parallel-size-local 8 --data-parallel-address $MASTER_IP --data-parallel-rpc-port $PORT --enable-expert-parallel --max-num-batched-tokens 8192 --max-num-seqs 256 --gpu-memory-utilization 0.85 --enable-auto-tool-choice --tool-call-parser kimi_k2

# node 1
vllm serve $MODEL_PATH --headless --data-parallel-start-rank 8 --port 8000 --served-model-name kimi-k2 --trust-remote-code --data-parallel-size 16 --data-parallel-size-local 8 --data-parallel-address $MASTER_IP --data-parallel-rpc-port $PORT --enable-expert-parallel --max-num-batched-tokens 8192 --max-num-seqs 256 --gpu-memory-utilization 0.85 --enable-auto-tool-choice --tool-call-parser kimi_k2
```

--------------------------------

### Install @mariozechner/pi-mom via npm

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/README.md

Install the package using npm. Requires Node.js and npm.

```bash
npm install @mariozechner/pi-mom
```

--------------------------------

### Troubleshoot Model Startup with pi ssh, pi list, and pi stop

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Use these commands to diagnose why a model won't start. Check GPU usage with nvidia-smi, verify the port isn't in use with pi list, and force stop all models with pi stop.

```bash
# Check GPU usage
pi ssh "nvidia-smi"

# Check if port is in use
pi list

# Force stop all models
pi stop
```

--------------------------------

### Start model with custom context and memory

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/pods/README.md

Starts a model with a 64k context window and 70% GPU memory allocation for coding workloads. The --memory, --context, and --gpus parameters are ignored when --vllm is used, and a warning is shown.

```bash
# Large context for code analysis, moderate concurrency
pi start Qwen/Qwen2.5-Coder-32B-Instruct --name coder \
  --context 64k --memory 70%
```

--------------------------------

### Start artifacts server with start-server.sh

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/mom/docs/artifacts-server.md

Starts the Node.js server on localhost:8080, creates a Cloudflare Tunnel with a public URL, prints the URL (e.g., https://random-words-123.trycloudflare.com), and saves it to /tmp/artifacts-url.txt. The URL changes on every restart due to the free Cloudflare Tunnel limitation.

```bash
cd /workspace/artifacts
./start-server.sh
```

--------------------------------

### Install @mariozechner/pi-ai

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/ai/README.md

Installs the @mariozechner/pi-ai package. TypeBox exports (Type, Static, TSchema) are re-exported from this package.

```bash
npm install @mariozechner/pi-ai
```

--------------------------------

### UserMessage type example

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/pi-mono-main/packages/coding-agent/docs/rpc.md

Example of the UserMessage type. The content field can be a string or an array of TextContent/ImageContent blocks.

```json
{
  "role": "user",
  "content": "Hello!",
  "timestamp": 1733234567890,
  "attachments": []
}
```

--------------------------------

### Build from source with esbuild

Source: https://github.com/zacharyzhang-ny/aemeathcli/blob/main/claudecode-reference/QUICKSTART.md

Steps to install esbuild, run the build script, and test the output. The build script transforms feature flags and bundles with esbuild.

```bash
cd claude-code-2.1.88/

# 1. Install build dependency
npm install --save-dev esbuild

# 2. Run the build script
node scripts/build.mjs

# 3. If successful, run the output:
node dist/cli.js --version
```