Open Source CLI AI Coding Agent • Bun + OpenTUI + SQLite

Popeye: Your AI Coding Agent, Right in the Terminal

Plan, understand, and build software without leaving your terminal. Popeye is a local-first AI coding agent that combines a focused command-line interface with the models you already trust.

$npm install -g popeye-code
A Local-First AI Coding Assistant for Developers

Why Developers Choose Popeye

Popeye brings AI-assisted development into a fast, keyboard-focused terminal workflow. Inspect codebases, plan changes, edit files, and run shell commands under your complete local control.

Stay in Your Development Flow

Work where your code already lives. Popeye provides an interactive terminal interface for planning, coding, reviewing changes, and managing longer tasks without context-switching between browser tabs.

Choose the Right Model

Use Anthropic Claude, OpenAI, Azure OpenAI, or models served locally through Ollama. Switch models mid-work and adjust effort levels matching task complexity.

Keep Control of Project Access

Project tools are restricted to the current working directory. Plan mode focuses on read-only investigation, while Build mode enables file edits and execution when authorized.

Keep Sessions on Your Machine

Configuration and conversation sessions are stored in local SQLite. Return to earlier work anytime without depending on remote server storage or cloud accounts.

Extend the Agent with Skills

Add reusable Markdown-based skills for workflows such as brainstorming, TDD testing, security code reviews, debugging, or team-specific engineering standards. Skills load on demand to preserve context window.

Core Feature Capabilities

Explore Popeye's terminal capabilities built with Bun, OpenTUI, React, and SQLite.

Terminal AI Chat

Use a responsive OpenTUI and React interface built specifically for the command line. Responses stream as they are generated, Markdown remains readable, and tool activity stays visible without overwhelming the conversation.

interfacepopeye CLI

Plan and Build Modes

Use PLAN mode to investigate a project with read-only tools. Switch to BUILD mode when Popeye should write files, apply edits, or execute shell commands. The separation makes the agent's current level of access clear.

controlpopeye CLI

Multiple AI Providers

Configure one or more supported providers and select models from the terminal. Popeye supports Anthropic, OpenAI, Azure OpenAI deployments, and Ollama models discovered from your local instance.

controlpopeye CLI

Adjustable Agent Effort

Choose from Low, Medium, High, X-High, and Max effort levels. Popeye maps the selected level to the capabilities of the active provider while preserving a consistent workflow when you switch models.

controlpopeye CLI

Reasoning and Thinking Views

Use extended thinking with supported Claude models, detailed reasoning summaries with supported OpenAI models, and thinking-capable Ollama models. Reasoning output is collapsible, so you can focus on the final result or inspect more detail when needed.

interfacepopeye CLI

Sandboxed Project Tools

Popeye can read files, list directories, search by file pattern, search source text, write files, apply targeted edits, and run shell commands. Local tools are restricted to the current project directory.

controlpopeye CLI

Persistent Local Sessions

Conversations and messages are stored in a local SQLite database. Browse earlier sessions, reopen a task, and continue with its previous context from the /sessions command.

privacypopeye CLI

Context-Usage Meter

See how much of the active model's context window is in use. For local or custom models without a known fixed context window, Popeye displays the raw token count.

interfacepopeye CLI

Structured Clarifying Questions

When an assumption could lead to unnecessary rework, Popeye can ask a focused multiple-choice or free-text question directly inside the terminal interface.

interfacepopeye CLI

Task Tracking

Break larger requests into visible tasks, track their status, and keep implementation progress connected to the conversation. Task summaries help both the developer and the agent understand what is pending, active, completed, or blocked.

controlpopeye CLI

Themes & Keyboard Navigation

Choose a terminal theme, navigate dialogs from the keyboard, scroll through long conversations, and use a command menu to reach common actions quickly.

interfacepopeye CLI

Reusable Skills

Add reusable Markdown-based skills for workflows such as brainstorming, testing, debugging, documentation, or project-specific engineering practices. Skills load when needed instead of filling every conversation with unnecessary instructions.

extensibilitypopeye CLI
Flexible Model Ecosystem

Supported AI Providers

Connect Anthropic Claude, OpenAI, or Azure OpenAI with your own credentials, or use Ollama to work with local models on your GPU/RAM.

Anthropic Claude

Cloud API Integration

Connect your Anthropic API key and work with supported Claude Opus, Sonnet, and Haiku models. Supported reasoning models can use extended thinking with effort settings adapted to the provider.

Available Models:

claude-3-7-sonnetclaude-3-5-sonnetclaude-3-5-haikuclaude-3-opus
Extended thinking support
Streaming tool execution
Provider-aware reasoning budget
Onboarding Configuration
popeye /config

Run this command in Popeye CLI or during interactive onboarding to configure:

$ popeye /config set anthropic --api-key="sk-ant-..."
Credentials are stored locally in your system configuration directory with strict permissions. Requests go directly to Anthropic Claude.
CLI Cheatsheet

Essential Commands

Keyboard-first interaction through slash commands in the Popeye command menu.

CommandWhat It DoesCopy
/newStart a new conversation session.
/agentsSwitch between Plan and Build modes.
/modelsChoose from configured cloud and local models.
/effortSelect the agent effort level for the current workflow.
/sessionsBrowse and reopen locally stored SQLite sessions.
/configAdd or update provider settings and API credentials.
/themeChange the terminal color theme.
/exitClose Popeye CLI cleanly.
Tip: Installed skills also appear automatically as slash commands (e.g. /brainstorming)
Extensible Agent Workflows

Skills That Match the Way You Work

Popeye skills are reusable Markdown instruction packs. A skill can encode a testing discipline, debugging process, documentation standard, or team engineering guidance.

Personal Skills

Stored in your user directory and available across all your local projects. Perfect for individual productivity tools and custom prompts.

Project Skills

Live in .popeye/skills/ within your repository and committed to Git so the whole team shares identical guidelines.

Featured Pre-Built Skills:

brainstorming.md
Author: Popeye Community
# Brainstorming Skill

When asked to design or solve a complex architectural question:
1. Deconstruct the requirements into core invariants.
2. Outline 2-3 distinct implementation tradeoffs.
3. Present clear pros, cons, and performance implications.
4. Recommend the optimal path before taking implementation action.
Install Skill via CLI
$ popeye --add-skill https://github.com/obra/superpowers.git skills/brainstorming
Clear Answers

Frequently Asked Questions

Everything you need to know about Popeye local AI coding agent architecture, model providers, and privacy.

Popeye is a local-first terminal AI coding agent for software developers. It combines an interactive CLI, project-aware tools, persistent sessions, task tracking, and support for cloud or locally hosted language models.