pal-code

A terminal coding agent with tool use, built in TypeScript on Bun.

pal-code runs in your project, reads your files, and can edit them — all through a streaming TUI. It's BYOK (bring your own key) and speaks the OpenAI-compatible Chat Completions API, so one adapter drives DeepSeek, Gemini, OpenRouter, OpenCode Zen, OpenAI, Groq, xAI, and Mistral.

Requirements

Bun ≥ 1.1 is required. pal-code uses Bun's built-in modules and cannot run on Node.js.

Install Bun

macOS / Linux:

curl -fsSL https://bun.sh/install | bash

Windows (PowerShell):

powershell -c "irm bun.sh/install.ps1 | iex"

Other methods:

• npm: npm install -g bun
• Homebrew: brew install oven-sh/bun/bun
• Docker: oven/bun

Verify Bun is installed:

bun --version   # Should print 1.1 or higher

Install

npm install -g pal-code

Or with Bun:

bun add -g pal-code

Run

pal

On first launch, pal-code runs a short setup wizard. Pick a provider and paste an API key (or press Enter for a keyless provider like OpenCode Zen).

Features

• TUI built on @earendil-works/pi-tui with streaming markdown, a model picker, session selector, and a live status line (tokens, cache-hit %, cost).
• Tool use — read/write/edit files, run shell commands, grep/glob/ast-grep search, repo maps, verify, and delegate sub-agents.
• BYOK provider registry with key-shape detection, live /models fetching, curated fallback model lists, and retry/backoff with quota-vs-rate-limit-aware fallback switching.
• Safety & context — .pal.json ignore patterns, file-size limits, file snapshots for /undo, context compaction, and secret-redacting debug logs.
• Sessions — SQLite-backed (bun:sqlite) with resume via /sessions or /resume <id>.
• Extensions — install additional tools like web search and multi-agent orchestration.
• MCP — connect to Model Context Protocol servers for external tool integrations.

Extensions

Install extensions from any directory:

pal add @pal-code/web-search      # Web search tools (fetch_url, web_search)
pal add @pal-code/agents          # Multi-agent orchestration (delegate, explore, etc.)

Extensions are installed to ~/.pal/extensions/ and persist across sessions.

MCP (Model Context Protocol)

Add MCP servers for external tool integrations:

pal mcp add filesystem npx @anthropic-ai/mcp-server-filesystem /path/to/dir
pal mcp add github npx @anthropic-ai/mcp-server-github

MCP config is stored in ~/.pal/mcp.json (user-level) or ./mcp.json (project-level).

Configuration

API keys are resolved from (in order):

1. Environment variables — DEEPSEEK_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, ZEN_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, XAI_API_KEY, MISTRAL_API_KEY.
2. ~/.pal/config.json — { "keys": { "<provider>": "<key>" } }.

Keyless providers are opted into by setting "keyless": "<provider-id>".

Data storage

All user data lives in ~/.pal/:

~/.pal/
  config.json        # API keys, default model, extensions list
  sessions.db        # Conversation history (SQLite)
  mcp.json           # MCP server configuration
  extensions/        # Installed extension packages
  snapshots/         # File backups for /undo
  logs/              # Debug logs (when PAL_DEBUG=1)

Slash commands

| Command | Action | |---|---| | /help | Show commands | | /model | Open the model picker | | /model NAME | Set a model directly | | /key | Set an API key interactively | | /keys | Show configured keys | | /sessions / /resume ID | List / resume sessions | | /snapshots / /undo [id] | Restore a pre-edit file | | /compact | Compress conversation context | | /effort low\|medium\|high | Set reasoning effort | | /cost | Show token usage and estimated cost | | /clear | Start a fresh session | | /exit | Save and quit |

Architecture

Logic lives in @pal-code/core; rendering lives in @pal-code/cli.

The one agent loop (runAgent) lives in core and streams events; the CLI only renders them. Full rules, the event protocol, and the termination/interrupt design are in SYSTEM.md.

Development

bun test          # run the test suite
bunx tsc --noEmit # typecheck

Layout

packages/
  core/     # agent loop, providers, tools, session, compaction, snapshots
  cli/      # the TUI front-end (rendering only)
  mcp/      # MCP client integration
  web-search/  # Web search extension
  agents/   # Multi-agent orchestration extension

License

MIT

Roadmap

See EXTENSIONS.md for the extension roadmap (MCP, ACP, session handoff, sandboxing, and OMO-style orchestration).