# Repo Prompt Documentation

Complete documentation for Repo Prompt - AI-powered code context management for macOS.

Website: https://repoprompt.com
Documentation: https://repoprompt.com/docs

---

## Table of Contents

- **Overview**
  - Introduction
- **Getting Started**
  - Installation
  - Interface Overview
  - First Prompt
- **Building Context**
  - Overview
  - File Selection
  - Codemaps
  - Token Management
  - Presets & Prompts
- **Workflows**
  - Context Over Convenience
  - Discovery (Context Builder)
  - Architectural Planning
  - Orchestration
  - Model Recommendations
- **AI Providers**
  - API Providers
  - CLI Providers
  - OpenRouter
  - Custom Providers
- **MCP Server**
  - Overview
  - Setup Guide
  - Tools Reference
  - Transport Modes
  - Settings & Presets
  - Connection Management
- **rp-cli**
  - Command Line Guide
- **Reference**
  - Settings Reference
  - Keyboard Shortcuts

---

# Overview

What Repo Prompt is, key value props, and how it compares to AI editors.

## Introduction

Repo Prompt is an AI-powered context IDE. It gives you precise control over what a model sees — so you get the best responses from the most powerful reasoning models.
**Talk to These Docs**
Open all documentation in an AI assistant for guided help
Open in ChatGPT
Open in Claude
### Why Context Engineering Matters
Agents waste context before they start thinking. Their context windows fill with tool calls, duplicate file reads, and irrelevant code — leaving little room for actual reasoning. Repo Prompt solves this by structuring context upfront: the model reasons about the problem from the first token instead of spending its thinking budget on figuring out what to read next.
**Typical Agent Context**
- ~16% system prompts & tool definitions
- ~38% wasted on duplicate reads & unrelated code
- ~16% relevant code (finally)
- ~14% actual reasoning
- ~16% missing context the agent never found
**Repo Prompt Context**
- File tree for project orientation
- Codemaps for API surface at a glance
- Complete relevant file contents
- Git diffs for change awareness
- Task description — 100% of reasoning spent solving the problem
### Three Ways to Work
[
**Agent Mode**
Hands off context engineering to your coding agents. The same best practices from the old IDE Mode in the Classic Edition — codemaps, slicing, token budgets — managed by agents (Codex, Claude Code, Cursor, Gemini, OpenCode) on your behalf, with built-in workflows.
](/docs#s=agent-mode)
[
**Built-in MCP Server**
Any MCP-compatible tool gets access to Repo Prompt's context tools. Claude Code, Cursor, Codex, Gemini CLI, OpenCode — install with one click.
](/docs#s=mcp-server)
[
**IDE Mode (Classic Edition only)**
Craft precise prompts with full control over file selection, codemaps, and context.
](/docs#s=ide-mode)
### [How Context Builder Works](/docs#s=agent-mode&ss=workflows)
Context Builder is a three-stage pipeline that gives your agents the right context, every time. [Learn more →](/docs#s=agent-mode&ss=workflows)
**1. Explore**
A discovery agent navigates your codebase, reading files and understanding relationships.
**2. Curate**
Relevant files are selected within a token budget, using codemaps and line slices for maximum density.
**3. Handoff**
A structured prompt with curated context is passed to an analysis model for planning, review, or deep Q&A.
### [Built-in Workflows](/docs#s=agent-mode&ss=workflows)
Ready-made context engineering pipelines your agents run directly:
- **Orchestrate** (`/rp-orchestrate`) — Plans, decomposes, dispatches sub-agents across providers
- **Plan & Build** (`/rp-build`) — Discovery → plan → implement in one session
- **Review** (`/rp-review`) — Git diffs + codebase context for grounded code reviews
- **Investigate** (`/rp-investigate`) — Systematic exploration with evidence gathering
- **Refactor** (`/rp-refactor`) — Two-pass: analyze then implement preserving behavior
### [Agent Orchestration](/docs#s=mcp-server)
Repo Prompt is a full control plane for multi-agent workflows via MCP. The `agent_run` tool provides: start, wait/poll (multi-session), steer, respond, cancel. Any MCP-connected agent can orchestrate complex workflows — not just Repo Prompt's built-in agents.
The `/rp-orchestrate` workflow automates this: Context Builder generates a plan → decomposes into tasks → dispatches sub-agents in parallel or sequence → verifies each result. [Learn more →](/docs#s=agent-mode&ss=workflows)
### Why It Matters
**Without Curated Context**
- Misses tradeoffs and edge cases
- Architectural drift from existing patterns
- Duplicates functionality that already exists
- Generic advice disconnected from your codebase
**With Curated Context**
- Considers the full picture before acting
- Follows existing patterns and conventions
- Finds simpler solutions using what's already there
- Grounded feedback tied to real code
### [CLI Providers](/docs#s=ai-providers&ss=cli-providers)
Already paying for Claude Pro/Max, ChatGPT Plus/Pro, or Google AI? Use those same models in Repo Prompt with **CLI Providers** — no additional API costs. These providers power Agent Mode, Chat Mode, and Context Builder workflows. [Learn more →](/docs#s=ai-providers&ss=cli-providers)
### Who Is Repo Prompt For?
- **Developers, researchers, or anyone working with AI on their files** — Repo Prompt gives you precise control over what context AI sees, whether you're writing code, analyzing documents, or exploring data
- **Professionals shipping production-ready code** — Context Builder helps plan architecturally sound changes that fit naturally into existing codebases, so AI suggestions don't fight your patterns
- **Teams that care about code quality** — the `/rp-review` workflow provides world-class AI code reviews powered by Context Builder, grounding feedback in your actual codebase rather than generic advice
### Get Started
Ready to build better AI prompts? Here's where to go next:
- **New to Repo Prompt?** Start with the [Installation guide](/docs#s=overview&ss=installation)
- **Have an AI subscription?** Set up [CLI Providers](/docs#s=ai-providers&ss=cli-providers) to use your existing plan
- **Using Claude Code or Cursor?** Check out [MCP Server Integration](/docs#s=mcp-server)
- **Want an integrated agent experience?** Try [Agent Mode](/docs#s=agent-mode) with Codex, Claude Code, or Gemini CLI
- **Want smarter file selection?** Learn about the [Context Builder](/docs#s=ide-mode&ss=context-builder)
### Learn More
[
Repo Prompt 101
Video walkthroughs of key features and workflows
](https://youtube.com/playlist?list=PLFg9suyZ1OnLh3Tv5bP6jvWXcKKTlI_4m)
[
Rate Limited Podcast
AI coding workflows with Eric, Ray Fernando, Adam Larson
](https://www.youtube.com/@ratelimitedpod)
> **Tip:**
**Quick Win:** Download Repo Prompt, open a project, select a few files, and copy your first prompt. You'll immediately see how much cleaner the context is compared to manual copy-paste.

# Getting Started

Install Repo Prompt and build your first AI prompt in minutes.

## Installation

Repo Prompt is a native macOS application available for
[
download via the Community Edition Repository
](https://github.com/repoprompt/repoprompt-ce/releases)
.
### Onboarding Walkthrough
Ray Fernando put together an excellent end-to-end onboarding video that
walks through Repo Prompt from install through your first orchestrated
workflow. Even though this video was done for the Classic Edition, it
still applies to the Community Edition:
### Manual Download
Get the latest version directly from Repo Prompt CE Repository:
[
Download for macOS
](https://github.com/repoprompt/repoprompt-ce/releases)
### Manual Installation
-
Download the most recent `.dmg` file from the link above
- Open the downloaded file
- Drag the Repo Prompt CE to your Applications folder
- Eject the disk image
- Open Repo Prompt from Applications or Spotlight
### Homebrew Installation
You can install the pre-built Repo Prompt CE macOS binaries via Homebrew
``
### Migrating from the Classic Edition
To move your existing Repo Prompt Classic data into Repo Prompt CE,
install Repo Prompt CE and launch it once so macOS creates the new app
data location. Then the Codex app or Claude Desktop or similar to
migrate the data for you. The apps are recommended, though a CLI
should work too.
You can use a prompt like:
`
Migrate Repo Prompt's Application Data to Repo Prompt CE. Do
not change anything inside Repo Prompt's folders. Migrate everything
to Repo Prompt CE, and do not worry about overwriting data because this is a
fresh install.
`
For MCP installs created with Classic Edition or installed manually,
update the `command` path to:
`~/Library/Application Support/RepoPrompt CE/repoprompt_ce_cli`
### System Requirements
-
**macOS 14.0 (Sonoma)** or later
- Apple Silicon (M1/M2/M3) or Intel Mac
- ~50MB disk space
### First Launch
- Open Repo Prompt from Applications or Spotlight
- Grant folder access when prompted (required to read your code)
-
Open a workspace: **File → Open** or drag a folder onto
the app
> **Tip:**
**Tip:** You can open Repo Prompt from Terminal with
`open -a "Repo Prompt" /path/to/folder` or use the URL scheme
`repoprompt://open?path=/path/to/folder`
### Updates
Repo Prompt checks for updates automatically. When an update is
available, you'll see a notification in the app. You can also manually
check via **Settings → Updates**.
### Platform Availability
Repo Prompt is built natively with Swift and SwiftUI, which means it's
currently macOS-only. Multi-platform support is being worked on by
various community members.

## Interface Overview

Repo Prompt's interface is designed around three main views: Compose, Chat, and Apply. Here's how they work together.
### Main Views
#### Compose View
The primary workspace where you build context and craft prompts.
**Key elements:**
- **File Tree (left):** Browse and select files from your workspace
- **Selected Files Panel:** View and manage your current selection
- **Instructions Area:** Write your prompt/task description
- **Bottom Bar:** Copy presets, token count, Copy and Chat buttons
#### Chat View
Have AI conversations with your code context automatically included.
**Key elements:**
- **Message Thread:** Conversation history with AI responses
- **Input Bar:** Send messages, toggle Pro Edit mode
- **Model Selector:** Choose which AI model to use
- **Chat History Tabs:** Switch between conversation sessions
#### Apply View
Review and apply code changes from AI responses. Paste Pro Edit XML or use the built-in chat to generate changes.
**Key elements:**
- **Paste Area:** Paste AI responses containing code changes
- **Process Button:** Parse XML and send to chat for parallel edits
#### Review View
After processing, review each file's changes before applying.
**Key elements:**
- **File Cards:** Each modified file shown with change preview
- **Diff View:** Line-by-line comparison of changes
- **Apply Controls:** Apply all, apply selected, or reject changes
### Navigation
#### Tab Bar
Switch between views using the tab bar at the top:
- **Compose tabs:** Multiple compose sessions (like browser tabs)
- **Chat:** Access the chat interface
- **Apply:** Review pending changes
#### Toolbar
Quick access to common actions:
- **Settings (gear icon):** Open preferences
- **New Tab:** Create a new compose tab
- **Search:** Find files in your workspace
### Compose View Details
#### File Selection Panel
The left sidebar shows your workspace files:
- **Click** a file to select it (adds to context)
- **Right-click** for options: Full, Slices, Codemap modes
- **Search** to filter files by name
- Files with `+` marker have codemaps available
#### Instructions Area
Where you write your prompt:
- **Prompt dropdown:** Access saved prompts
- **System prompt toggle:** Include/exclude system instructions
- **Edit mode toggle:** Enable Pro Edit XML format
#### Bottom Bar
The control center for your prompt:
- **Copy Preset dropdown:** Choose format (Standard, Pro Edit, Plan, etc.)
- **Token counter:** Shows current context size
- **Copy button:** Copy prompt to clipboard
- **New Chat button:** Send directly to Chat view
> **Tip:**
**Keyboard Shortcuts:** `⌘+C` to copy, `⌘+N` for new chat, `⌘+F` to search files, `⌘+,` for settings.

## First Prompt

Let's build your first AI prompt with rich code context. This takes about 2 minutes.
### Step 1: Open Your Project
- Launch Repo Prompt
- Go to **File → Open** (or `⌘+O`)
- Select your project folder
Your workspace loads with the file tree on the left.
### Step 2: Select Files
Click files in the tree to add them to your context. Selected files appear in the Selected Files panel.
**Tips for good selection:**
- Select files you want the AI to understand or modify
- Include related files (imports, types, tests)
- Watch the token counter - stay within model limits
> **Tip:**
**Start small:** For your first prompt, select 2-3 related files. You can always add more context later.
### Step 3: Write Your Prompt
In the Instructions area, describe what you want:
Be specific about what you want. Good prompts include:
- The task or goal
- Any constraints or requirements
- Expected behavior or output
### Step 4: Copy and Use
#### Option A: Copy to External AI
- Click **Copy** (or `⌘+C`)
- Paste into ChatGPT, Claude.ai, or any AI
- Get your response
- If it contains code changes, paste back into Apply view
#### Option B: Use Built-in Chat
- Click **New AI Chat**
- Select your model and settings
- Send - your context is automatically included
- Review changes in the diff view
### Step 5: Apply Changes
When the AI suggests code changes:
- Review each file's changes in the diff view
- Click **Apply All** or select specific files
- Changes are written to your files
- Use **Undo** if needed
### Watch It In Action
[
Rapid Iteration with Repo Prompt
See the complete prompt-building workflow in action
](https://www.youtube.com/watch?v=LSQBi0Vx3Y4)

# Building Context

Master file selection, codemaps, slices, and token-efficient context building.

## Overview

The key to good AI responses is giving the right context - not too much, not too little. Repo Prompt gives you precise control over what context your AI sees.
[
What is Repo Prompt for?
Overview of context building fundamentals
](https://youtu.be/ncY6cqOCd_Y)
### The Anatomy of a Repo Prompt
Every prompt you create in Repo Prompt is assembled from several components:
- **Your instructions:** What you want the AI to do
- **File tree:** Project structure for navigation context
- **Codemaps:** Structural summaries of your code
- **Selected files:** Full content of files you're working with
- **Slices:** Specific line ranges from large files
[
Try the interactive Prompt Anatomy demo →
](/prompt-anatomy)
### Multi-Root Workspaces
Repo Prompt supports opening multiple root folders in a single workspace. All features work across roots:
- **Cross-project context:** Select files from your codebase and a third-party library to evaluate integration
- **Code + docs:** Work with your code and documentation site together to improve docs
- **Monorepos:** Navigate related packages, shared libraries, and services in one view
- **Context Builder:** Discovers relevant files across all roots automatically
Add roots via **File → Add Folder to Workspace** or drag folders onto the app.
### Context Building Workflow
There are two main approaches to building context:
#### Manual Selection
- Browse the file tree and click files to select them
- Use search to find specific files or content
- Adjust selection modes (Full, Codemap, Slices) per file
- Write your prompt and copy to AI
#### AI-Powered Discovery
- Open Context Builder and describe your task
- Let the AI agent explore and select relevant files
- Review and refine the selection
- Proceed to your chosen workflow
> **Tip:**
**Tip:** For complex tasks, start with Context Builder to discover files, then manually refine the selection before proceeding.

## File Selection

Every file can be included in one of three modes, giving you fine-grained control over token usage.
### Selection Modes
Mode
What's Included
Token Impact
Best For
**Full**
Complete file content
Highest
Files you're actively editing
**Slices**
Specific line ranges
Medium
Large files where only part matters
**Codemap**
Function/type signatures only
Lowest (~10x smaller)
Reference files, APIs, dependencies
### Switching Modes
- **Click** a file to select it (Full mode by default)
- **Right-click** for mode options: show as Full or Codemap ("Show as API only")
- Files marked with `+` in the tree have codemaps available
### Selected Files Panel
The selected files panel shows your current selection with token counts. Use the controls to manage your context:
- **Sort:** Order by Name (A-Z, Z-A) or Tokens (Low-High, High-Low)
- **Gear menu:** View Mode, Collapse All Folders, Clear All Line Slices, Clear File Selection
- **Per-file actions:** Right-click to switch modes or clear slices on individual files
### Using Slices
Slices let you include only specific line ranges from a file. Slices are created through MCP-connected agents:
- **Context Builder:** Automatically creates slices when curating context—it reads files and extracts only the relevant sections to fit your token budget
- **MCP Agents:** Any agent connected via MCP can use the `manage_selection` tool to create slices with specific line ranges and descriptions
When a file has slices, you'll see the line range (e.g., "L1-107") and a scissors icon. You can clear slices via right-click or the gear menu's "Clear All Line Slices" option.
> **Tip:**
**Slice Power:** Context Builder can turn a 2000-line file into a 50-line slice containing just the relevant function—massive token savings while preserving the context AI needs.
### File Tree Options
The file tree helps AI understand your project structure and navigate relationships between files.
Option
What It Shows
Tokens
**Auto**
Balanced tree, trimmed if needed
Low-Medium
**Full**
Complete directory structure
Higher
**Selected**
Only selected files and parents
Lowest
**None**
No file tree
Zero
Files with available codemaps show a `+` marker in the tree. This helps AI know which files have structural information available.
### File Filtering
Repo Prompt respects your `.gitignore` files automatically. If files are missing from the tree, they may be filtered out. Access filter settings via the filter icon in the file tree toolbar.
**Filter options:**
- **Local ignore file:** Create workspace-specific ignore patterns via the UI
- **Global ignores:** Set patterns that apply to all workspaces
- **Negative patterns:** Use `!` prefix to counter gitignore patterns you need to override (e.g., `!dist/important.js`)
> **Tip:**
**Tip:** If a file you need isn't showing up, check your gitignore patterns and use negative patterns to override them.
### Git Integration
Include diffs of changed files in your prompt. Access git controls via the "Git" button in the bottom bar.
**Git controls:**
- **Compare with:** Select which branch or tag to diff against (HEAD, main, etc.)
- **Include diff in prompt:** None, Selected files only, or All changed files
- **Pending changes:** View all modified files with line counts (+/-)
- **Select files:** Check files to include their diffs in context
Both Compose and Chat have separate git settings. The **Review** and **Diff Follow-up** presets auto-configure this to include diffs for selected files.
> **Tip:**
**Tip:** Use git diffs to give AI context about recent changes when debugging issues or continuing work on a feature.

## Codemaps

Codemaps extract the "shape" of your code - function signatures, class definitions, type declarations - without implementation details. This gives AI structural understanding at 10x fewer tokens.
### What Codemaps Include
- Function and method signatures (names, parameters, return types)
- Class and struct definitions
- Type aliases and interfaces
- Protocol/interface declarations
- Important constants and enums
### Supported Languages
Codemaps are powered by tree-sitter and support:
Swift, JavaScript, TypeScript, Python, C, C++, C#, Rust, Go, Java, Dart, PHP
### Codemap Modes
Mode
Behavior
When to Use
**None**
No codemaps included
When you don't need structural context
**Auto** (Default)
Intelligently selects relevant definitions
Most use cases - balanced and smart
**Complete**
All definitions from scanned files
Architectural understanding, full API overview
### Auto-Codemap Management
When you select files in Full or Slices mode, Repo Prompt automatically adds codemaps for related files:
- Dependencies and imports get codemap context
- Related types and protocols are included
- You get structural context without manually selecting every file
Manual codemap operations (promote/demote) disable auto-management for that session.
### Using Codemaps Effectively
#### For Reference Files
When you need to reference APIs or types but don't need to edit the file:
- Right-click the file in the tree
- Select "Show as API only"
- The file is included as a codemap (10x fewer tokens)
#### For Architecture Questions
To understand your codebase structure:
- Set Codemap mode to "Complete" in settings
- Don't select any files in Full mode
- Get a bird's-eye view of your entire codebase at minimal token cost
> **Tip:**
**Architecture Tip:** For architectural questions, try Complete codemaps with no full files selected. This gives AI a bird's-eye view of your entire codebase structure at minimal token cost.
### Codemap Availability
Files with available codemaps show a `+` marker in the file tree. If a file doesn't have this marker:
- The language may not be supported
- The file may be too small to benefit from a codemap
- The file type (config files, JSON, etc.) doesn't have structural definitions

## Token Management

The token counter shows your current context size. Understanding token limits helps you build effective prompts without hitting model limits.
### Example Model Context Windows
Model
Context Window
Notes
GPT-5.4
272K–1M tokens
Codex standard: 272K. API: 1M+. ChatGPT: 30k (Plus) / 60k (Pro). GPT-5.5 is Codex CLI-only (Medium/High) or ChatGPT Pro web (Pro) — do not treat it as an API or OpenRouter context-window entry.
Claude 4.5
200K tokens
Claude Code & Desktop. 1M via API at higher rates
Gemini 3.0 Preview
200K tokens
Standard pricing. 1M+ at higher pricing tiers
> **Tip:**
**Effective vs Advertised:** Models have an advertised context window and an effective one. Most models perform well in the 64-128k token range, but going beyond that can degrade reasoning ability.
### Token Reduction Strategies
If you're hitting token limits:
#### 1. Use Codemaps
Switch reference files from Full to Codemap mode. You get the API surface without implementation details—typically 10x fewer tokens.
#### 2. Use Slices
Let Context Builder create slices, or have MCP agents specify line ranges. Include only the relevant sections of large files.
#### 3. Be Selective
Remove files that aren't essential for the task. Ask yourself: "Does the AI need to see this file to answer my question?"
#### 4. Simplify the Tree
Use "Selected" tree mode instead of "Full". The AI doesn't always need to see your entire directory structure.
#### 5. Consider Model Choice
For massive contexts, Gemini's 1M+ token window or Claude's 1M API tier can help when you truly need everything.
### Reading the Token Counter
The token counter in Repo Prompt shows:
- **Total tokens:** Your complete prompt size
- **Breakdown:** Hover to see files, codemaps, tree, and prompt contributions
- **Per-file tokens:** Shown in the selected files panel
### Budgeting for Responses
Remember that the context window includes both your prompt *and* the model's response. Leave room:
- **Planning tasks:** Leave 10-20k tokens for detailed plans
- **Code generation:** Leave tokens proportional to expected output
- **Conversations:** Budget for multiple turns

## Presets & Prompts

Presets save and restore your complete context configuration - file selection, prompt, and app settings - in one click.
### Copy Presets vs Chat Presets
Both copy and chat have their own preset dropdowns. Presets customize the system prompt, file tree inclusion, git diffs, and codemap settings.
Copy Presets
Chat Presets
### Manual Controls
Select "Manual" from either preset dropdown to configure each setting individually:
### What Presets Configure
- **System prompt:** Instructions that guide AI behavior
- **File tree:** Include project structure (Auto, Full, Selected, None)
- **Git diffs:** Include uncommitted changes
- **Codemaps:** Include API signatures for unselected files
### Built-in Presets
Preset
Purpose
**Standard**
Clean formatting for any AI (ChatGPT, Claude, etc.)
**XML Edit**
XML format for structured changes - paste response back to apply
**Plan**
Optimized for architectural planning and design discussions
**Diff Follow-up**
Include diffs of changed files for review in ongoing chats
### MCP Copy Presets
When handing off to external agents (Claude Code, Codex), MCP presets prepare the agent:
Preset
Purpose
**MCP Pair**
Pair programming workflow—agent drives, chat implements
**MCP Discover**
Same as Context Builder—agent explores and curates context
**MCP Agent**
Primes agent on MCP tooling for autonomous work
### Creating Custom Presets
- Configure your selection, prompt, and settings
- Click the preset dropdown → "Save as Preset"
- Name your preset descriptively
- Access it anytime from the preset menu
### Preset Use Cases
- **Feature work:** Preset with relevant files for a specific feature
- **Code review:** Preset with review-focused prompt and diff settings
- **Debugging:** Preset with error handling code and logging utilities
- **Documentation:** Preset with doc-writing prompt and public APIs
### Stored Prompts
Stored prompts are reusable instruction snippets that power both presets and custom workflows. Access via the "Prompts" button in the bottom bar.
#### Built-in Prompt Categories
- **Architect/Engineer/Review:** Role-based prompts used by the Plan preset for architectural discussions
- **MCP Behavior Prompts:** Prime external agents for MCP Discover, Pair, and Agent workflows
- **XML Edit Prompts:** Control response format—Diff (minimal changes), Whole (full file), Pro (parallel edits). Used by Edit and Pro Edit modes in chat
#### Custom Prompts
Create your own stored prompts for frequently-used instructions:
- Click "New" in the stored prompts panel
- Write your instruction text
- Name it descriptively (e.g., "Code Review Guidelines")
- Click + to insert into your current prompt
> **Tip:**
**Tip:** Combine multiple stored prompts by clicking + on each one. Use stored prompts for reusable instructions and presets for complete workflow configurations.

# Workflows

Discovery, planning, and implementation workflows for different task complexities.

## Context Over Convenience

{Array.from().map((_, r) =>
Array.from().map((_, c) => {
const active = highlighted.has(`$-$`);
return ;
})
)}
);
};
{Array.from().map((_, r) =>
Array.from().map((_, c) => )
)}
9 / 54
);
};
const HandoffCard = () => (
Curated Context
{['auth.ts  L5-89','api.ts  L22-58','useAuth.ts  L1-41','Header.tsx  L12-67'].map(f => (
))}
);
const Arrow = () => (
);
Repo Prompt's workflows are built on one principle: **give the model the right context before it acts**. Context Builder handles the discovery, powerful analysis models plan and review, and agents implement through orchestration.
### How Context Builder Works
Every workflow starts with Context Builder, a two-stage pipeline that separates discovery from reasoning:
01 Explore
Agent navigates codebase
02 Curate
Select within token budget
03 Handoff
Structured prompt for analysis
### Built-in Workflows
Each workflow is a slash command you can run from Agent Mode or any MCP client:
Command
What It Does
Best For
`/rp-orchestrate`
Plans (or accepts a plan), decomposes into tasks, dispatches sub-agents across providers
Any complex work. Replaces /rp-build with better results
`/rp-build`
Context Builder gathers files, analysis model creates plan, then implement in one session
Faster alternative when you don’t need sub-agent delegation
`/rp-review`
Publishes git diffs alongside codebase context for grounded reviews
Code reviews, PR review
`/rp-refactor`
Two-pass: analyze for opportunities, then plan preserving behavior
Refactoring, cleanup
`/rp-investigate`
Systematic exploration with evidence gathering
Bugs, root cause analysis
### Orchestration: Multi-Agent Workflows
The `/rp-orchestrate` workflow goes beyond single-agent execution. Give it a pre-existing plan, or let it generate one on the fly with Context Builder. It freely delegates tasks to sub-agents across providers like Codex, OpenCode, and Gemini, supervising their work and steering as needed.
- **Flexible planning:** Works with a plan you provide, or uses Context Builder to generate one automatically
- **Autonomous delegation:** The orchestrator decides when to run tasks in parallel or sequence based on dependencies
- **Multi-provider:** Sub-agents can use any available provider. Pick the right model for each task
- **Verification:** The orchestrator checks each result against the plan before continuing
Personal agents like **OpenClaw** can launch orchestration workflows via the CLI, completing complex engineering work asynchronously while you're away.
### ChatGPT Pro Planning
For the highest-quality architectural plans, Repo Prompt has a native **ChatGPT Export** workflow. Describe what you need, and Repo Prompt assembles the curated context into a prompt ready to paste into ChatGPT Pro for GPT-5.5 Pro's extended reasoning:
GPT-5.5 Pro is a ChatGPT Pro (web) model. For in-app implementation and review, use Codex CLI with GPT-5.5 Medium/High — that's the recommended in-app agent path, not a ChatGPT Export target.
- Click **ChatGPT Export** in Agent Mode
- Describe your task
- Copy the assembled prompt and paste into ChatGPT Pro
- Hand the resulting plan to your coding agent for implementation
> **Tip:**
**When to export:** Use ChatGPT Pro planning for high-stakes architectural decisions. For routine tasks, the built-in workflows handle planning automatically.
### Why Context Over Convenience?
Coding agents are convenient but fundamentally limited. When they search and code simultaneously, context fills with noise before they understand the problem:
- Tool calls, grep results, and backtracking exhaust the context window
- By the time the agent understands your code, its effective reasoning is degraded
- Solutions miss architectural patterns and duplicate existing functionality
Context Builder solves this by separating discovery from reasoning. The analysis model receives clean, curated context and spends its entire thinking budget on the solution, not on figuring out which files to read.
Read the full philosophy: [Context Over Convenience](https://repoprompt.com/blog/context-over-convenience)
### Choosing a Workflow
Situation
Recommended
Small feature, quick fix
Just ask the agent directly, no workflow needed
Any complex work
`/rp-orchestrate`: plans and delegates, works at any scale
Complex work, want speed over thoroughness
`/rp-build`: same pipeline, single session, faster
High-stakes architecture
ChatGPT Export: GPT-5.5 Pro extended reasoning
Review a PR or recent changes
`/rp-review`
Clean up or restructure code
`/rp-refactor`
Bug or mysterious behavior
`/rp-investigate`
Autonomous, overnight work
OpenClaw + `/rp-orchestrate` via CLI
### Your Role as Engineer
- **Scope correctly:** Break large tasks into manageable pieces
- **Guide discovery:** Mention key files or areas in your task description
- **Review changes:** Validate implementation matches the plan
- **Iterate:** Use review workflows to catch issues early

## Discovery (Context Builder)

The Context Builder is an AI agent that researches your codebase and selects relevant files for your task. It's the foundation of every Repo Prompt workflow.
[
Context Builder 2.0
AI-powered context selection with CLI Providers
](https://youtu.be/qHl116OG2DM)
### How Context Builder Works
- **Task analysis:** You describe what you're trying to accomplish
- **Codebase exploration:** The agent uses MCP tools to search and read your code
- **File selection:** Relevant files and codemaps are identified
- **Token optimization:** Selection is refined to fit your token budget
- **Handoff prompt:** A non-opinionated summary is generated
### The Handoff Prompt
The Context Builder produces a "handoff prompt" that contains:
- **Clarified instructions:** Your task, refined with specifics
- **Open questions:** Ambiguities you may want to address
- **File relationships:** How discovered files relate to each other
- **Selected context:** Files, slices, and codemaps
> **Tip:**
**Non-Opinionated Discovery:** The Context Builder is explicitly instructed to gather facts, not propose solutions. This prevents bias in the handoff prompt and ensures the implementing model gets complete, unbiased context.
### Token Budget
The Context Builder targets a specific token budget to ensure your prompt fits the effective context window of your target model:
Target
Budget
Use Case
ChatGPT Pro
60k tokens (default)
Pasting into ChatGPT web (Pro plan)
ChatGPT Plus
30k tokens
Pasting into ChatGPT web (Plus plan)
API / Codex CLI
128-200k tokens
Direct API, Codex CLI, Claude Code
Coding agents
24-32k tokens
Kickstarting agent sessions with context
### File Slicing
One of Context Builder's most powerful tools is file slicing. Instead of including entire files, it can extract only the relevant sections:
- Massive files become manageable
- Irrelevant code is excluded
- Token budget is used efficiently
- Slices include line numbers for easy reference
### CLI Provider Integration
Context Builder works best when connected to a CLI provider:
Provider
Model Used
Subscription
Claude Code
Claude Sonnet 4.5
Claude Pro/Max
Codex CLI
GPT-5.5 Low for discovery/explore; GPT-5.5 Medium for engineer/default implementation; GPT-5.5 High for heavier review/planning after discovery
OpenAI Plus/Pro
Gemini CLI
Gemini 2.5
Google AI
Cursor CLI
Discovers models dynamically from your Cursor installation
Cursor Pro/Business
OpenCode
Multiple providers including some free models
Various subscriptions
For Codex users, our current default is GPT-5.5 Low for discovery and Context Builder. It is the practical Codex CLI default for repeated exploration; use GPT-5.5 Medium for engineer/default implementation, and switch to GPT-5.5 High for heavier planning, review, or pair sessions after discovery.
### Running Context Builder
- Open your workspace in Repo Prompt
- Click **Context Builder** in the toolbar
- Describe your task clearly and specifically
- Wait for the agent to explore and select files
- Review the selection and handoff prompt
- Proceed to your chosen implementation path
### Tips for Better Results
- **Describe what you need, not where to look:** The builder explores autonomously. "Add JWT authentication to the API" works better than listing specific files
- **Mention what you know:** If you know key areas, modules, or patterns, include them — the builder uses these as starting hints but explores beyond them
- **Don't over-constrain:** Being too prescriptive narrows discovery. Let the builder find related code you might not know about
- **Review open questions:** The handoff prompt flags ambiguities — address them before handing off to implementation
- **Adjust token budget for your target:** Lower for agent handoffs (24-32k), higher for API/CLI usage (128-200k)

## Architectural Planning

For high-stakes architectural decisions, you can break out the planning step and use ChatGPT Pro's extended reasoning for the deepest analysis. This is the manual version of what `/rp-build` automates — useful when you want hands-on control over the planning phase or access to GPT-5.5 Pro's thinking time.
> **Tip:**
**Where each model lives:** GPT-5.5 Pro is a ChatGPT Pro (web) model used for this architectural planning flow. GPT-5.5 Low for implementation and GPT-5.5 High for in-app review are available only through Codex CLI. Neither is available as an OpenAI API or OpenRouter model.
> **Tip:**
**For most tasks:** The `/rp-build` and `/rp-orchestrate` workflows automate this entire pipeline. Use this manual approach when you want GPT-5.5 Pro's extended reasoning for particularly complex architectural decisions, or when you need human review of the plan before implementation.
[
Fitting Repo Prompt into Agent Workflows
Context Builder → Plan → Implementation → Review
](https://youtu.be/060MqOx-Ex0)
### Why Architectural Planning?
Coding agents — including `/rp-build` — use context-first planning to produce better results. But for the most consequential decisions, you may want to run the planning step yourself with a dedicated reasoning model:
- GPT-5.5 Pro's extended thinking time can surface insights that faster models miss
- You can review and refine the plan interactively before any code is written
- The planning conversation becomes a persistent reference you can return to
- Complex trade-offs benefit from a human-in-the-loop at the planning stage
The core principle — whether automated or manual — is the same:
- Context Builder gathers all relevant files first (discovery phase)
- The planning model receives complete context upfront
- It can reason about the entire affected codebase at once
- Plans are thorough and architecturally sound
### The Workflow
- **Run Context Builder** with your task description
- **Review the selection:** Ensure all relevant files are included
- **Switch to Plan preset:** Select the "Plan" copy preset
- **Copy and paste to GPT-5.5 Pro:** Use ChatGPT's Pro plan for best results
- **Get your architectural plan:** GPT-5.5 Pro excels at breaking down architectures
- **Refine if needed:** Ask follow-up questions in the same chat
- **Implement:** Hand the plan to any Agent Mode provider (Claude Code, Codex CLI with GPT-5.5 Medium/High, Cursor, etc.), or run `/rp-build` with the plan as input
### Why GPT-5.5 Pro?
GPT-5.5 Pro has exceptional abilities for architectural planning:
- **Extended reasoning:** Can think for many minutes on complex problems
- **Thorough analysis:** Considers edge cases and implications
- **Large context:** Can process your entire relevant codebase
- **Clear structure:** Produces well-organized, actionable plans
> **Tip:**
**Token Budget:** The default 60k token budget is calibrated for GPT-5.5 Pro on ChatGPT's Pro plan. This is the upper limit before hitting errors when pasting into the web interface.
### What Good Plans Include
An effective architectural plan should cover:
#### 1. Clear Outcome Specification
- What the final product should do after changes
- Success criteria and expected behavior
- Edge cases to handle
#### 2. Architectural Specification
- How new code should be structured
- Which parts of the codebase are affected
- What each component should do exactly
- Dependencies and relationships
#### 3. Implementation Steps
- Ordered list of changes to make
- Clear, verifiable sub-tasks
- Dependencies between steps
### Why PRDs Aren't Enough
Many plan modes focus on PRDs (Product Requirements Documents). The problem:
- PRDs describe *what* but not *how*
- Implementation details are left to the implementing model
- Agent orientation problems return during implementation
- No guidance on code structure or file organization
Architectural plans solve this by specifying implementation details upfront, so the implementing model encounters minimal ambiguity.
### From Plan to Implementation
Once you have your architectural plan, hand it off for implementation:
- **/rp-orchestrate:** Takes the plan and delegates sub-tasks across multiple agents automatically
- **/rp-build:** Feed the plan as input for a single-agent automated build
- **Claude Code:** Paste the plan and let it implement step by step
- **Codex CLI:** Feed the plan as context for implementation
- **Cursor / Cursor CLI:** Use the plan to guide agentic edits
- **Repo Prompt Chat:** Use XML Pro Edit mode for direct implementation
The plan provides the architectural guidance that keeps implementation on track. Instead of discovering your codebase from scratch, the agent receives a complete implementation roadmap.
### Review the Implementation
After the agent implements your plan, review the changes with one of these approaches:
#### Option 1: Automated Review with /rp-review
Run `/rp-review` to automatically review the implementation against your plan. Since Context Builder already selected the relevant files, the review has all the context needed for a thorough analysis.
- Verifies the implementation matches the plan
- Checks for edge cases or missing error handling
- Suggests tests or improvements
#### Option 2: GPT-5.5 Pro Review (Recommended for ChatGPT users)
If you used ChatGPT for planning, use the **Diff Follow-up** copy preset to request a review:
- The preset includes your prompt plus diffs of all changed files
- GPT-5.5 Pro sees exactly what the agent did in response to the plan it proposed
- Efficiently conveys changes without resending the entire codebase
- The planning model can validate implementation against its own architectural recommendations
> **Tip:**
**Why Review Matters:** The planning model has deep context about your architecture. Having it review the implementation catches misunderstandings and ensures the changes align with the intended design.
### When to Use Architectural Planning
- **New features:** Significant additions to the codebase
- **Major refactors:** Restructuring existing code
- **System redesign:** Changing how components interact
- **Complex bugs:** Issues requiring architectural understanding
- **Performance optimization:** Changes affecting multiple systems
### Example Use Cases
- "Add a caching layer to our API endpoints"
- "Refactor the authentication system to support OAuth"
- "Implement real-time notifications across the app"
- "Migrate from REST to GraphQL"
- "Add comprehensive error handling throughout the codebase"
> **Tip:**
**Pro Tip:** After getting your plan from GPT-5.5 Pro, review it carefully. If something seems off, ask follow-up questions in the same chat. The model has full context and can refine its recommendations.

## Orchestration

Repo Prompt is a **multi-agent control plane**. Any MCP-connected agent — Claude Code, Cursor, Codex, Gemini CLI, OpenCode, or custom scripts — can orchestrate complex multi-agent workflows through Repo Prompt's `agent_run` and `agent_manage` tools.
### Agent Run Control
The `agent_run` MCP tool is the core primitive for orchestration. It provides five operations:
Operation
Description
`start`
Launch an agent session with a task and optional provider/model
`wait / poll`
Block or poll on one or many sessions — multi-session wait returns when the first of N parallel agents finishes
`steer`
Redirect a running agent mid-flight with new instructions
`respond`
Answer agent interactions and permission requests
`cancel`
Stop any session cleanly
### Orchestration Layer
On top of `agent_run`, Repo Prompt provides infrastructure for coordinating multi-agent work:
- **Multi-session wait** — Pass a `session_ids` array to `wait` and block until the first of N parallel agents finishes, enabling fan-out/fan-in patterns
- **Session management** — Create, resume, and stop durable sessions via `agent_manage`
- **Workflow engine** — Reusable multi-step orchestration templates (e.g. the `/rp-orchestrate` workflow)
- **MCP-native** — Any AI tool that speaks MCP can orchestrate. Not just Repo Prompt agents — any MCP client can drive this
### How /rp-orchestrate Works
The built-in orchestration workflow automates the full lifecycle:
- **Scan:** Context Builder gathers relevant files and generates (or accepts) a plan
- **Decompose:** The plan is broken into discrete work items with dependency information
- **Dispatch:** Sub-agents are launched across providers — the orchestrator decides whether to run tasks in parallel or sequence based on dependencies
- **Scope:** Each sub-agent gets scoped file boundaries from the shared plan
- **Monitor:** The orchestrator steers between tasks and verifies each result against the plan
- **Multi-provider:** Sub-agents can use any available provider — Codex, Claude, Cursor, Gemini, OpenCode
### Example: Parallel Agent Dispatch
Launch multiple agents and wait for the first to complete:
> **Tip:**
**Fan-out/fan-in:** The multi-session `wait` returns as soon as *any* of the listed sessions completes. This lets an orchestrator react immediately — process the result, launch follow-up work, or steer the remaining agents — without polling.
### Who Can Orchestrate
- Any **Agent Mode** session running `/rp-orchestrate`
- Any MCP client calling `agent_run` and `agent_manage` tools directly
- CLI scripts using `rp-cli`
- Custom automation via the standard MCP protocol
### When to Use Orchestration
- Complex multi-part tasks that benefit from parallel execution
- Work that spans different concerns — backend, frontend, and tests can each get a dedicated agent
- When you want different models for different sub-tasks (e.g. Codex for fast edits, Claude for architectural reasoning)
- Overnight or autonomous work pipelines where the orchestrator monitors progress without human intervention
> **Tip:**
**Getting started:** Run `/rp-orchestrate` in any Agent Mode session and describe your task. The workflow handles plan generation, decomposition, dispatch, and verification automatically.

## Model Recommendations

const screenshotStyle = ;
After extensive testing across workflows, here are the current go-to models for each use case as of May 2026. Repo Prompt includes an automatic model recommendation system that suggests optimal models based on your current workflow.
> **Tip:**
**GPT-5.5 Update:** GPT-5.5 Low is our default for Explore and Context Builder/discovery via Codex CLI. GPT-5.5 Medium is now the default for Engineer/everyday implementation, while GPT-5.5 High remains the in-app choice for heavier planning, review, and pair sessions. Use GPT-5.5 Pro for ChatGPT Pro planning and exports. GPT-5.5 is not available as an OpenAI API or OpenRouter model.
### Best Models by Use Case
Use Case
Model
Access
**Best Agent**
GPT-5.5 Medium
Codex CLI
**Best Planning Model**
GPT-5.5 Pro
ChatGPT Pro (web only)
**Best In-App Planning/Review**
GPT-5.5 High
Codex CLI
**Best Context Builder**
GPT-5.5 Low
Codex CLI
### Why These Models?
#### GPT-5.5 Low for Explore, Medium for Implementation
GPT-5.5 Low (available through Codex CLI) remains our top recommendation for explore and discovery work. GPT-5.5 Medium is the default for engineer agents and general implementation:
- Low keeps repeated codebase exploration and context building fast and efficient
- Medium adds reasoning headroom for everyday multi-step implementation
- Both remain more conversational and easier to steer than prior generations
- Use Medium as the default for most engineer implementation work
Claude Opus 4.6 is still useful as an optional secondary tool for editing-heavy tasks, but it is no longer something we think you need to keep on a separate $100 Max plan.
> **Tip:**
**Codex-only:** GPT-5.5 is currently accessible only through Codex CLI. Do not try to configure it as an OpenAI API or OpenRouter model — those endpoints still serve the GPT-5.4 family.
#### GPT-5.5 Pro for Architectural Planning
GPT-5.5 Pro on ChatGPT Pro is our top planning recommendation because:
- Extended reasoning time produces thorough architectural analysis
- It handles large codebase planning extremely well
- It produces clearer architectural specs and follow-up plans
- It remains the best fit for high-value planning sessions
GPT-5.5 Pro is available only through the ChatGPT Pro web interface — use Repo Prompt's **ChatGPT Export** copy preset to hand it a curated prompt. It is not a Codex CLI or OpenAI API model.
#### GPT-5.5 High for In-App Planning/Review
For in-app Chat planning and code review, we recommend Codex CLI with GPT-5.5 High:
- Strong reasoning without the wait times of ChatGPT Pro sessions
- Won't exhaust usage limits as quickly as Pro-style planning sessions
- XHigh is available for the hardest in-app problems
- High is the practical default for most Repo Prompt in-app sessions
#### GPT-5.5 Low for Context Building
We recommend GPT-5.5 Low as the Context Builder and discovery default. It is the practical Codex CLI default for repeated exploration, file selection, and handoff preparation.
The Context Builder agent benefits from:
- Strong codebase understanding
- Efficient file exploration and selection
- Uses usage limits more slowly than GPT-5.5 Medium/High while staying on the current GPT-5.5 family
- Stays practical for repeated discovery runs while matching the current default recommendation
### Recommended Subscriptions
#### Core Setup (Recommended)
**ChatGPT Pro**
$200/month
Codex CLI (GPT-5.5 Low for explore/discovery, GPT-5.5 Medium for engineer implementation, GPT-5.5 High for heavier work) + GPT-5.5 Pro for planning
This setup gives you:
- Best-in-class explore/discovery with GPT-5.5 Low and engineer implementation with GPT-5.5 Medium via Codex CLI
- Best-in-class in-app planning/review with GPT-5.5 High via Codex CLI
- Best-in-class architectural planning with GPT-5.5 Pro on ChatGPT Pro web
- No need to add a separate premium Claude plan just to round out the workflow
#### Optional Claude Add-On
**Claude Pro**
$20/month
Claude Code for light UI work, polish, and fast fixes when you want it
If you still like Claude's editing style, we now recommend keeping it lightweight: Claude Pro is enough for light UI work and quick fixes. Upgrade beyond that only if Claude Code is a daily driver for you.
#### Budget Setup (Great Results)
**ChatGPT Plus**
$20/month
Codex CLI + GPT-5.5 Low / GPT-5.5 Medium / GPT-5.5 High
**Total**
**$20/month**
Context Builder + solid in-app chat
This gives you:
- Context Builder/explore with GPT-5.5 Low and default implementation with GPT-5.5 Medium
- Strong in-app planning and review with GPT-5.5 High via Codex CLI for heavier sessions
- Excellent results for most tasks without stacking subscriptions
That split is intentional: use GPT-5.5 Low for repeated context-building and explore work, GPT-5.5 Medium for engineer/default implementation, and save GPT-5.5 High for heavier planning/review or pair-agent sessions.
> **Tip:**
**Keep Evolving:** Model recommendations change as new releases come out. Check back regularly or follow @repoprompt on X for the latest recommendations.

# AI Providers

Configure API keys, CLI providers, OpenRouter, and custom endpoints.

## API Providers

Connect directly to AI providers using API keys. This gives you full control over model selection and usage.
> **Tip:**
**IDE Mode only (Classic Edition):** API key providers power Chat, Context Builder, Oracle, and Pro Edit. Agent Mode requires a CLI harness — Repo Prompt supports [six compatible CLIs](#s=agent-mode&ss=providers) including Codex, Claude Code, Gemini, OpenCode, and Cursor.
> **Tip:**
**GPT-5.5 is not an API model:** GPT-5.5 Low/Medium/High are available only through Codex CLI, and GPT-5.5 Pro is ChatGPT Pro web only. The OpenAI API and Azure OpenAI continue to serve the GPT-5.4 family. Use Codex CLI (under [Agent Providers](#s=agent-mode&ss=providers)) to access GPT-5.5.
### Supported Providers
Repo Prompt supports direct API connections to these providers:
Provider
Models
Context
**Anthropic**
Claude Opus 4.6, Sonnet 4.5, Haiku 4.5
200K
**OpenAI**
GPT-5.4 family
1M+
**Google**
Gemini 2.5 Pro, Gemini 2.5 Flash
1M+
**DeepSeek**
DeepSeek V3, DeepSeek R1
128K
**xAI**
Grok 4
128K
**Groq**
Llama, Mixtral (fast inference)
Varies
**Fireworks AI**
Qwen3, Kimi K2, DeepSeek
Up to 32K
**Z.AI**
GLM 4.6, GLM 4.7, GLM 5
200K
**Azure OpenAI**
Your Azure deployments
Varies
### Adding API Keys
- Open **Settings** (`⌘+,`)
- Go to **API Settings → API Providers**
- Find your provider and enter your API key
- Click **Validate & Save**
- A green checkmark confirms the key is valid
### Getting API Keys
#### Anthropic (Claude)
- Go to [console.anthropic.com](https://console.anthropic.com/settings/keys)
- Create an account or sign in
- Navigate to Settings → API Keys
- Create a new key and copy it
#### OpenAI (GPT)
- Go to [platform.openai.com](https://platform.openai.com/api-keys)
- Create an account or sign in
- Navigate to API Keys
- Create a new secret key and copy it
#### Google (Gemini)
- Go to [aistudio.google.com](https://aistudio.google.com)
- Sign in with your Google account
- Get your API key from the console
### Key Security
Your API keys are stored securely in the macOS Keychain - they never leave your machine and are encrypted at rest.
### Custom Models
For providers that support it, you can add custom model names:
- After validating your API key, look for the "Custom Model" field
- Enter the model identifier (e.g., `claude-3-5-sonnet-latest`)
- Click "Save Model"
- The model appears in your model selection dropdown
For OpenAI custom models using the Responses API, you can also configure reasoning effort levels (low, medium, high)
to control how much thinking the model does before responding.
### GitHub Models (Free)
GitHub provides free access to select models with an 8K context limit:
- Go to Settings → API Providers
- Click "Sign in with GitHub"
- Authorize Repo Prompt
- GitHub models appear in your model list
> **Tip:**
**Note:** GitHub models are limited to 8K tokens context, which may be too small for many coding tasks. Consider using other providers for larger contexts.
### Local Models (Ollama)
Run models locally with Ollama:
- Install Ollama from [ollama.com](https://ollama.com)
- Pull a model: `ollama pull llama3.1`
- In Settings → API Providers, find "Local Model Settings"
- The default URL is `http://localhost:11434`
- Click "Validate" to fetch available models
- Select your model from the dropdown

## CLI Providers

> **Tip:**
**Use Your Existing Subscriptions:** CLI Providers let you use models through your Claude Pro/Max, OpenAI Plus/Pro, Cursor Pro/Business, or Google AI subscriptions instead of paying per-token API costs.
CLI Providers are one of Repo Prompt's most powerful features. If you already pay for Claude Pro/Max, ChatGPT Plus/Pro, Cursor Pro/Business, or a Google AI subscription, you can use those same models in Repo Prompt without additional API costs.
### Why Use CLI Providers?
- **Save Money:** Use your existing subscription instead of paying per-token API fees
- **Latest Models:** Access the newest models through official CLI tools
- **No API Keys:** Authentication is handled by the CLI's existing login
- **Full Features:** Works with Chat, Context Builder, and Pro Edit workflows
### Available CLI Providers
#### Claude Code (Claude Pro/Max)
Use Claude models through your Claude Pro or Max subscription. For many teams, Claude Pro is enough for light UI work and quick fixes.
- Install Claude Code: `npm install -g @anthropic-ai/claude-code`
- Login: `claude login`
- In Repo Prompt, go to Settings → CLI Providers
- Click "Connect" next to Claude Code
- Test the connection to verify it works
**Claude Code-compatible backends:** The same Claude Code integration also powers
** CC Zai** (GLM via a Z.AI API key), **CC Moonshot** (Kimi via a Moonshot API key,
endpoint prefilled to `https://api.kimi.com/coding/`), and **CC Custom** (any
Claude Code-compatible endpoint you configure). These appear in Agent Mode once their API keys are saved
under **Settings → API Settings → API Providers**. See [Agent Mode → Providers](/docs#s=agent-mode&ss=providers) for details.
#### Codex CLI (OpenAI Plus/Pro)
Use OpenAI models through your ChatGPT Plus or Pro subscription.
- Install Codex: `npm install -g @openai/codex`
- Login: `codex login`
- In Repo Prompt, go to Settings → CLI Providers
- Click "Connect" next to Codex CLI
- Test the connection to verify it works
#### Gemini CLI (Google AI)
Use Gemini models through your Google AI subscription. Gemini CLI connects via ACP (Agent Communication Protocol), enabling
text streaming, permission support, bash tool access, and automatic model detection for a full-featured agent experience.
- Install Gemini CLI: `npm install -g @google/gemini-cli`
- Login: `gemini login`
- In Repo Prompt, go to Settings → CLI Providers
- Click "Connect" next to Gemini CLI
- Test the connection to verify it works
#### Cursor CLI (Cursor Pro/Business)
Use Cursor models through your Cursor Pro or Business subscription. Cursor CLI connects via ACP with dynamic
model discovery — available models are detected automatically from your Cursor installation.
- Install Cursor and ensure `cursor` is available on your PATH
- Login to your Cursor Pro or Business account
- In Repo Prompt, go to Settings → CLI Providers
- Click "Connect" next to Cursor CLI
- Test the connection — available models will be discovered automatically
### Using CLI Providers
Once connected, CLI providers appear as model options throughout Repo Prompt:
- **Chat Mode:** Select CLI models from the model dropdown
- **Context Builder:** Use CLI providers for AI-powered file discovery
- **Pro Edit:** Route edits through CLI providers for cost-effective workflows
### Troubleshooting
#### Connection Failed
- **CLI not found:** Ensure the CLI tool is installed globally and available in your PATH
- **Not logged in:** Run the login command for the respective CLI tool
- **Subscription inactive:** Verify your subscription is active with the provider
#### Rate Limits
CLI providers are subject to the rate limits of your subscription plan. If you hit rate limits:
- Wait a few minutes before retrying
- Consider using API keys for higher-volume work
- Check your subscription tier's limits with the provider
#### Update Required
If you see "update required" errors, update your CLI tool:
- Claude Code: `npm update -g @anthropic-ai/claude-code`
- Codex: `npm update -g @openai/codex`
- Gemini: `npm update -g @google/gemini-cli`
- Cursor: Update your Cursor application to the latest version
> **Tip:**
**Pro Tip:** CLI Providers are especially valuable with the Context Builder. Since context building can involve multiple AI calls, using your existing subscription can significantly reduce costs compared to API usage.

## OpenRouter

OpenRouter provides access to multiple AI providers through a single API. It's a great way to try different models without managing multiple API keys.
> **Tip:**
**IDE Mode only (Classic Edition):** Like other API key providers, OpenRouter powers Chat, Context Builder, Oracle, and Pro Edit. Agent Mode requires a CLI harness — see [Agent Providers](#s=agent-mode&ss=providers) for the six compatible CLIs.
### What is OpenRouter?
OpenRouter is a unified API that routes requests to various AI providers including:
- Anthropic (Claude models)
- OpenAI (GPT models)
- Google (Gemini models)
- Meta (Llama models)
- Mistral AI
- And many more...
### Setup
- Create an account at [openrouter.ai](https://openrouter.ai)
- Add credits to your account
- Go to Keys → Create Key
- Copy your API key
- In Repo Prompt: Settings → API Settings → OpenRouter
- Paste your key and click "Validate & Save"
### Available Models
Once connected, OpenRouter models appear in your model selector with an "openrouter/" prefix. Popular options include:
- `openrouter/anthropic/claude-sonnet-4.5`
- `openrouter/openai/gpt-5.4`
- `openrouter/google/gemini-3.0-preview`
- `openrouter/meta-llama/llama-3.1-70b`
- `openrouter/mistralai/mixtral-8x7b`
### Pricing
OpenRouter uses pay-per-token pricing that varies by model. Check [openrouter.ai/models](https://openrouter.ai/models) for current pricing.
### When to Use OpenRouter
- **Model variety:** Easy access to models from many providers
- **No commitment:** Try models without signing up for each provider
- **Cost comparison:** Compare pricing across providers
- **Fallback routing:** OpenRouter can route to alternatives if a model is unavailable
> **Tip:**
**Direct vs OpenRouter:** For your primary models, direct API keys often provide better performance and reliability. OpenRouter is great for exploration and accessing models you use occasionally.
> **Tip:**
**GPT-5.5 is not on OpenRouter:** GPT-5.5 Low/Medium/High are available only through Codex CLI, and GPT-5.5 Pro is ChatGPT Pro web only. OpenRouter continues to serve the GPT-5.4 family for OpenAI routing.

## Custom Providers

Connect to any OpenAI-compatible API endpoint - perfect for self-hosted models, company internal APIs, or alternative providers.
### What's Supported
Any API that follows the OpenAI API specification works, including:
- **Self-hosted models:** vLLM, text-generation-inference, LocalAI
- **Company APIs:** Internal model deployments
- **Alternative providers:** Services offering OpenAI-compatible endpoints
- **Proxies:** API gateways and load balancers
### Setup
- Open **Settings** (`⌘+,`)
- Go to **API Settings → Custom API**
- Enter your configuration:
**Base URL:** Your API endpoint (e.g., `https://your-api.company.com/v1`)
- **API Key:** Authentication key if required
- **Model Name:** The model identifier your API expects
- Click **Validate & Save**
### Configuration Examples
#### vLLM Server
#### Text Generation Inference
#### Company Internal API
### OpenAI Custom Base URL
You can also customize the OpenAI base URL for proxies without using a full custom provider:
- Go to Settings → API Providers
- Under OpenAI, click "Advanced (Custom Base URL)"
- Enter your custom endpoint
- Your OpenAI API key is used with the custom URL
### Troubleshooting
#### Connection Failed
- Verify the base URL is correct and accessible
- Check that the URL ends with `/v1` if your API expects it
- Ensure any required API key is correct
#### Model Not Found
- Verify the model name matches exactly what your API expects
- Some APIs require just the model name, others need the full path
- Check your API's documentation for the correct model identifier
#### Streaming Issues
If responses aren't streaming properly:
- Ensure your API supports server-sent events (SSE)
- Check that your proxy/gateway preserves streaming responses

# MCP Server

Connect external tools like Claude Code and Cursor via MCP.

## Overview

## MCP Server: An IDE for AI Agents
### What is MCP?
MCP (Model Context Protocol) is an open standard for AI tools to communicate with external
services. Repo Prompt's MCP server exposes its capabilities — file selection, codemaps,
Context Builder, chat, edits, workspace and tab lifecycle, app preferences, and Agent Mode
session control — as tools that any MCP-compatible agent can use. The same tool surface
is reachable two ways:
- **Direct MCP** — persistent connections for agents that natively speak MCP.
- **[rp-cli](/docs#s=rp-cli&ss=cli-guide)** — ephemeral shell invocations for agents and humans that prefer a terminal.
Picking one is a shape choice, not a capability tradeoff. Anything you can do in the UI —
switching workspaces, creating tabs, selecting files, running Context Builder, starting
chats, applying edits, orchestrating Agent Mode runs, flipping allowlisted preferences —
is reachable from either surface.
### Quick Access: MCP Controls
Click the **MCP Server** indicator in the toolbar for quick access to all MCP settings.
This is the primary control panel for MCP - no need to dig through preferences.
**Key settings to configure:**
- **Auto-Start:** Enable this so MCP is always available when you launch Repo Prompt
- **Chat Model Presets:** Choose which model handles `chat_send` requests from external agents
- **Context Builder:** Select the agent (Codex, Claude, Gemini) that powers `context_builder`
- **Quick Setup:** One-click install for Cursor, Claude Code, Codex CLI, and more
> **Tip:**
**Showing 0 tools?** If you just set up your client and it shows 0 available tools, the client cached the empty tool list before Repo Prompt was ready. Restart your client (Cursor, Claude Code, etc.) to pull the updated list.
### Repo Prompt as an IDE for Agents
Think of Repo Prompt's MCP server as providing everything an AI agent needs to work effectively with code:
#### File Navigation
Browse file trees, search by path or content, read files with line ranges - agents can explore codebases just like developers do.
#### Code Intelligence
Access codemaps showing function signatures and type definitions - token-efficient structural understanding without reading entire files.
#### Context Building
Select files with full content, line slices, or codemap-only modes. Auto-codemap management adds dependency context automatically.
#### AI-Powered Discovery
Run Context Builder as an MCP tool - let a headless agent select relevant files within a token budget.
#### Pair Programming
Invoke Repo Prompt's built-in chat for planning, reviewing, and implementing changes with your configured models.
#### File Editing
Create, move, delete files. Apply search/replace edits or full rewrites with diff visualization and undo support.
#### Workspace Management
List, switch, and create workspaces. Manage compose tabs for parallel tasks. Full programmatic control.
#### Multi-Window Support
Press `⌘+N` to open additional windows. MCP clients can target specific windows on demand, and agents can bind to specific tabs for isolated context.
#### Agent Control Plane
External clients can orchestrate Agent Mode sessions via `agent_run` (session-based run control)
and `agent_manage` (session/workflow management). See the [Tools Reference](/docs#s=mcp-server&ss=mcp-tools) for details.
#### App Settings
Flip allowlisted RepoPrompt preferences — appearance, prompt packaging,
edit-format defaults, preferred models, MCP auto-start, and the global Code Maps
toggle — via the `app_settings` tool. See
[App Settings Tool](/docs#s=mcp-server&ss=mcp-app-settings).
### Architecture Overview
The MCP server uses a secure, local-only architecture with UNIX socket transport:
**Local Socket Transport:**
External Client → rp-cli (stdio) → UNIX Socket → Repo Prompt App
All traffic stays local to your machine with no network ports exposed.
UNIX sockets provide strong isolation - connections are user-specific and
cannot be accessed by other users on the system.
### Compatible Clients
- **Claude Code** - Anthropic's official CLI with full MCP support
- **Cursor** - AI-powered editor with MCP integration
- **Codex CLI** - OpenAI's CLI tool
- **Any MCP Client** - The protocol is open and standardized
### Sibling: rp-cli
Prefer a shell, or running on an agent that doesn't natively speak MCP? The same tools
are reachable from [`rp-cli`](/docs#s=rp-cli&ss=cli-guide),
RepoPrompt's scriptable control surface. Drive workspaces, selections, context, chats,
edits, Agent Mode runs, and app settings from Bash or any shell. See
[App Settings from the CLI](/docs#s=rp-cli&ss=cli-app-settings)
for the CLI view of the same `app_settings` surface.
### Quick Start: claude-rp
For the fastest way to use Claude Code with RepoPrompt, install the `claude-rp` wrapper
from the MCP Server popover → Install → "claude-rp (Claude Code wrapper)".
This installs a simple command that launches Claude Code pre-configured to use RepoPrompt's
MCP tools instead of Claude's built-in file operations. No global MCP configuration needed -
just run `claude-rp` instead of `claude`.
### Key Benefits
- **Better Context:** Agents get token-efficient codemaps and slices instead of dumping entire files
- **Multi-Repository:** Work across multiple project folders in a single workspace
- **Visual Feedback:** See what agents are doing in Repo Prompt's UI
- **Human Oversight:** Approve connections, review edits before applying
- **Undo Support:** File checkpoints let you restore previous states
### Security Model
- All connections require explicit user approval (or allowlist)
- Only connections from the local machine are accepted (UNIX sockets are local-only)
- No network ports exposed - uses local UNIX sockets for communication
- Per-user isolation - socket directories are user-specific
- Individual tools can be enabled/disabled
- Only one window owns the MCP server at a time
> **Tip:**
**Getting Started:** Click the **MCP Server** button in the toolbar to enable the server, configure your models, and install in your preferred client. See the Setup Guide for step-by-step instructions.

## Setup Guide

Get Repo Prompt's MCP server connected to your preferred AI tool in minutes.
The server enables external agents to use Repo Prompt's powerful context building,
code intelligence, and editing capabilities.
### Quick Setup
- Open **Settings → MCP Server**
- Enable the **MCP Server** toggle
- Click the install button for your client (or copy configuration)
- Restart your client and approve the connection in Repo Prompt
### Client-Specific Instructions
#### Cursor (One-Click)
- Open **Settings → MCP Server** in Repo Prompt
- Click **"Install in Cursor"**
- Restart Cursor
- When Cursor connects, approve in Repo Prompt (check menu bar for dialog)
#### Claude Code
- Open **Settings → MCP Server** in Repo Prompt
- Click **"Copy Configuration"**
- Open Claude Code's MCP settings (`claude mcp add` or edit config file)
- Paste the configuration
- Restart Claude Code
- Approve the connection when prompted in Repo Prompt
#### Codex CLI (One-Click)
- Open **Settings → MCP Server** in Repo Prompt
- Click **"Install for Codex"**
- This automatically configures your `codex.toml` with extended timeouts
- Restart Codex and approve the connection
#### Other MCP Clients
- Open **Settings → MCP Server**
- Click **"Copy Configuration"** to get the JSON config
- Add to your client's MCP server configuration
- The client will launch `repoprompt-mcp` automatically via stdio
- Approve the connection in Repo Prompt
### Configuration Format
The copied configuration follows the MCP standard format:
{`{
"mcpServers": {
"repoprompt":
}
}`}
The exact path varies by installation. Always use the "Copy Configuration" button
to get the correct path for your system.
### Connection Approval
When a client first connects, Repo Prompt shows an approval dialog. You can:
- **Allow Once:** Permit this single session
- **Always Allow:** Add to allowlist (recommended for trusted clients)
- **Deny:** Reject the connection
> **Tip:**
**Tip:** The approval dialog appears in the menu bar area. If you don't see it,
check that Repo Prompt has focus or look for a notification.
### Verifying the Connection
Once connected, you'll see the connection status in Repo Prompt's toolbar:
- **Connected: [Client Name]** - Ready to receive tool calls
- **Animated icon** - Tool call in progress
Test the connection by asking your agent to list files or get the workspace context.
In Claude Code, try: "Use Repo Prompt to show me the file tree."
### Transport Mode
If you're in a corporate environment with strict firewall policies, switch to
** Filesystem transport** in Settings. This uses file-based message passing
instead of localhost TCP connections.
See **Transport Modes** documentation for details on when and why to use each mode.
### Troubleshooting Setup
#### Client can't find repoprompt-mcp
- Re-copy the configuration - paths are system-specific
- Ensure Repo Prompt is installed in /Applications
- Check that the CLI binary exists at the configured path
#### No approval dialog appears
- Ensure MCP Server is enabled in Settings
- Check the menu bar for pending approval notifications
- Try toggling the server off and on
#### Connection keeps dropping
- Try switching to Filesystem transport mode
- Check if antivirus software is interfering
- Ensure no VPN is redirecting localhost traffic
#### Tools not appearing in client
- Check **Settings → MCP Server → Tools** to ensure tools are enabled
- Restart the client after enabling tools
- Verify the connection is active (check status indicator)
> **Tip:**
**Next Steps:** Once connected, explore the **Tools Reference** to
see all available capabilities, or check **Connection Management** to learn
about multi-window mode and tab binding.

## Tools Reference

Complete reference for all MCP tools available in Repo Prompt. Tools are organized by category
and can be individually enabled/disabled in **Settings → MCP Server → Tools**.
### Selection & Context Tools
#### `manage_selection`
Add, remove, or replace files in the current selection with fine-grained control over representation.
Parameter
Description
`op`
get | add | remove | set | clear | preview | promote | demote
`paths`
Array of file or folder paths (folders expanded recursively)
`mode`
full | slices | codemap_only
`slices`
Array of {`{path, ranges: []}`}
`view`
summary | files | content | codemaps
**Selection Modes:**
- **full:** Complete file content (default)
- **slices:** Only specified line ranges
- **codemap_only:** Just function/type signatures (token-efficient)
**Auto-Codemap:** When adding files with full/slices mode, related dependency files
automatically get codemaps added. Use promote/demote to manually adjust.
#### `workspace_context`
Get a complete snapshot of the current workspace state.
Parameter
Description
`include`
Array of: prompt, selection, code, files, tree, tokens
Returns prompt text, selected files, codemaps, and token counts in a single call.
#### `prompt`
Get or modify the shared prompt/instructions text.
Parameter
Description
`op`
get | set | append | clear
`text`
Text for set/append operations
#### `context_builder`
Intelligently explore the codebase and build optimal file context for a task.
Parameter
Description
`instructions`
Describe the task or question you need help with
`response_type`
`clarify` (default, context only) | `question` (answer using context) | `plan` (generate implementation plan) | `review` (generate code review with git diffs)
Creates a fresh compose tab, runs a headless agent to explore the codebase,
and selects relevant files within a token budget. Returns a `chat_id` when `response_type` is
`question`, `plan`, or `review` for continuing the conversation via `chat_send`.
Can take 30s-5min+ depending on codebase size and task complexity.
### File Operation Tools
#### `get_file_tree`
Get an ASCII directory tree of the project.
Parameter
Description
`type`
files | roots
`mode`
auto | full | folders | selected
`path`
Optional starting folder
`max_depth`
Limit tree depth (root = 0)
Files with available codemaps are marked with `+` in the tree output.
#### `file_search`
Search by file path and/or content with regex support.
Parameter
Description
`pattern`
Search pattern (regex by default)
`mode`
auto | path | content | both
`regex`
true (default) | false for literal matching
`context_lines`
Lines of context around matches
`filter`
{``}
`max_results`
Limit results (default: 50)
#### `read_file`
Read file contents with optional line ranges.
Parameter
Description
`path`
File path (relative or absolute)
`start_line`
1-based start line (negative for tail)
`limit`
Number of lines to read
Use `start_line: -N` to read the last N lines (like `tail -n`).
#### `get_code_structure`
Get codemaps (function/type signatures) for files or directories.
Parameter
Description
`scope`
selected | paths
`paths`
Array of file/folder paths (when scope=paths)
`max_results`
Limit codemaps returned (default: 25)
Directories are processed recursively. Files without codemap support are reported.
#### `file_actions`
Create, delete, or move files.
Parameter
Description
`action`
create | delete | move
`path`
File path (absolute required for delete)
`content`
File content (for create)
`new_path`
Destination path (for move)
`if_exists`
error (default) | overwrite
Multi-root workspaces require absolute paths for create to avoid ambiguity.
#### `apply_edits`
Apply search/replace edits or full file rewrites.
Parameter
Description
`path`
File to edit
`search`
Text to find (single edit)
`replace`
Replacement text (single edit)
`edits`
Array of {``} for multiple edits
`rewrite`
Complete file content for full rewrite
`all`
Replace all occurrences (default: false)
`verbose`
Include diff preview in response
Handles indentation correction, ambiguous search block validation, and malformed input recovery.
> **Tip:**
**CLI usage:** `apply_edits` requires JSON format via `rp-cli`:
'
rp-cli -c apply_edits -j edits.json      # From .json file (auto-detected)
rp-cli -c apply_edits -j @edits.json     # From file (explicit @)
echo '...' | rp-cli -c apply_edits -j @- # From stdin`}
Raw newlines/tabs in JSON strings are auto-repaired for LLM-generated payloads.
### Chat & Model Tools
#### `chat_send`
Start or continue chat conversations with Repo Prompt's built-in chat.
Parameter
Description
`message`
Your message to send
`new_chat`
true to start new, false to continue
`mode`
chat | plan | edit | review
`model`
Model preset ID or name
`chat_id`
Specific chat to continue
`chat_name`
Name for the session
`selected_paths`
Override selection for this message
`include_diffs`
Include edit diffs in response
**Modes:**
- **chat:** General conversation
- **plan:** Architectural planning without immediate edits
- **edit:** Generate and apply code changes
- **review:** Code review with git diff context from selected files
#### `chats`
List recent chats or view conversation history for the current workspace or a specific compose tab.
Parameter
Description
`action`
list | log
`chat_id`
Chat ID for log action
`scope`
workspace | tab (default: workspace)
`tab_id`
Optional compose tab UUID filter. With `scope="tab"`, omitting it uses the current bound tab when available, otherwise the active UI tab.
`limit`
Max results (default: 10 for list, 3 for log)
`diffs`
Include diff summaries in log
#### `list_models`
List available model presets with descriptions.
Returns preset ID, name, description, and supported modes. Use the ID with `chat_send`.
### Git Tools
#### `git`
Safe, token-efficient git abstraction for MCP agents. Also supports Jujutsu (jj) repositories natively.
See [Code Reviews & Git](/docs#s=mcp-server&ss=code-reviews) for deep review workflows and jj details.
Parameter
Description
`op`
status | diff | log | show | blame
`repo_root`
Repo path or loaded root name (defaults to first loaded root). Supports suffixes: `:worktree` or `:main` to target specific checkout
`repo_roots`
Array of repo paths or names (for multi-root operations)
`compare`
Compare spec: uncommitted (default), staged, unstaged, mergebase:X, back:N, last, main, trunk, or any revspec. `main`/`trunk` and `*:main` use merge-base semantics.
`detail`
summary (default) | files | patches | full
`scope`
all | selected (diff scope)
`artifacts`
Write snapshot artifacts (MAP.txt, patches) for diff
`ref`
Git ref for show operation (e.g., HEAD~1, main)
`path`
File path for blame operation
`lines`
Line range for blame (e.g., "45-60")
`count`
Number of commits for log
**Operations:**
- **status:** Repository state (branch, upstream, ahead/behind, staged/modified/untracked)
- **diff:** View changes with configurable detail level. Optionally writes artifacts.
- **log:** Commit history with stats
- **show:** Single commit details
- **blame:** Line-by-line attribution
**Worktrees:** Full support for git worktrees. Status and diff output includes worktree metadata (branch, main checkout path). Use `repo_root` suffixes to target specific checkouts in multi-worktree setups.
**Safety:** All git commands use `--no-ext-diff`, `--no-textconv`,
`--color=never`, and `GIT_TERMINAL_PROMPT=0` to ensure predictable, safe output.
### Workspace Management Tools
#### `manage_workspaces`
List, switch, create, or modify workspaces and tabs.
Parameter
Description
`action`
list | switch | create | delete | add_folder | remove_folder | list_tabs | select_tab | create_tab | close_tab
`workspace`
Workspace UUID or name
`name`
Name for new workspace, or optional name for `create_tab`
`folder_path`
Absolute path for add/remove_folder
`tab`
Tab UUID or name for `select_tab` or `close_tab`
`mode`
For `create_tab`: `blank` | `fork` (default: `blank`)
`source_tab`
Optional source tab for `create_tab` when `mode="fork"`
`bind`
For `create_tab`: bind this MCP connection to the new tab (default: true)
`window_id`
Target window (multi-window mode)
`focus`
For `select_tab` or `create_tab`: switch the UI to that tab (default: false)
`allow_active`
For `close_tab`: allow closing the currently visible tab
`open_in_new_window`
For action=switch or create: opens workspace in a new window and binds connection. Returns `window_id` in response.
`switch_to_created`
For action=create: switch to the newly created workspace in the target window (default: true).
Create, delete, and folder operations modify workspace state. Tab binding ensures consistent
context even if the user switches tabs during your session. Use `open_in_new_window` with
the switch or create action to open a workspace in a fresh window without affecting existing windows.
**Tab automation:** `create_tab` defaults to `bind=true` and `focus=false`, so agents can create isolated background tabs without stealing UI focus. `close_tab` refuses to close the last remaining tab, the active visible tab unless `allow_active=true`, or any tab that still has live bound runs.
### App Settings
#### `app_settings`
Read and update an allowlisted set of RepoPrompt's global preferences — appearance,
prompt packaging, edit-format defaults, preferred models, the Context Builder
agent/model, MCP server behavior, and the global Code Maps toggle — without
opening the Settings UI. Secrets, tool ACLs, workspace-scoped settings, and
internal/migration flags are deliberately excluded.
Parameter
Description
`op`
`list` | `get` | `set` | `options`
`group`
`ui` | `prompt_packaging` | `editing` | `models` | `context_builder` | `mcp` | `code_maps`. Filter on `list` or selector on `get`.
`key`
Fully-qualified key (e.g. `ui.appearance_mode`). Required on `set`; optional selector on `get`.
`keys`
Array of keys for batch `get`. Mutually exclusive with `key` and `group`.
`value`
boolean | number | string | null. Required on `set`; validated against the entry's declared type.
`agent`
For `options`: filter candidates to one CLI backend (e.g. `claudeCode`, `codexExec`, `gemini`).
`limit`
For `options`: maximum number of candidates returned (1–200, default 60).
`detailed`
For `options`: include descriptions and model metadata in each candidate.
**Groups:** `ui`, `prompt_packaging`, `editing`, `models`, `context_builder`, `mcp`, `code_maps`.
**Examples:**
{`# Browse the catalog (values always included)
# Inspect one group
# Batch read
# Toggle a flag
# Clear an optional model
# Switch the Context Builder agent (remembered model is preserved)
# List candidate values for a setting that advertises options_available
`}
**See the standalone**
[App Settings Tool](/docs#s=mcp-server&ss=mcp-app-settings)
**page** for the complete key allowlist, per-group tables, validation
rules, and the deliberately excluded categories.
### Agent Control Plane
> **Tip:**
**Advanced & Policy-Gated:** The `agent_run` and `agent_manage` tools
are part of the advanced agent external control capability. They may not appear on all MCP connections —
availability depends on the connection's policy configuration. These tools enable external orchestration
of Repo Prompt's Agent Mode sessions.
#### `agent_run`
Session-based control surface for long-running Agent Mode runs. Each `start` call returns
a `session_id` that becomes the control-plane identifier for `poll`, `wait`,
`steer`, `respond`, and `cancel`. Use `agent_manage` for durable
session history and metadata.
**Operations:**
Operation
Required Parameters
Description
`start`
`message`
Start a new agent run in a **new session**. Do not pass `session_id` — use `steer` to continue an existing session. Optional: `session_name`, `model_id` (role label like `explore`, `engineer`, `pair`, `design`, or a specific ID from `agent_manage.list_agents`), `workflow_id`/`workflow_name`, `detach`, `timeout`. Returns a snapshot with `session_id`.
`poll`
`session_id` or `session_ids`
Non-blocking read of the current run snapshot. With `session_ids` (array), returns all current snapshots in a collection response with `poll` metadata.
`wait`
`session_id` or `session_ids`, `timeout` (optional)
Blocks until the run needs input (`waiting_for_input`) or reaches a terminal state. With `session_ids` (array), waits for the **first** session to reach an interesting state and returns the winning snapshot. Optional `timeout` in seconds (fractional OK); defaults to 300s (5 min). Use `timeout=0` for an immediate non-blocking check. `session_id` and `session_ids` are mutually exclusive.
`cancel`
`session_id`
Cancel an active agent run. Only valid when the run is `running` or `waiting_for_input`. Waits for cleanup before returning the final snapshot.
`steer`
`session_id`, `message`
Continue an existing agent session. If the run is still active, the instruction is injected into that run. If the previous run already finished, a new run starts in the same session. Optional: `wait=true` to block until the steered run finishes or needs input, `timeout_seconds` (defaults to 300s, implies `wait=true`). This is the only way to continue an existing session — `start` always creates a new one.
`respond`
`session_id`, `interaction_id`
Resolve a pending interaction. Use `response` for decisions/text, `answers` for structured input, and `amendment` when relevant. Also supports `workflow_id`/`workflow_name`.
**Snapshot Status Values:**
- `running` — Agent is actively working
- `waiting_for_input` — Agent needs a response (check `interaction` field)
- `completed` — Run finished successfully
- `failed` — Run encountered an error (check `failure_reason`: `process_crash`, `timeout`, `agent_error`)
- `cancelled` — Run was cancelled (`failure_reason: cancelled`)
- `expired` — The session has no active control snapshot available
**Snapshot Fields:** Responses include `session_id`, `status`, `status_text`, `assistant_text` (partial output while running, full output when terminal), `transcript_item_count`, `failure_reason` (on failed/cancelled), and a `session` object with `id`, `name`, `tab_id`, `parent_session_id`. Agent info (`agent.id`, `agent.name`, `agent.model`) is included when available.
**Interaction Kinds** (for the `respond` operation):
Kind
Response Fields
`approval`
`response` (`accept` | `accept_for_session` | `accept_with_amendment` | `decline` | `cancel`), optional `reason` / `amendment`
`question`
`response` (text) or `answers` (object), optional `skip`
`user_input`
`response` (text) or `answers` (object), optional `skip`
**Sub-Agent Spawning:**
Top-level MCP-started agent sessions can spawn sub-agents using `agent_run` and `agent_manage` —
just like user-initiated sessions. This enables the **Orchestrate** workflow, which plans, decomposes,
and delegates tasks across multiple agents. Only nested sub-agent sessions are blocked from spawning further agents
(no recursive spawning).
**Multi-Session Wait & Poll:**
When running multiple agents in parallel, use `session_ids` (array) instead of `session_id` to
monitor them efficiently:
- **`op=wait` with `session_ids`:** Blocks until the *first* session reaches an interesting state. Returns the winning snapshot at the top level with a `wait` metadata object containing `mode`, `result`, `winner_session_id`, and `pending_session_ids`.
- **`op=poll` with `session_ids`:** Returns all current snapshots immediately in a collection response with `poll` metadata and a `snapshots` array.
`session_id` and `session_ids` are mutually exclusive. Multi-session mode is only supported for `wait` and `poll` — not `steer`, `respond`, or `cancel`.
**Typical workflow:**
- Call `agent_run op=start message="..."` → receive `session_id`
- Call `agent_run op=wait session_id="..."` → blocks up to 5 min (or custom `timeout`) until input needed or terminal
- When `status=waiting_for_input`, call `agent_run op=respond` with the returned `interaction_id` and an appropriate `response`
- Repeat wait/respond loop until the run reaches a terminal state
#### `agent_manage`
Session and workflow management surface for Agent Mode. Use this tool to discover available agents,
list and inspect sessions, and read transcript logs.
`agent_run` controls the current run for a session, while session data itself persists across runs.
**Operations:**
Operation
Key Parameters
Description
`list_agents`
—
List available agent providers and their supported models.
`list_sessions`
`limit`, `state`
List agent sessions (both live and persisted). Returns `session_id` for each session. When called from agent mode, automatically scopes to sessions spawned by the current agent session. Filter by `state` (e.g., `running`, `completed`, `failed`), or `agent`. MCP-originated sessions include `is_mcp_originated: true`.
`get_log`
`session_id`
Read session transcript as compact XML. Returns `name` and `transcript_xml`. Supports `offset` and `limit` for pagination.
`create_session`
`session_name`
Create a new agent session. Optional: `model_id` (role label or specific ID).
`resume_session`
`session_id`
Hydrate and resume an existing session. Optional: `model_id`.
`stop_session`
`session_id`
Stop/cancel a currently live running session. Returns `stop_requested: true` if the session was active.
`cleanup_sessions`
`session_ids` (array)
Delete specific MCP-originated sessions by UUID. Only sessions started via MCP are eligible — user-created sessions are never deleted. Skips active sessions. Use `list_sessions` first to find session IDs.
`list_workflows`
—
List available agent workflows.
**Session IDs:** Full UUIDs are required for all `session_id` parameters. There is no separate `get_session` operation —
use `list_sessions` for metadata and `get_log` for transcript content.
**Workflow runs:** To start a workflow-backed run, use `agent_run op=start` with
`workflow_id` or `workflow_name` plus your `message`. Then use `agent_run`
operations (`wait`, `respond`, etc.) with that `session_id` to control the run.
#### Agent Control Plane Examples
> **Tip:**
**Tool Availability:** Individual tools can be enabled/disabled in
** Settings → MCP Server → Tools**. Disabled tools won't appear in the
client's tool list. Agent control tools (`agent_run`, `agent_manage`) are
additionally gated by connection policy and may not appear on all MCP connections.

## Transport Modes

Repo Prompt's MCP server uses secure local UNIX sockets for communication between external
clients and the main application. All traffic stays local to your machine with no network
ports exposed.
### How It Works
When an external client (Claude Code, Cursor, etc.) connects to Repo Prompt, the CLI bridge
establishes a secure local socket connection:
- External client launches `repoprompt-mcp` via stdio
- CLI bridge connects to Repo Prompt through a local UNIX socket
- Messages are forwarded bidirectionally between the client and Repo Prompt
- Connection persists for the session lifetime with automatic reconnection on interruption
### Security
UNIX sockets provide strong security guarantees:
- **No network exposure:** Connections are local-only with no TCP ports opened
- **Per-user isolation:** Socket directories are user-specific, preventing cross-user access
- **Approval flow:** New clients must be explicitly approved before accessing your workspace
- **Session tokens:** Each CLI instance has a unique session identifier for connection management
### Connection Management
The MCP dashboard (accessible from the status bar icon) shows all active connections and allows you to:
- View connected clients and their activity
- Disconnect specific clients
- Manage auto-approval settings for trusted clients
### Automatic Reconnection
If Repo Prompt restarts or temporarily becomes unavailable, connected clients will automatically
attempt to reconnect. The CLI maintains its session identity across reconnections, so your
workflow continues seamlessly.
### Troubleshooting
- **Connection refused:** Ensure MCP Server is enabled in Settings and Repo Prompt is running
- **Approval not appearing:** Check that the client is using a compatible version of the CLI
- **Stale connections:** Use the MCP dashboard to disconnect old sessions
> **Tip:**
**Note:** The UNIX socket transport works reliably in all environments including
corporate networks with strict firewall policies, as no network ports are used.

## Settings & Presets

The MCP Server popover provides quick access to server configuration, model presets,
and Context Builder settings. Access it via the MCP indicator in the toolbar.
## Popover Overview
Click the MCP indicator in the toolbar to open the settings popover. The indicator shows
connection status and the number of available tools.
This is the primary location to configure the MCP server, including:
- **Server activation** - Enable/disable MCP tools for external clients
- **Chat Model Presets** - Choose which model handles MCP chat requests
- **Context Builder** - Select the agent that powers context discovery via MCP or CLI
## Server Controls
### Enable MCP Tools
The main toggle enables or disables MCP tools for the current window. When enabled,
external clients can interact with your workspace through the MCP protocol.
### Auto-Start
When checked, the MCP server starts automatically when RepoPrompt launches.
This is useful if you always want MCP available for your AI tools.
### Status Indicator
- **Green dot** - Server active with tools enabled
- **Orange dot** - Tools enabled but waiting for listener
- **Gray dot** - Inactive or tools disabled
## Chat Model Presets
Control which AI models are available to MCP clients when they use the `chat_send`
and `list_models` tools.
### Use Model Preset for MCP Chat
When enabled, the `list_models` tool returns your configured Model Presets,
allowing AI agents to select from your preferred model configurations. This gives agents
access to different models for different tasks (e.g., fast models for simple queries,
reasoning models for complex planning).
When disabled, `list_models` only returns the current default chat model.
### Fallback Model
If Model Presets are enabled but none are configured, MCP chat uses this fallback model.
Choose a model with strong reasoning capabilities for planning-oriented workflows.
> **Note:**
**Tip:** Configure Model Presets in Settings → Chat → Manage Presets to give
AI agents a selection of models optimized for different task types.
### How Agents Use Presets
When an AI agent calls `chat_send`, it can specify a `model` parameter
that matches a preset ID or name. The agent can first call `list_models` to
discover available presets and their descriptions, then choose the most appropriate one.
``
## Context Builder Settings
Configure which agent powers the `context_builder` MCP tool, which helps
AI agents build relevant file context for their tasks.
### Context Builder Agent
Select the agent type used when MCP clients invoke context discovery. Options include:
- **Codex** - OpenAI's Codex models, optimized for code understanding
- **Claude** - Anthropic's Claude models
- **Gemini** - Google's Gemini models
The selected agent determines which AI provider handles context-building requests.
Choose based on your API availability and preferred model capabilities.
### How context_builder Works
When an MCP client calls `context_builder` with task instructions,
RepoPrompt's Context Builder agent:
- Analyzes the task requirements
- Explores the codebase to find relevant files
- Builds an optimized selection within token limits
- Returns the selection for subsequent operations
This enables AI agents to automatically gather context without manual file selection.
## Quick Setup
The popover includes buttons for quick installation in popular AI clients:
### Install MCP Server
Click "Install..." to automatically configure the MCP server in supported clients:
- **Cursor** - Adds to Cursor's MCP configuration
- **VS Code** - Configures the VS Code MCP extension
- **Codex CLI** - Sets up OpenAI's Codex CLI
- **Gemini CLI** - Configures Google's Gemini CLI
- **Claude Desktop** - Adds to Claude's MCP servers
- **Claude Code (per-project)** - Installs MCP config in the current workspace's `.claude/` folder
### CLI Installation (rp-cli)
Install the `rp-cli` command to `/usr/local/bin` for terminal access
to RepoPrompt's MCP tools. This enables scripting, automation, and interactive exploration
of your codebase from the command line.
``
### claude-rp Wrapper
Install the `claude-rp` command - a wrapper for Claude Code that automatically
configures it to use RepoPrompt's MCP tools instead of Claude's built-in file operations.
**Why use claude-rp?**
- **Frees up context:** RepoPrompt's codemaps and slices are more token-efficient than dumping entire files
- **No global MCP setup needed:** The wrapper configures everything automatically via command-line flags
- **Visual feedback:** See what Claude is doing in RepoPrompt's UI
- **Better file selection:** Use RepoPrompt's selection, slicing, and codemap features
``
> **Note:**
**Prerequisite:** RepoPrompt must be running with MCP Server enabled for `claude-rp` to work.
### Copy JSON
Copies the MCP server configuration to your clipboard for manual installation
in any MCP-compatible client:
`{`{
"mcpServers": {
"RepoPrompt":
}
}`}`
> **Note:**
**Note:** After installing, restart the client application if the
integration isn't detected immediately.
## Advanced Settings
For additional configuration options, click "Open Status Dashboard" to access:
- Individual tool enablement
- Connection diagnostics and troubleshooting
- Active client management
- Multi-window configuration
See [Transport & Security](/docs#s=mcp-server&ss=mcp-transport) and
[Connection Management](/docs#s=mcp-server&ss=mcp-connections) for details.
);
};

## Connection Management

Repo Prompt provides comprehensive tools for managing MCP connections, including status monitoring,
multi-window support, tab binding, and workspace management - all controllable both through the UI
and programmatically via MCP tools.
### Connection Status UI
The MCP connection status is displayed in the toolbar and provides real-time feedback:
Status
Meaning
Server Off
MCP Server is disabled in Settings
Listening
Server is running, waiting for connections
Connecting...
Client is establishing connection
Connected: [Client Name]
Active connection with named client (e.g., "Claude Code")
Tool Running (animated)
A tool call is currently being processed
Click the status indicator to access quick actions: view connection details, copy configuration,
or open MCP settings.
### Connection Approval
When a new client attempts to connect, Repo Prompt shows an approval dialog:
- **Client name:** Identifies the connecting application
- **Allow Once:** Permit this single connection
- **Always Allow:** Add to allowlist for automatic approval
- **Deny:** Reject the connection
> **Tip:**
**New in 1.5.41:** The connection approval dialog now defaults to "Always Allow"
to reduce repeated prompts for trusted clients.
### Multi-Window Mode
Repo Prompt supports multiple windows, each potentially showing different workspaces.
The MCP server can be configured to work across windows:
#### Single Window Mode (Default)
- One window owns the MCP server
- All tool calls operate on that window's workspace
- Simpler mental model for basic use
#### Multi-Window Mode
Enable in **Settings → MCP Server → Multi-Window Mode**
- Agents can query available windows and their workspaces
- Tool calls can target specific windows
- Enables parallel work across multiple projects
When multi-window mode is enabled, the `manage_workspaces` tool gains additional capabilities:
{`// List all workspaces across windows
// Switch a window to a different workspace
// Open workspace in a NEW window and bind connection to it
// Returns:
// Create a new workspace
// Create a new workspace and switch to it
// Create a new workspace in a NEW window
// Returns:
// Add folder to workspace
`}
### Tab Management
Compose tabs allow parallel work contexts within a single window. MCP clients can manage tabs programmatically:
#### Listing Tabs
{`// List tabs in current window
// Response includes:
// - Tab ID and name
// - [active] = Currently visible tab
// - [bound] = Tab this MCP connection is pinned to`}
#### Tab Binding
By default, MCP tools operate on whichever tab is currently active. This can cause issues
if the user switches tabs during a long operation. Tab binding solves this:
{`// Bind to a specific tab for consistent context
// focus: true = switch UI to show this tab (can disrupt user)
// focus: false = bind silently, user's view unchanged`}
Once bound, all subsequent tool calls from this connection operate on the bound tab,
regardless of which tab the user is viewing.
#### Creating Tabs for Background Work
MCP clients can now create new compose tabs explicitly. This is useful for spinning up a fresh task context
without disturbing the tab the user is currently looking at.
{`// Create a blank background tab and bind this MCP connection to it
// Fork an existing tab into a new background tab
`}
`create_tab` defaults to `bind=true` and `focus=false`. That means automation can create an isolated tab for a task,
keep future tool calls pinned to it, and avoid stealing focus from the user.
#### Closing Tabs Safely
Tabs can also be closed programmatically, but Repo Prompt applies safety checks to prevent destructive or confusing behavior.
{`// Close a non-active tab by name or UUID
// Explicitly allow closing the currently visible tab
`}
- The last remaining compose tab cannot be closed
- The currently visible tab is protected unless `allow_active=true`
- Tabs with live bound runs cannot be closed until those runs finish or disconnect
#### Tab-Scoped Chat History
The `chats` MCP tool now supports chat inspection at either workspace scope or compose-tab scope.
This is especially helpful when you use multiple tabs for parallel work and want chat history that matches the tab currently bound to your connection.
{`// List recent chats for the currently bound tab
// Read recent messages from the current tab's most recent chat
// Inspect a specific tab explicitly
`}
When `scope` is `tab` and `tab_id` is omitted, Repo Prompt uses the current bound tab when available,
otherwise it falls back to the active tab in the UI.
#### Context Builder Discovery Tab
When running Context Builder via MCP (`context_builder`), a fresh compose tab
is automatically created for each run. This ensures discovery operations don't interfere
with your existing work context.
### Workspace Approval System
Certain workspace operations require explicit user approval based on risk level:
Operation
Risk Level
Approval Required
List workspaces
None
No
Switch workspace
Low
No (existing workspaces)
Create workspace
Medium
Yes
Add folder
Medium
Yes
Delete workspace
High
Yes
### Connection Lifecycle
Understanding the connection lifecycle helps troubleshoot issues:
- **Server Start:** Repo Prompt opens listening socket/creates filesystem inbox
- **Client Launch:** External tool spawns `repoprompt-mcp` CLI
- **Handshake:** CLI establishes connection and exchanges capabilities
- **Approval:** User approves (or connection auto-approved from allowlist)
- **Active:** Tool calls flow bidirectionally
- **Disconnect:** Client closes or user stops server
- **Cleanup:** Resources released, filesystem folders deleted
### Reconnection Behavior
Connection management was significantly improved in 1.5.41:
- **App Restart:** Connections automatically rebind when Repo Prompt restarts
- **Client Restart:** New connection inherits previous approval status
- **Tab Context:** Bound tabs are restored across reconnections
- **Multi-Window:** Window routing is preserved through restarts
### Troubleshooting Connections
#### Connection Not Appearing
- Ensure MCP Server is enabled in Settings
- Check the approval queue (look in menu bar for pending approvals)
- Verify the client configuration points to correct `repoprompt-mcp` path
#### Stale Connection State
- Toggle the MCP Server off and on in Settings
- Restart the external client
- Check for orphaned connection folders in `~/Library/Application Support/RepoPrompt/MCPFS/`
#### Wrong Window/Tab Receiving Tools
- Use `list_tabs` to verify which tab is bound
- Use `select_tab` to explicitly bind to the correct tab
- In multi-window mode, use `manage_workspaces` to target the right window
> **Tip:**
**Pro Tip:** For long-running agent sessions, always bind to a specific tab using
`select_tab` early in the session. This prevents context confusion if tabs are
switched during operation.

# rp-cli

Use Repo Prompt from your terminal for automation and scripting.

## Command Line Guide

> **Tip:**
**What is rp-cli?** `rp-cli` is RepoPrompt's **scriptable control surface** —
a shell-level bridge to the same tool surface the MCP server exposes. Drive workspaces,
tabs, file selections, Context Builder, chat, edits, Agent Mode sessions, and
allowlisted app settings from Bash, Makefiles, scripts, or any agent that prefers a
terminal. The core automation surface — workspaces, tabs, selections, context,
chats, edits, allowlisted app preferences, and Agent Mode sessions — is
reachable from the CLI, while API credentials, tool ACLs, workspace approvals, and
other sensitive or internal settings remain UI-only by design.
When an agent like Claude Code, Codex, Cursor, or Gemini runs `rp-cli`
through its Bash/shell tool, it gets the same surface a native MCP client would:
file selection, codemaps, Context Builder, chat, edits, workspace and tab lifecycle,
allowlisted app preferences via `app_settings`, and Agent Mode run control.
The CLI is especially useful for agents that don't speak MCP natively, for ad-hoc
shell automation, and for mixing RepoPrompt with other tools in a script.
The CLI communicates with the running Repo Prompt app over a local UNIX socket. You don't need to configure MCP in the agent, but you **do** need the MCP Server enabled in Repo Prompt's settings for the CLI to connect. The shorthand verbs below map to the same MCP tools documented in the [MCP Tools Reference](/docs#s=mcp-server&ss=mcp-tools); use `rp-cli -d <tool>` or `rp-cli tools <group> --schema` for the authoritative schema.
> **Tip:**
**New: `app_settings`:** RepoPrompt exposes an allowlisted set of
global preferences through the `app_settings` tool and the matching
`settings` tool group. See
[App Settings from the CLI](/docs#s=rp-cli&ss=cli-app-settings)
for the shell-focused guide and
[App Settings Tool](/docs#s=mcp-server&ss=mcp-app-settings)
for the full allowlist and safety story.
### CLI vs MCP: When to Use Which
Both the CLI and direct MCP integration provide access to the same tools, but with different tradeoffs:
Aspect
CLI (`rp-cli`)
Direct MCP
**Connection**Ephemeral - each invocation is independentPersistent - binds once per agent session
**Window/Tab targeting**Must pass `-w` and `-t` on every callBind once with `select_tab`, persists for session
**Command chaining**Yes - use `&&` to chain commandsNo - one tool call per request
**Output redirection**Yes - pipe to files with `>`No - results returned in response
**Token efficiency**Higher - formatted text outputLower - structured JSON responses
**Setup complexity**None - just call via BashRequires MCP server configuration
**Use CLI when:**
- Your agent supports Bash/shell but not MCP directly
- You want to chain multiple operations in one call, or pipe output to files
- You're building agent skills or workflows that mix Repo Prompt with other shell tools
- You don't want MCP tool schemas loaded into every agent session—CLI is on-demand, keeping conversations lighter when Repo Prompt isn't needed
**Use MCP when:**
- Your agent has native MCP support and you want persistent window/tab binding
- You prefer structured JSON responses for programmatic processing
- Your workflow primarily uses Repo Prompt and benefits from having tool schemas always available
### Getting Started
Before using `rp-cli`, you'll need three things: Repo Prompt running on your Mac, the MCP Server enabled in settings, and the CLI installed to your PATH.
To install the CLI, open Repo Prompt, go to Settings &rarr; MCP Server, and click "Install CLI to PATH". This creates a symlink at `/usr/local/bin/rp-cli` (macOS will prompt for administrator access).
After installing, open a new terminal and verify it works:
### Exec Mode: The Primary Mode for Agents
Exec mode is designed for AI agents and scripts. Run commands with `-e` and they execute immediately:
#### Core Concept: Selection is Context
The tab's **file selection is the context for chat**. The AI only sees files you've selected.
Use `manage_selection` to curate context manually, or `context_builder` to auto-select relevant files.
#### MCP Tools Reference
The CLI provides shorthand commands that map to MCP tools. Use `-d <tool>` to see full parameter documentation including types, required/optional, and valid values:
MCP Tool
Shorthand
Key Parameters
`manage_selection``select`op (`add|remove|set|clear|get|preview|promote|demote`), paths (array), mode (`full|slices|codemap_only`)
`context_builder``builder`instructions (required), response_type (`clarify`=context only, `question`=answer, `plan`=implementation plan, `review`=code review)
`chat_send``chat`, `plan`, `review`message (string), new_chat (bool, required), mode (`chat|plan|edit|review`), model, chat_id
`read_file``read`, `cat`path (required), start_line (int, negative for tail), limit (int)
`file_search``search`, `grep`pattern (required), mode (`auto|path|content|both`), filter (object: extensions, paths, exclude), context_lines, max_results
`get_file_tree``tree`type (`files|roots`, default: files), mode (`auto|full|folders|selected`, default: auto), path, max_depth
`get_code_structure``structure`scope (`paths|selected`), paths (array), max_results
`workspace_context``context`include (array: `prompt,selection,code,files,tree,tokens`), path_display (`relative|full`)
`apply_edits`*JSON only*Use `call apply_edits {''}` - path (required), ONE of: rewrite | search+replace | edits array
`file_actions`*JSON only*Use `call file_actions {''}` - action (`create|delete|move`), path (required), content (for create), new_path (for move)
`prompt``prompt`op (`get|set|append|clear|export|list_presets|select_preset`), text, path, preset
`app_settings`*direct name*op (`list|get|set|options`), group (`ui|prompt_packaging|editing|models|context_builder|mcp|code_maps`), key, keys, value, agent, limit, detailed. See [App Settings from the CLI](/docs#s=rp-cli&ss=cli-app-settings).
`chats``chats`action (`list|log`), scope (`workspace|tab`), tab_id, chat_id (for log), include_diffs (bool), limit
`list_models``models`(no parameters - lists available AI model presets)
`manage_workspaces``workspace`, `tabs`action (`list|switch|create|delete|add_folder|remove_folder|list_tabs|select_tab|create_tab|close_tab`), workspace, tab, mode, source_tab, bind, focus, allow_active, open_in_new_window, switch_to_created, close_window
`list_windows``windows`(no parameters - lists open Repo Prompt windows)
`git``git`op (`status|diff|log|show|blame`), repo-root (path or name), repo-roots (comma-separated), compare (`uncommitted|staged|unstaged|mergebase:X|main|trunk|back:N|revspec`), detail, scope, artifacts, ref, path, lines
`agent_run`*direct name*op (`start|poll|wait|cancel|steer|respond`), session_id, session_name, message, model_id, interaction_id, response, timeout, detach
`agent_manage`*direct name*op (`list_agents|list_sessions|get_log|create_session|resume_session|stop_session|list_workflows`), session_id, model_id, session_name, state, limit
> **Tip:**
**Agent Control Plane:** `agent_run` and `agent_manage` are advanced, policy-gated tools
for external orchestration of Agent Mode sessions. They may not appear on all connections.
See the [MCP Tools Reference](/docs#s=mcp-server&ss=mcp-tools) for full documentation.
#### Common Examples by Tool
{`# Selection (manage_selection)
rp-cli -e 'select set src/'                        # Replace selection with folder
rp-cli -e 'select add lib/utils.ts'                # Add file to selection
rp-cli -e 'select add file.swift:10-50'            # Add line range (slice)
rp-cli -e 'select clear'                           # Clear all selection
# Context Builder (context_builder)
rp-cli -e 'builder "find auth code"'               # Build context only
rp-cli -e 'builder "add logout" --type plan'       # Generate implementation plan
rp-cli -e 'builder "how does X work?" --type question'  # Answer question
rp-cli -e 'builder "review changes" --type review' # Generate code review
# Chat (chat_send)
rp-cli -e 'chat "Explain this code"'               # Continue current chat
rp-cli -e 'chat "New question" --new'              # Start new chat
rp-cli -e 'plan "Design auth system"'              # Plan mode (new chat)
rp-cli -e 'review'                                 # Review selected files
# File Operations
rp-cli -e 'read src/main.swift'                    # Read entire file
rp-cli -e 'read src/main.swift 100 50'             # Lines 100-149
rp-cli -e 'search "TODO" --extensions .swift'      # Search Swift files
rp-cli -e 'tree --folders'                         # Show folder structure
rp-cli -e 'structure src/auth/'                    # Get codemaps
# Workspace & Context
rp-cli -e 'context --all'                          # Full workspace snapshot
rp-cli -e 'workspace list'                         # List workspaces
rp-cli -e 'workspace switch MyProject'             # Switch workspace
rp-cli -e 'workspace switch MyProject --new-window'  # Open in new window
rp-cli -e 'workspace create MyProject --new-window'  # Create in new window
rp-cli -e 'workspace create MyProject --switch'      # Create and switch to it
rp-cli -e 'workspace create MyProject --folder-path /path/to/repo'  # Create with a root folder
rp-cli -e 'workspace create MyProject --new-window --folder-path /path/to/repo'  # Create in new window with root folder
rp-cli -e 'workspace delete MyProject --close-window'  # Delete workspace and close its window
rp-cli -e 'tabs create "Bugfix"'                  # Create a blank background tab
rp-cli -e 'tabs create --mode fork --source-tab "Feature Work" --name "Feature Work Follow-up"'  # Fork a tab
rp-cli -e 'tabs close "Bugfix"'                   # Close a non-active tab
rp-cli -e 'tabs close "Feature Work" --allow-active'  # Explicitly close the visible tab
rp-cli -e 'chats list --scope tab'                 # List chats for the current tab
rp-cli -e 'chats log --scope tab --limit 10'       # Read recent messages from the current tab
rp-cli -e 'prompt export ~/context.md'             # Export for LLM
# App Settings (allowlisted app-wide preferences)
rp-cli -e 'app_settings op=list'                    # Browse the catalog (values always included)
rp-cli -e 'app_settings op=list group=ui'           # Inspect one group
rp-cli -e 'app_settings op=get key=ui.appearance_mode'
rp-cli -e 'app_settings op=set key=ui.show_tooltips value=false'
rp-cli -e 'app_settings op=set key=ui.appearance_mode value=Dark'
rp-cli -e 'app_settings op=set key=editing.complex_edit_strategy value="Parallel split"'  # quote enum values with spaces
rp-cli -e 'call app_settings '
rp-cli -e 'call app_settings '
rp-cli -e 'app_settings op=options key=models.planning_model agent=codexExec'  # candidate model values
rp-cli -e 'tools settings --schema'                 # app_settings schema as JSON
# Editing (apply_edits requires JSON format)
rp-cli -e 'call apply_edits '
rp-cli -e 'call apply_edits '
rp-cli -e 'call apply_edits '  # Multiline
rp-cli -e 'call file_actions '           # Create file
rp-cli -e 'call file_actions '  # Create with content
rp-cli -e 'call file_actions ' # Rename file
# Git (git) - defaults to first loaded root
rp-cli -e 'git status'                             # Repository status
rp-cli -e 'git diff --files'                       # Changed files list
rp-cli -e 'git diff --patches --compare staged'   # Staged patches (truncated)
rp-cli -e 'git diff --full --compare staged'      # Staged patches (untruncated)
rp-cli -e 'git diff --compare main'                # Working tree vs trunk merge-base
rp-cli -e 'git diff --compare mergebase:origin/main' # Explicit merge-base compare
rp-cli -e 'git log --count 10'                     # Recent commit history
rp-cli -e 'git show HEAD~1'                        # Show specific commit
rp-cli -e 'git blame src/main.swift --lines 10-40' # Line attribution
rp-cli -e 'git diff --artifacts'                   # Write snapshot (MAP.txt, patches)
rp-cli -e 'git status --repo-root MyApp'           # Target specific repo by name
rp-cli -e 'git diff --repo-roots MyApp,Backend'    # Multi-root diff
# Agent Control (advanced, policy-gated)
rp-cli -e 'agent_manage op=list_agents'            # List agent providers
rp-cli -e 'agent_manage op=list_sessions limit=5'  # List sessions
rp-cli -e 'agent_manage op=list_sessions state=failed' # Filter by state
rp-cli -e 'agent_manage op=list_workflows'         # List workflows
rp-cli -e 'agent_manage op=stop_session session_id=""' # Stop a live session
rp-cli -e 'agent_manage op=cleanup_sessions session_ids=["",""]' # Delete MCP sessions
rp-cli -e 'agent_run op=start message="Investigate auth"'  # Start run
rp-cli -e 'agent_run op=wait session_id=""'          # Wait (default 5 min timeout)
rp-cli -e 'agent_run op=wait session_id="" timeout=10' # Bounded 10s wait
rp-cli -e 'agent_run op=steer session_id="" message="Fix it" wait=true' # Steer and wait
rp-cli -e 'agent_run op=respond session_id="" interaction_id="" response="accept"'
rp-cli -d agent_run                                # Full schema docs
rp-cli -d agent_manage                             # Full schema docs`}
#### Parameter Syntax
The CLI supports multiple ways to pass parameters:
{`# Shorthand flags (most commands)
rp-cli -e 'search "TODO" --extensions .swift --context-lines 3'
# Key=value pairs (any tool)
rp-cli -e 'file_search pattern=TODO mode=content max_results=20'
# JSON arrays and objects (for complex parameters)
rp-cli -e 'manage_selection op=set paths=["src/","lib/"]'
rp-cli -e 'file_search pattern=TODO filter='
# Dotted keys expand to nested objects
rp-cli -e 'file_search pattern=TODO filter.extensions=[".swift"]'
# Raw JSON with call command (full control)
rp-cli -e 'call file_search {"pattern":"TODO","filter":}'`}
#### Quoting and Escape Sequences
In shorthand commands:
- **Single quotes** (`'...'`): Content is literal, no escape processing
- **Double quotes** (`"..."`): Escape sequences are processed:
`\n` → newline
- `\t` → tab
- `\r` → carriage return
- `\\` → literal backslash
- `\"` → literal quote
- Other backslashes (e.g., `\w` in regex) are preserved literally
For complex multiline content, prefer the JSON format (`call <tool> {''}`) which provides standard JSON escape handling.
#### chat_send: Starting vs Continuing Chats
The `new_chat` parameter controls whether to start a new conversation or continue the current one:
#### Chaining Commands
Commands can be chained with `&&` within a single `-e` flag. State like workspace selection carries through the chain:
#### Output Redirection
Commands support output redirection with `>` to write results directly to a file:
#### Prompt Export and Presets
Export full LLM-ready context (files, tree, codemaps) to a file, or manage copy presets:
The `prompt export` command builds a complete context file that can be used with any LLM, including the file tree, selected files, and codemaps.
#### Exec Mode Flags
#### JSON Argument Sources (-j / --json)
The `-j` flag accepts JSON arguments in multiple formats:
'
# From a .json file (auto-detected by extension, no @ needed)
rp-cli -c tool -j args.json
rp-cli -c tool -j /path/to/args.json
# From a file with explicit @ prefix
rp-cli -c tool -j @args.json
rp-cli -c tool -j @/path/to/args.json
# From stdin
echo '' | rp-cli -c tool -j @-`}
**Auto-repair:** Raw newlines and tabs inside JSON string values are automatically escaped.
This handles a common issue where LLMs produce JSON with unescaped control characters in multiline content.
### Interactive Mode
Interactive mode provides a REPL for exploration and experimentation. It's useful for learning commands, debugging workflows, or when you want to maintain state across multiple operations.
Inside the REPL, type `help` to see all commands. The same commands from exec mode work here, plus session management commands like `history`, `set`, and `status`.
#### One-Shot Flags
These flags run a single operation and exit - useful for scripting or quick lookups:
'  # Call tool directly
rp-cli -c read_file -j args.json                    # JSON from file (auto-detected)
rp-cli -c read_file -j @args.json                   # JSON from file (explicit @)
echo '...' | rp-cli -c read_file -j @-              # JSON from stdin`}
### Working with Multiple Windows
When multiple Repo Prompt windows are open, you **must** target a specific window.
**CLI limitation:** Each CLI invocation is an independent connection with no memory of previous calls. You must pass `-w` (and optionally `-t`) on **every** invocation. This is inherent to how the CLI works—each command starts fresh.
**MCP alternative:** If your agent supports MCP directly, use `manage_workspaces` with `action=select_tab` once at the start of your session. The binding persists for all subsequent tool calls without needing to repeat the window/tab targeting.
> **Tip:**
**Important for AI Agents**
When multiple windows are detected, AI agents **must**:
- Run `windows` to discover available windows
- Pass `-w <id>` on every CLI invocation
- Pass `-t <tab>` to target a specific compose tab
#### Targeting Specific Tabs
Workspaces can have multiple compose tabs, each with different file selections and prompts. Use `-t` to target a specific tab by name or UUID:
Using a dedicated tab ensures consistent file selection and prompt context across multiple tool calls.
### Scripting with .rp Files
For repeatable workflows, save commands to a script file:
Run with:
#### Workflow Shorthand Flags
Common workflows have shorthand flags that compile to exec commands:
Example:
### Getting Help
The CLI has tiered help for different needs:
### Complete Tool Schema Reference
Below is the complete schema documentation for all MCP tools. Use `rp-cli -d <tool> --verbose` to also see the raw JSON schema.
#### manage_selection
Manage the current file selection (context for chat). Shorthand: `select`
{`Parameters:
op (string): get | add | remove | set | clear | preview | promote | demote
Operation to perform
paths (array)
File or folder paths (required for add/remove/set)
mode (string): full | slices | codemap_only
How to represent files: 'full' (complete content), 'slices' (line ranges),
or 'codemap_only' (signatures only)
view (string): summary | files | content | codemaps
Amount of detail to return (default: summary)
slices (array)
Selection slices with line ranges:
- path (string, required): File path
- ranges (array): []
- lines (string): Shorthand like '10-20,40'
strict (boolean)
Error when no paths resolve (default: false)
path_display (string): full | relative
Path display format (default: relative)`}
#### context_builder
Auto-build optimal file selection for a task. Shorthand: `builder`
#### chat_send
Send message to AI chat. Shorthands: `chat`, `plan`, `review`
#### read_file
Read file contents. Shorthands: `read`, `cat`
#### file_search
Search by file path and/or content. Shorthands: `search`, `grep`
#### get_file_tree
ASCII directory tree. Shorthand: `tree`
#### get_code_structure
Get codemaps (function/type signatures). Shorthand: `structure`
#### workspace_context
Snapshot of workspace state. Shorthand: `context`
{`Parameters:
include (array): items: prompt | selection | code | files | tree | tokens
What to include (default: prompt, selection, code, tokens)
path_display (string): full | relative [default: relative]
Path display format
copy_preset (string | object)
Preset override. String: UUID, kind, or name.
Object: `}
#### prompt
Get or modify shared prompt/instructions.
{`Parameters:
op (string): get | set | append | clear | export | list_presets | select_preset
Operation (default: 'get')
text (string)
Text for set/append
path (string)
File path (required for export)
preset (string | object)
Preset to select. String: UUID, kind, or name.
Object:
copy_preset (string | object)
Override for export. String: UUID, kind, or name.
Object: `}
#### apply_edits
Apply file edits. **JSON format required** - use `call apply_edits {''}`
> **Tip:**
**Usage:** No shorthand available. Use JSON format for reliable escape handling:
'
rp-cli -e 'call apply_edits '
# From file (no @ needed for .json files)
rp-cli -c apply_edits -j edits.json
rp-cli -c apply_edits -j @edits.json
# From stdin
echo '...' | rp-cli -c apply_edits -j @-`}
**Auto-repair:** Raw newlines and tabs in JSON strings are automatically escaped,
so multiline payloads from LLMs work without manual escaping.
**Provide exactly ONE mode:**
{`Parameters:
path (string, required)
File path
# Mode 1: Rewrite entire file
rewrite (string)
Replace entire file content
on_missing (string): error | create [default: create]
Behavior when file is missing
# Mode 2: Single replacement
search (string)
Text to find
replace (string)
Replacement text
all (boolean) [default: false]
Replace all occurrences
# Mode 3: Multiple edits
edits (array)
Array of  objects
# Shared option
verbose (boolean)
Include diff preview`}
#### file_actions
Create, delete, or move files. **JSON format required** - use `call file_actions {''}`
> **Tip:**
**Usage:** No shorthand available. Use JSON format for reliable escape handling:
'
rp-cli -e 'call file_actions '
rp-cli -e 'call file_actions '
# From file (no @ needed for .json files)
rp-cli -c file_actions -j create-file.json
rp-cli -c file_actions -j @create-file.json
# From stdin
echo '...' | rp-cli -c file_actions -j @-`}
**Auto-repair:** Raw newlines and tabs in JSON strings are automatically escaped.
#### chats
List chats or view history.
#### list_models
List available AI model presets. Shorthand: `models`
#### manage_workspaces
Manage workspaces and tabs. Shorthands: `workspace`, `tabs`
> **Tip:**
**CLI vs MCP:** With CLI, connections are ephemeral—you must pass `-w` and `-t` on every invocation. With direct MCP, use `select_tab` once to bind your session to a specific tab; subsequent tool calls automatically target that tab without needing to repeat the binding.
#### list_windows
List open Repo Prompt windows. Shorthand: `windows`
#### app_settings
Read/update allowlisted RepoPrompt app-wide preferences. Part of the
`settings` tool group. See
[App Settings Tool](/docs#s=mcp-server&ss=mcp-app-settings)
(MCP) for the full registry, and
[App Settings from the CLI](/docs#s=rp-cli&ss=cli-app-settings)
for shell-focused examples.
{`Parameters:
op (string, required): list | get | set | options
Operation to perform
group (string): ui | prompt_packaging | editing | models | context_builder | mcp | code_maps
Filter for list; selector for get.
key (string)
Fully-qualified key (e.g. ui.appearance_mode). Required for set/options.
keys (array)
Multi-key selector for get. Mutually exclusive with key and group.
value (boolean | number | string | null)
Required for set. Type validated against the entry definition.
agent (string)
For options on model settings: filter candidates to one CLI backend.
limit (integer)
For options: max candidates returned (1-200, default 60).
detailed (boolean)
For options: include descriptions and model metadata per candidate.
Shell examples:
rp-cli -e 'app_settings op=list'
rp-cli -e 'app_settings op=list group=ui'
rp-cli -e 'app_settings op=get key=ui.appearance_mode'
rp-cli -e 'app_settings op=set key=ui.show_tooltips value=false'
rp-cli -e 'app_settings op=set key=ui.appearance_mode value=Dark'
rp-cli -e 'app_settings op=options key=models.planning_model agent=codexExec'
rp-cli -e 'call app_settings '
rp-cli -e 'call app_settings '
Use rp-cli -d app_settings for the full schema.
Use rp-cli tools settings --schema for the machine-readable schema.`}
#### agent_run
Session-based agent run control. **Advanced, policy-gated.**
#### agent_manage
Session and workflow management. **Advanced, policy-gated.**
### Troubleshooting
#### "command not found: rp-cli"
The CLI isn't installed or isn't on your PATH. Install from Repo Prompt's settings, then open a new terminal.
#### Connection Failures
Make sure Repo Prompt is running and the MCP Server is enabled. For scripts that start both together, use `--wait-for-server 5`.
#### Operations Need Approval
Some operations require approval in the Repo Prompt UI. If a command hangs, check the app for a dialog.
> **Tip:**
**Codex CLI Users: Sandbox Restrictions**
Codex runs in a restricted sandbox that may block the socket connection `rp-cli` needs.
**Solutions:**
- **Use MCP directly (recommended)** - Configure Repo Prompt as an MCP server in Codex rather than calling `rp-cli` through Bash.
- **Escalate sandbox permissions** - Use `sandbox_permissions: "require_escalated"` in the Bash tool invocation.
- **Run outside Codex** - Run `rp-cli` in a regular terminal and use the exported context with Codex.

# Reference

Settings and keyboard shortcuts.

## Settings Reference

Complete reference for all Repo Prompt CE settings. Open Settings with `⌘+,` or from the gear icon.
> **Tip:**
**Scripting these settings:** A subset of these preferences is also
reachable from MCP and `rp-cli` through the `app_settings` tool &mdash;
appearance, prompt packaging, edit-format defaults, preferred models, MCP auto-start,
and the global Code Maps toggle. See
[App Settings Tool](/docs#s=mcp-server&ss=mcp-app-settings) for the MCP
surface and
[App Settings from the CLI](/docs#s=rp-cli&ss=cli-app-settings) for the
shell-focused guide. The in-app UI and the `app_settings` tool share the same
underlying store for allowlisted keys; secrets, tool ACLs, and workspace-scoped settings
remain UI-only by design.
### General Settings
#### Appearance
- **Theme:** Light, Dark, or System (follows macOS)
- **Font size:** Adjust text size throughout the app
- **Syntax highlighting:** Color scheme for code blocks
#### Updates
- **Auto-update:** Enable automatic update checks
- **Update channel:** Stable or Beta releases
#### Prompt Order
- **Section ordering:** Customize the order of prompt sections (files, instructions, etc.)
- **Include datetime:** Add timestamp to prompts
#### Advanced
- **Path display:** Relative or absolute paths in prompts
- **Gitignore:** Respect .gitignore when scanning files
- **Empty folders:** Show or hide empty directories
- **URL scheme:** Enable `repoprompt://` URLs
- **Saved prompts:** Export/import your stored prompts
### API Settings
#### API Providers
Configure API keys for each provider:
- Anthropic, OpenAI, Google (Gemini)
- DeepSeek, Fireworks AI, Grok (xAI), Groq, Z.AI
- Azure OpenAI (requires base URL + key + API version)
- GitHub Models (OAuth sign-in, 8K context limit)
- Ollama/Local (URL + model selection)
#### CLI Providers
Connect external CLI tools to use existing subscriptions:
- **Claude Code:** Claude Pro/Max subscription
- **Codex CLI:** OpenAI Plus/Pro subscription
- **Gemini CLI:** Google AI subscription
Test connections and view status for each provider.
#### OpenRouter
Single API key for access to multiple providers through OpenRouter.
#### Custom API
Configure custom OpenAI-compatible endpoints:
- Base URL
- API Key (optional)
- Model name
#### Model Config
Override default model parameters:
- Temperature
- Max tokens
- Context window size
- Custom parameters
### Chat Settings
#### Chat Settings
- **Default model:** Model used for new chats
- **Auto-format:** Markdown rendering in chat
- **Code block style:** Syntax highlighting theme
#### Pro Edit (Classic Edition)
Configure delegate agent behavior:
- **Model routing:** How models are selected for tasks
- **Parallel agents:** Maximum concurrent file editors
- **Planning model:** Model used for task decomposition
### MCP Settings
#### MCP Server
Configure the Model Context Protocol server:
- **Enable/Disable:** Turn MCP server on or off
- **Connection status:** View connected clients
- **Server settings:** Port and access controls
#### Model Presets
Create and manage model presets for quick switching:
- Save current model configuration as preset
- Edit preset name and parameters
- Delete unused presets
### Workspace Settings
#### Manage Workspaces
- **Recent workspaces:** Quick access to previous projects
- **Add/remove folders:** Manage workspace roots
- **Workspace settings:** Per-workspace configurations
#### Manage Presets
Workspace-specific presets:
- Save current selection and settings as preset
- Load presets to restore context
- Export/import presets
### Prompt Presets
#### Copy Presets
Configure how prompts are formatted when copied:
- **Standard:** Clean format for any AI
- **Pro Edit:** XML format for structured changes
- **Plan:** Optimized for architectural planning
- **Custom presets:** Create your own formats
#### Chat Presets
Preset configurations for chat sessions:
- System prompt templates
- Default mode (chat/plan/edit)
- Model selection
### Benchmark
Run model comparisons:
- Select models to benchmark
- Configure test parameters
- View results and history
- Export benchmark data

## Keyboard Shortcuts

Keyboard shortcuts for faster navigation and common actions.
### General
`⌘+,`
Open Settings
`⌘+O`
Open folder/workspace
`⌘+W`
Close current tab
`⌘+Q`
Quit Repo Prompt
### Compose
`⌘+C`
Copy prompt to clipboard
`⌘+T`
New compose tab
`⌘+F`
Search files
`⌘+Shift+F`
Search file content
### Chat
`⌘+N`
Start new AI chat
`⌘+Return`
Send message
`Escape`
Stop generation
### Navigation
`⌘+1`
Switch to Compose view
`⌘+2`
Switch to Chat view
`⌘+3`
Switch to Apply view
`⌘+[`
Previous tab
`⌘+]`
Next tab
### File Selection
`Click`
Toggle file selection
`⌘+Click`
Add to selection (multi-select)
`Shift+Click`
Select range
`Right-click`
File context menu (modes, slices)
> **Tip:**
**Tip:** Most shortcuts follow standard macOS conventions. If you're familiar with other Mac apps, the same patterns work here.