Forge TUI

A beautiful terminal UI for the Forge AI Coding Agent, built with Ink (React for CLI).

Features

• 🎨 Beautiful UI - Modern terminal interface with themes
• 💬 Streaming Output - Real-time response streaming
• 🔨 Tool Visualization - See tool calls with parameters and results
• 📋 Task List - Track progress with todo list
• 🎯 Command Palette - Quick access to all commands (Ctrl+P)
• 📚 Session Management - Browse, switch, and delete sessions
• ⚡ Confirmation Dialogs - Safe execution of dangerous operations

Requirements

• Node.js >= 18
• Forge SDK (built from ../forge/crates/forge-napi)

Installation

# Install dependencies
npm install

# Build the NAPI SDK first (if not already built)
cd ../forge/crates/forge-napi
npm install
npm run build
cd -

# Run in development mode
npm run dev

Configuration

Create a .env file or set environment variables:

# Required: API Key
FORGE_LLM_API_KEY=your-api-key

# Optional: Model configuration
FORGE_LLM_MODEL=claude-sonnet-4-5-20250929
FORGE_LLM_MODE=anthropic.messages  # or openai.chat
FORGE_LLM_BASE_URL=  # Custom endpoint (optional)

Usage

# Run with environment variables
FORGE_LLM_API_KEY=your-key npx tsx src/index.tsx

# Or with OpenAI-compatible endpoint
FORGE_LLM_MODE=openai.chat \
FORGE_LLM_API_KEY=your-key \
FORGE_LLM_BASE_URL=https://api.openai.com/v1 \
FORGE_LLM_MODEL=gpt-4 \
npx tsx src/index.tsx

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Enter | Submit input | | Ctrl+P | Open command palette | | Ctrl+O | Open session browser | | Ctrl+L | Clear messages | | Ctrl+S | Save session | | Ctrl+C | Cancel operation / Exit | | Ctrl+D | Exit | | Alt+↑/↓ | Browse input history | | Esc | Close dialogs |

Architecture

forge-tui/
├── src/
│   ├── index.tsx           # Entry point
│   ├── app.tsx             # Main app component
│   ├── components/         # UI components
│   │   ├── Header.tsx      # Status bar
│   │   ├── Footer.tsx      # Shortcuts bar
│   │   ├── InputBox.tsx    # Text input
│   │   ├── MessageList.tsx # Message container
│   │   ├── Message.tsx     # Single message
│   │   ├── CommandPalette.tsx
│   │   ├── SessionBrowser.tsx
│   │   ├── ConfirmDialog.tsx
│   │   └── TodoList.tsx
│   ├── hooks/              # React hooks
│   │   ├── useSDK.ts       # SDK wrapper
│   │   └── useTheme.ts     # Theme access
│   ├── state/              # TEA state management
│   │   ├── reducer.ts      # State transitions
│   │   └── context.ts      # React context
│   ├── themes/             # Color themes
│   │   ├── dark.ts
│   │   └── light.ts
│   ├── utils/              # Utilities
│   │   └── markdown.ts     # Markdown rendering
│   └── types/              # TypeScript types
│       ├── sdk.ts          # SDK type re-exports
│       └── app.ts          # App state types

State Management

Uses TEA (The Elm Architecture) pattern:

• Model: AppState in types/app.ts
• Update: reducer in state/reducer.ts
• View: React components

SDK Integration

The TUI communicates with the Forge Rust SDK through NAPI bindings:

import { ForgeConfig, ForgeSdk } from '@anthropic/forge-sdk';

const config = ForgeConfig.fromEnv();
const sdk = new ForgeSdk(config);
await sdk.init();

// Process messages with streaming
await sdk.process("Hello!", (err, event) => {
  console.log(event.eventType, event);
});

Development

# Type check
npm run typecheck

# Run in watch mode
npm run dev

# Build for production
npm run build

License

MIT