Popeye

A terminal-based AI coding agent — fully local. No server, no auth, no account.

Plan and build inside your project with a Bun-powered CLI, OpenTUI + React interface, AI SDK streaming, and a local SQLite session store. Bring your own keys (Anthropic, OpenAI) or run models locally with Ollama.

         

Features

• Terminal AI Chat — A coding assistant that runs entirely in your terminal, built with OpenTUI and React.
• Plan and Build Modes — PLAN gives the agent read-only analysis tools; BUILD enables file writes, edits, and shell execution. Switch with /agents.
• Bring Your Own Keys — Configure Anthropic and/or OpenAI in-app, or point at a local Ollama instance. No server, no OAuth, no account. Config is stored locally with 0600 permissions.
• Multi-Model Support — Anthropic (Sonnet / Haiku / Opus 4-6), OpenAI (gpt-5.4 / mini / nano), and any model served by Ollama (auto-discovered via /api/tags). Switch live with /models.
• Reasoning / Thinking — Extended thinking is enabled for Claude Opus/Sonnet and detailed reasoning summaries for gpt-5.4. Reasoning output is collapsible (Ctrl+T, collapsed by default).
• Streaming Responses — Model output streams through the AI SDK, with bot answers rendered as Markdown and tool calls displayed in a compact, Claude-Code-style layout.
• Local Project Tools — readFile, listDirectory, glob, grep, writeFile, editFile, and bash, all sandboxed to the current working directory.
• Context-Usage Meter — A header meter shows how much of the model's context window is in use (raw token count for Ollama/custom models with no fixed window).
• Clarifying Questions — An askUser tool lets the agent ask a focused multiple-choice or free-text question when a wrong assumption would cause real rework, rendered as an inline picker above the input bar.
• Persistent Sessions — Conversations and messages are stored in a local SQLite database; browse and resume past sessions with /sessions.
• Onboarding — First run walks you through picking a provider, entering a key (or Ollama URL), and validating it before saving.
• Themes & Commands — /theme to recolor, plus a / command menu for /new, /agents, /models, /sessions, /config, /theme, and /exit.
• Skills — User-authored markdown skill packs (modeled on Claude Code) that load procedural knowledge on demand. Each skill auto-registers as a /<skill-name> command and is also callable by the model via a skill tool. Install from Git with popeye --add-skill <url> [path] [--force]. See Skills below.

Getting Started

Prerequisites

• Bun installed
• An Anthropic API key, an OpenAI API key, and/or Ollama running locally — at least one provider is required

1. Clone and install

git clone <repo-url> popeye
cd popeye
bun install

2. Run the CLI

bun run dev

On first launch, the onboarding screen guides you through provider setup. You can reconfigure at any time with /config.

To build and link the popeye executable:

bun run link:cli
popeye

Configuration

Everything is stored locally:

• Config: $XDG_CONFIG_HOME/popeye/config.json (or ~/.config/popeye/config.json)
• Sessions: $XDG_DATA_HOME/popeye/ (or ~/.local/share/popeye/)

A minimal config after onboarding looks like:

{
  "providers": {
    "anthropic": { "apiKey": "sk-ant-..." }
  },
  "defaultModel": "claude-opus-4-6"
}

Ollama instead:

{
  "providers": {
    "ollama": { "baseUrl": "http://localhost:11434" }
  },
  "defaultModel": "ollama/llama3.1"
}

Skills

Skills are markdown packs that teach the agent a reusable workflow — a brainstorming checklist, a TDD discipline, a debugging method. A skill is a directory containing a SKILL.md with YAML frontmatter (name, description) and a markdown body of instructions, plus optional supporting files the agent can read on demand.

Two ways to use a skill

• Model-initiated: the system prompt advertises available skills (name + description only). When a request matches, the agent calls the skill tool to load the full body into context.
• User-initiated: every skill auto-registers as a /<skill-name> slash command in the command menu. Typing /<name> tells the agent to load that skill for the current turn.

Where skills live

Scanned at startup from two roots:

• Personal: ~/.config/popeye/skills/<name>/ — shared across all your projects.
• Project: .popeye/skills/<name>/ in the current working directory — committed to the repo and shared with your team.

On a name collision, the project skill wins. Only name + description ever enter the system prompt; skill bodies load on demand via the skill tool.

Installing a skill from Git

popeye --add-skill <git-url> [path] [--force]

Shallow-clones the repo, locates the skill directory (the given path subdirectory, or the repo root if it contains SKILL.md), and copies it into ~/.config/popeye/skills/<name>/. The install name is taken from frontmatter, falling back to the directory basename. Use --force to overwrite an existing skill.

Example — install a single skill from a pack:

popeye --add-skill https://github.com/obra/superpowers.git skills/brainstorming

Project Structure

packages/
├── cli/                         # OpenTUI + React terminal client
│   ├── bin/                     # popeye executable shim
│   └── src/
│       ├── components/          # Terminal UI components, dialogs, messages
│       ├── hooks/               # Chat and context-window hooks
│       ├── layouts/             # Root terminal layouts
│       ├── lib/                 # Config, providers, local tool execution, chat transport
│       ├── providers/           # Dialog, keyboard, prompt, theme, toast providers
│       └── screens/             # Home, new session, onboarding, and session screens
├── database/                    # SQLite client and session storage
└── shared/                      # Shared Zod schemas, AI tool contracts, model registry, system prompt

Scripts

Command	Description
bun run dev	Start the CLI in watch mode
bun run build	Build the CLI package
bun run link:cli	Build and link the popeye executable
bun test	Run the test suite

Packages

Package	Description
@popeye/cli	Terminal UI, local tool execution, and AI streaming
@popeye/database	SQLite client and session storage
@popeye/shared	Shared Zod schemas, AI tool contracts, model registry, and system prompt