llms.txt
# 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 cons
