# RepoPrompt > Community Edition documentation This file contains all documentation content in a single document following the llmstxt.org standard. ## Approvals and Paused Sessions A paused coding session can be waiting for a tool decision, an edit review, project-hook trust, or an answer to a question. Read the active card before changing permission settings or sending another task. Different cards authorize different actions; a provider's tool approval does not stand in for every RepoPrompt review. ### Tool approval An approval card shows **Needs your approval**, the requested operation, and available details such as the command or working directory. Read the proposed action and its scope. - **Approve** accepts the current request where supported. - **Decline** refuses the request and lets the runtime handle that outcome. - A session-approval option, when offered, has a broader scope than one request. - **Approve & Remember** accepts the proposed execution-policy amendment supplied with the request. Inspect that proposal before choosing it; it is not merely a second label for one-time approval. The available choices depend on the provider and request. A separate **Permission Approval** card does not offer remembered decisions through this interface. For default provider modes and the separate MCP sub-agent policy, see [Tools](https://repoprompt.com/docs/agent-mode/tools/) and [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/). ### Apply Edits Review This card shows the file path and a proposed unified diff. Read the additions and deletions before choosing **Accept**. To choose **Reject**, enter a **Rejection reason** first; rejection is disabled while that field is empty. Give an actionable reason, such as “Preserve the existing public method signature.” **⌘Return** accepts and **⌘Delete** rejects when the corresponding action is available. If the card says **No diff available**, obtain the information you need before accepting. The **Auto Edit** preference can bypass this separate edit review; it does not establish that generated changes are correct. ### Project Hooks Need Approval Codex can pause its initial turn to review repository-provided hooks. Check the **Execution directory**, hook details, and warnings. No hook is selected by default. Select the hooks you intend to trust and choose **Approve Selected & Continue**, or use **Trust All Shown** only after reviewing the full list. These choices concern project hooks, not general approval of every later tool request. Where available, **Continue Without Hooks** asks for confirmation before continuing without enabling those hooks. Strict hook mode hides this option. If discovery fails, the card offers **Retry**; inspect the displayed error and directory before retrying. ### Other reasons a session is waiting An external MCP client's **Connection Request** is separate from an agent tool approval. With **Strict connection approval** enabled, built-in and saved client-name approvals are ignored and the client must be approved for the current RepoPrompt run. Reconnects from the same running app can reuse that approval. Agents launched inside RepoPrompt do not need this external-client prompt. See [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/#connection-approval) for admission details; allowing a connection does not grant broader agent permissions. An overseer can also be waiting for a [delegation-scope approval](https://repoprompt.com/docs/overseer/#organize-sessions-with-delegated-permissions) or a batch confirmation for session administration. Review the affected sessions and proposed capabilities in that card. Scope approval is distinct from changing a provider's permission mode. A question needs an answer in its input card. A [worktree merge review or conflict](https://repoprompt.com/docs/worktrees/review-and-merge/) needs its own integration decision. An overseer can handle eligible one-time requests, but [oversight](https://repoprompt.com/docs/overseer/) does not transfer every approval: hook trust, merge reviews, session-wide grants, and secret inputs remain with you. If the session still appears paused, check the currently displayed blocker and any error after your response. Another pending decision may be shown next; repeated approval is not a general recovery procedure. --- ## Auto Effort **Auto Effort** is the gauge control above the message editor. It chooses reasoning effort before an eligible user turn while keeping the model you selected. Use it when you want effort to respond to the task rather than manually choosing a level for every message. Enable Auto Effort confirmation explaining the excerpt, model ID, effort choices, workflow category, and privacy controls Choose **Enable Auto Effort** after reviewing the disclosure. **Privacy details…** opens its settings; **Cancel** leaves it disabled. The highlighted composer label identifies the selected decision service. The screenshot shows **Auto Effort · Jev by TypeSafe**; **Decisions by OpenAI** (the OpenAI Decisions API) is also available. In [Agent Decisions settings](https://repoprompt.com/docs/settings/agent-decisions/), Auto Effort and model routing have independent decision-service selections. Composer showing both Model Router and Auto Effort service labels Configure and verify the service selected for each feature. A working execution-provider connection does not configure a decision service, and selecting a service for Model Router does not select it for Auto Effort. ### Which turns are eligible? The selected supported model must be explicit and advertise multiple effort levels. Auto Effort can apply to an eligible first launch and to follow-up messages sent after the previous turn has settled. Model aliases, default selections, and custom workflows keep manual effort. A start already handled by model routing retains the effort chosen by routing. Steering an agent while it is already working does not change effort mid-turn. Effort is held through that turn's tool calls. Auto Effort can be enabled independently of model routing. ### Understand feedback and fallback While a decision is being made, the control can show a busy state. After a service choice, its tooltip reports the chosen effort; directional feedback compares service choices or the initial selected effort. It does not prove that every intervening message used that effort. If the service cannot make a valid decision, RepoPrompt uses the manual effort. You can turn Auto Effort off and select effort directly through [Model and Effort](https://repoprompt.com/docs/agent-mode/model-and-effort/). Different effort choices can affect latency, usage, and provider caching; savings are not guaranteed. ### What the service receives For each eligible turn, the service receives a short, best-effort-masked excerpt of the message, model ID, supported effort choices, and any built-in workflow category. The workflow template body, attached files, tool output, and earlier conversation are not added. Masking can miss private information in your message. Review the service's privacy details before enabling it. For service configuration, manual fallback, and eligibility details, see [Auto effort settings](https://repoprompt.com/docs/settings/agent-decisions/#auto-effort). --- ## Computer Use **Computer Use** lets an eligible native Codex session interact with desktop applications through a supported companion. Use it for tasks that require the visible interface of another app, such as inspecting a rendered result or following a UI procedure that repository file tools cannot perform. The monitor-shaped control appears in the composer toolbar when the session is eligible. It reports **Computer Use on** or **off** for this chat, with a busy state while a change is being applied. Its presence does not mean every provider or sub-agent can use the desktop. Monitor-shaped Computer Use toggle in the session toolbar ### Prepare an eligible session Computer Use requires a top-level native Codex session with its own tab, the feature enabled, and a supported installed companion from Codex or ChatGPT. RepoPrompt reports when no companion is available. A provider connection alone is not enough to satisfy these requirements. Enable the feature in Codex's [Direct Agent permissions](https://repoprompt.com/docs/settings/agent-permissions/), then enable it locally in the intended chat using the toolbar control. The native `/computer-use` command is another entry point when supported. macOS permissions must be granted manually; enabling the feature does not silently approve operating-system access. ### Give a bounded UI task Describe the application, the starting screen, the outcome, and any limits on what the agent should change. For example: “Open the local preview, inspect the sign-in form at narrow width, and report clipping; leave account settings unchanged.” Be explicit when a task should stop before submitting, purchasing, publishing, or otherwise making an external change. Watch the session's actions and respond to requests for input or approval. Computer Use is an additional way to carry out the task; the selected [execution location](https://repoprompt.com/docs/agent-mode/execution-location/), tool permissions, and your instructions still matter. ### If the control is unavailable Check that the chat is a direct native Codex session rather than a different provider or an agent-controlled child. Check the feature setting, companion availability, and macOS permissions. Read any displayed configuration error before retrying. If the runtime reports a conflicting Computer Use integration, resolve that configuration rather than repeatedly sending the same request. For a screenshot that you simply want the agent to analyze, use [Image Support](https://repoprompt.com/docs/agent-mode/image-support/). Attaching an image provides visual input without enabling interactive desktop control. --- ## Context Builder Open the files/stack control at the right of the composer toolbar to review context. Its file count describes the selection, while the usage ring describes context consumption. Hover for the token count, percentage, and source. **Source: Live** identifies live usage information; it is not simply the sum of the selected files. **⌘P** opens the Context Composer by default. Context indicator tooltip showing live usage, token capacity, selected file count, and the Context Composer shortcut ### Selections: inspect what is included The drawer's **Selections** tab lists selected files and Code Maps separately. Filter the selection, change **Sort**, use **Add** for more context, or **Clear** to remove the selection. Each row reports size information and offers preview, copy, additional actions, and removal. Inspect large entries when you want to reduce the package or keep the agent focused. Selections tab with file filtering, sort, Add and Clear, file and Code Map counts, and per-file context sizes Selected context is useful preparation, but it is not an access-control boundary: an agent with repository tools can discover other files permitted by its tools and permissions. Use narrower instructions and the appropriate permission policy when you need to constrain work. ### Prompt: tell the receiving model what to do The **Prompt** tab contains **Receiving-model instructions** for the selected context. Use it to specify the question, scope, constraints, or expected result for the model receiving that package. This is distinct from the Context Builder's discovery task. Prompt tab and Receiving-model instructions heading The drawer can also expose prompt-packaging controls for stored prompts, the file tree, Code Maps, and Git context. Review those before copying or exporting a package; different presets can change its contents and size. For a complete manual workflow, see [Prepare and Copy Context](https://repoprompt.com/docs/agent-mode/context-composer/), including the difference between selected file context and checked Git changes. ### Context Builder: discover relevant code Choose the **Context Builder** tab. The top line identifies the discovery agent and model. **Prompts** selects additional discovery instructions. In **Task Description**, explain the task and known constraints; let the agent find the relevant code rather than preselecting the whole repository. Context Builder tab with discovery model, Prompts, Task Description, Budget, Run, and analysis follow-up controls **Budget** sets the target size for the package. The help and settings controls explain or adjust the related configuration. Choose **Run** to start discovery. The agent explores the codebase, builds a selection toward that budget, and can improve the prepared prompt according to your settings. A budget is a target for useful context, not a promise that every relevant file will fit. ### Optional analysis follow-up **Analysis follow-up → Auto** can run the selected plan, review, or question after discovery. Choose the analysis model and response type independently of the discovery model. The action button, such as **Generate Plan**, identifies the analysis you can request using the prepared context. Review the resulting selection and answer before using them for implementation. Discovery and analysis can consume separate provider usage. Configure budgets, rewriting behavior, clarification, and follow-up defaults in [Context Builder settings](https://repoprompt.com/docs/settings/context-builder/); choose the discovery runtime in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). --- ## Prepare and Copy Context Use Context Composer when you want to prepare a focused package for an external model or coding agent. It combines your receiving-model instructions with selected code and the packaging options you choose. Copying a package does not send a session message or invoke the receiving model. Open the files/stack control beside the composer or press **⌘P** with the default shortcut. The drawer has **Selections**, **Prompt**, and **Context Builder** tabs. See [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/) for automatic discovery; the steps below cover inspecting and copying the result yourself. ### Choose the code to include In **Selections**, inspect the selected files and Code Maps. Use **Add** to browse more files; the browser can add Code Maps rather than full content. Check the available per-file actions before changing representation: - **Convert to Full File** includes implementation content where that action is available. - **Convert to Codemap** keeps a compact structural representation where supported. - **Clear Slices** removes selected slice ranges; inspect the resulting selection before copying. Full files suit code the receiving model must understand in detail. Code Maps suit supporting types and API surfaces. Slices focus a large file on selected ranges. These representations affect the package, not the coding agent's filesystem permissions. ### Write receiving-model instructions Open **Prompt** and describe the question, constraints, and expected output. For example: “Review the selected authentication changes for regressions. Explain each finding using the surrounding code; do not implement fixes.” These instructions are distinct from the discovery task you give Context Builder. ### Choose packaging **Copy Preset** offers choices including **Standard**, **Plan · Architect**, **Review**, and **Manual**, along with available custom presets. A preset can change what is included; a Review preset alone does not establish which repository or changes you meant to review. Inspect **Prompts**, **File Tree**, **Code Map**, and **Git**. Manual mode uses the current packaging settings. Stored prompt selection and preset editing are covered by [Workflow Presets](https://repoprompt.com/docs/settings/workflow-presets/); section ordering is configured in [Copy Prompt Order](https://repoprompt.com/docs/settings/copy-prompt-order/). In **Git**, confirm the repository **Root** and comparison target. **None** omits Git changes, **Selected** includes checked pending changes, and **All** includes the available pending changes. File context selection and checked Git changes serve different purposes: selecting a source file is not the same as selecting its diff. ### Copy and check the package Choose **Copy Prompt**, then paste into a draft where you can inspect it before submitting. Confirm the instructions, file paths, relevant implementation, and intended Git changes. Reduce irrelevant full files or use narrower context if the receiving model cannot accept the package. The session's live context-usage ring describes runtime usage; it is not simply the size of this exported package. Copying context does not transfer a running conversation's entire history, provider permissions, or tool configuration. If the clipboard action reports **Copy failed**, retry after resolving the error rather than assuming the previous clipboard contents are the new package. --- ## Execution Location The execution-location control sits at the left of the toolbar above the message editor. It usually begins as **Work locally**. This is the filesystem location where the session's agent works, including its repository reads, edits, and shell commands within the applicable permissions. ### Choose where to start Open the control to see **Start in**. Select a location before sending the first message: | Choice | Use it for | | --- | --- | | **Workspace checkout** | Work directly in the checkout already open in the workspace. Edits appear alongside your existing local work. | | **New worktree** | Give the task a separate Git checkout, useful for parallel implementation or an alternative approach. | | **Existing worktrees** | Continue in an already-created checkout. Read the branch, worktree name, and path before choosing. | Start in menu with Workspace checkout selected, New worktree, and an empty Existing worktrees list The screenshot's **No other worktrees available** is an empty state. When worktrees are available, the list identifies them by branch or detached commit and directory. Unusable, prunable entries cannot be selected. A worktree requires a suitable Git repository; a plain folder does not acquire Git isolation merely because you choose a workflow. Your initial worktree selection is prepared when you first send. Check the location indicator and any creation error before assuming the task has started in a new directory. For repository setup and local file copying, see [Worktrees](https://repoprompt.com/docs/worktrees/). ### Keep parallel tasks from colliding Two sessions in **Workspace checkout** can edit the same files. Their conversation histories are separate, but their working directory is shared. Use different worktrees for tasks that may touch overlapping files, then review and integrate their changes deliberately. A worktree separates repository files; it does not change the provider's permissions or automatically isolate databases, remote services, or other resources the agent can access. Configure [Tools and permissions](https://repoprompt.com/docs/agent-mode/tools/) for the intended task. ### Change an existing session's location After a session starts, the menu is labeled **Execution location** and the toolbar can show its bound checkout. Changing it restarts the agent's provider context. If a run is active, RepoPrompt asks you to confirm stopping it; the in-flight request is not replayed automatically. An idle session can also lose some conversational continuity when its provider context restarts. Finish or stop the current task, review its changes, and decide which checkout should receive the next message. Read the confirmation before proceeding. Switching the visible workspace tab is not a substitute for changing a session's execution binding. Once the location is correct, select a [Workflow Template](https://repoprompt.com/docs/agent-mode/workflow-templates/) and describe the task. For a complete worktree task, follow [Create and Use a Worktree](https://repoprompt.com/docs/worktrees/create-and-use/), then [Review and Merge](https://repoprompt.com/docs/worktrees/review-and-merge/). Changing this location does not merge changes between checkouts. --- ## Image Support Images give an agent visual evidence that is difficult to express in text: a clipped panel, a design mockup, an error dialog, or the exact arrangement you want to reproduce. Include a short explanation of what the agent should notice and what outcome you want. ### Add images to the next message Click the attachment button near Send to open **Choose Files**, then select one or more images. You can also paste an image from the clipboard or drag image files into the message editor. RepoPrompt prepares supported image input and shows attachments above the editor. Image attachment button beside the message editor Review the attachment previews before sending. Remove an image with its attachment removal control if it belongs to another task or contains information you do not intend to share. Attachments are staged for the next turn; they are not sent merely because you select or paste them. The available attachment actions depend on the current session and submission state. If an action is disabled during a pending submission or rewrite, finish or cancel that step before changing its attachments. Image support also depends on the provider and selected model; read a reported compatibility or input error rather than assuming every connected model accepts the same formats. ### Include other files when useful The file picker also accepts files beyond images. Acceptance and delivery depend on the connection and file type; choosing a file does not make every provider able to read it. Keep the task text explicit about what each attachment contributes, and inspect any unsupported-file or size-limit message before resubmitting. For a separate Oracle consultation, images, UTF-8 text files, and PDFs on supported routes can be supplied through [Oracle attachments](https://repoprompt.com/docs/agent-mode/oracle/#attach-files-to-an-oracle-consultation). Oracle has its own attachment validation and does not automatically receive everything attached to the coding session. ### Explain how to use the image A useful message identifies the relevant part and the requested change: “The Save button is clipped at the bottom of this screenshot. Fix the layout while keeping the form keyboard-accessible.” If you attach several images, describe their relationship, such as current behavior versus intended design. Images can show text, code, and instructions that belong to the material being analyzed. State your task in the message and identify which visual details matter. For documentation work, explain whether a screenshot is the current interface or an example from an older build. ### Images, selected files, and desktop interaction An image attachment is visual input for the message's execution provider. It is separate from the repository file selection in [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/). Selecting source files helps the agent connect the visual issue to implementation, but attaching a screenshot does not select those source files automatically. Re-prompt and automatic routing have narrower inputs: image attachments are not automatically forwarded as visual input to their draft-rewriting or decision requests. The execution provider receives the supported attachments with the submitted task. Review the image for private information before sending. To let an eligible session interact with desktop applications rather than analyze a static image, see [Computer Use](https://repoprompt.com/docs/agent-mode/computer-use/). --- ## Interviewer The **Interview** control is the question-bubble icon above the editor. Turn it on when your initial request needs a few decisions resolved before the agent starts. It is useful when you know the outcome you want but have not decided the scope, preferred approach, or tradeoffs. Interview control tooltip showing Interview off and Work begins immediately ### Enable before the first task Write your request, turn **Interview** on, and send. The control's tooltip distinguishes **Interview on: Asks questions before starting** from **Interview off: Work begins immediately**. When enabled for the first task, RepoPrompt asks the agent to interview you before beginning substantive work. The interview instructions call for one question at a time, normally with two to four concrete answer choices. The agent should adapt each question to your previous answer, ask one to three questions in total, and stop sooner when the task is clear. It should then summarize what it learned and proceed. Use the question card to select an answer or supply your own explanation. Give answers about the intended result and constraints: for example, whether a change should affect one screen or the entire application, or whether you want a proposal before implementation. ### Understand the scope Interview is a first-task instruction, consumed when used; it is not a requirement to interview you on every follow-up. Turning it on after the conversation already contains an assistant response does not retroactively restart the opening interview. You can always ask a follow-up such as “Before continuing, clarify the remaining decisions with me.” Interview guides model behavior, so the exact questions depend on the provider and task. It does not change the session's tool permissions or promise that the agent will pause before every later action. Approval requests remain governed by [Tools and permissions](https://repoprompt.com/docs/agent-mode/tools/). ### Combine it with a workflow Choose the [execution location](https://repoprompt.com/docs/agent-mode/execution-location/), then a [Workflow Template](https://repoprompt.com/docs/agent-mode/workflow-templates/), and enable Interview if you want a short clarification step before that method begins. **Deep Plan** also has its own instructions for establishing how involved you want to be. Choose the combination that matches your task rather than assuming every template needs an interview. [Re-Prompter](https://repoprompt.com/docs/agent-mode/re-prompter/) serves a different stage: it helps rewrite the draft in your editor before the execution agent receives it. --- ## Message Editor The message editor is the **Send a message…** field at the bottom of a session. It combines the request you write with the workflow, context, model, and permissions selected around it. Check these surrounding controls before sending, especially when you have switched sessions. Agent Mode composer showing the message field and its toolbar and submission controls ### Write the outcome and constraints Describe the result you need, the relevant behavior, and how you will judge success. Include known files or components as starting points without assuming you must select every file the agent will need. Agents can search the repository and use [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/) to discover relevant code. For example: “Fix the session list so renaming a chat preserves its selection. Keep keyboard navigation working and explain the affected behavior.” Add scope limits, compatibility requirements, or review expectations in the message. A [Workflow Template](https://repoprompt.com/docs/agent-mode/workflow-templates/) supplies the approach around that task; it does not supply missing product requirements. ### Stage the message Choose the [execution location](https://repoprompt.com/docs/agent-mode/execution-location/), then select a workflow card or the **Workflow** selector if needed. Use the file/context control to inspect selected files and receiving-model instructions. File mentions can add explicit file attachments when enabled; review the attachment strip rather than assuming a typed path was attached. The attachment button opens **Choose Files**. Select files, drop them into the editor, or paste supported clipboard content. Review the attachment strip and remove anything that should not accompany the next turn. Attachments are separate from repository selection: typing a path is not the same as attaching the file. Delivery depends on the selected provider and file type. Supported images are visual input; supported text files can supply their contents to the request. An unsupported file or a request that exceeds a limit produces an error instead of silently omitting the file. See [Image Support](https://repoprompt.com/docs/agent-mode/image-support/) and [Providers & Models](https://repoprompt.com/docs/providers/overview/) for related capabilities. Re-prompting does not inspect attachment contents. ### Submit and follow up **Return** or the paper-plane button submits the message in the normal composer state. Use **Shift+Return** for a line break. With [Re-prompt](https://repoprompt.com/docs/agent-mode/re-prompter/) enabled, the first Send can instead rewrite the draft for review; inspect the visible state before sending again. A follow-up sent to a running session can steer its work. It is different from starting a fresh session, and it does not necessarily interrupt a tool action at the exact moment you type. For a question or approval already waiting in the transcript, use that interaction's response controls so the answer reaches the right pending request. ### Work from the keyboard Use **Command+L** to focus the composer and **Command+.** to stop the current run. These actions target the current session. Return sends and Shift+Return inserts a line break in the normal editing state; [Re-prompt](https://repoprompt.com/docs/agent-mode/re-prompter/) can change what the first Send does. Command and composer shortcuts can be remapped in [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/). The bindings shown here are defaults; check your saved bindings if a shortcut behaves differently. ### Review the conversation Replies and tool cards appear above the editor. Expand a card for arguments, results, or a diff. Provider permissions and the **Auto Edit** setting determine whether a file change is applied automatically or needs a decision. Use the session's stop/cancel control when you intend to stop active work; an unsent draft does not stop the agent. Use [Session History](https://repoprompt.com/docs/agent-mode/session-history/) to return to earlier conversations or [Overseer](https://repoprompt.com/docs/agent-mode/overseer/) when coordinating several active sessions. --- ## Model and Effort The model selector below the editor chooses the provider and model for the session's work. The adjacent menu selects an available reasoning effort. This guide explains those controls; the shared [Models reference](https://repoprompt.com/docs/providers/models/) owns model availability, identifiers, aliases, effort, and service-tier concepts. Composer model and effort controls with a selected Codex model and Medium effort ### Select a connected model Open the provider/model menu and choose an available entry. Models come from connected runtimes and configured compatible backends, so the list can differ between installations. Connect a missing provider through [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/). The [Providers guide](https://repoprompt.com/docs/providers/overview/) compares the supported integrations in a compact format. An explicit selection establishes the intended provider and model. Read locks and disabled-state explanations when a choice cannot be changed: controls can be locked while an agent controls the session, and some provider settings are locked during an active run. A provider or backend change can require a fresh provider context, so review any restart behavior before switching during a task. ### Choose effort and speed deliberately Open the effort menu and select one of the choices returned for this model. Some connections display provider-specific parameter controls or omit effort when it is not available. See [Reasoning effort](https://repoprompt.com/docs/providers/models/#reasoning-effort) for the meaning of those choices. When a speed or Fast option is available, inspect its selected state separately from effort. [Speed and service tiers](https://repoprompt.com/docs/providers/models/#speed-and-service-tiers) explains the capability and billing distinctions. ### How automatic decisions interact With model routing enabled through [Agent Decisions](https://repoprompt.com/docs/agent-mode/model-router/) for a new session, the composer can replace the ordinary picker with the routing-service label. Model routing chooses the model and initial effort for that task. Existing sessions retain their established targets. [Auto Effort](https://repoprompt.com/docs/agent-mode/auto-effort/) keeps an explicitly selected supported model and chooses effort before eligible turns. It does not change effort between tool calls in an active turn. If automatic decisions are unavailable, the manual selection or applicable default is used. Other features have their own model controls. See [Model roles](https://repoprompt.com/docs/providers/models/#model-roles) and the corresponding [Re-prompt](https://repoprompt.com/docs/agent-mode/re-prompter/), [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/), and [Oracle](https://repoprompt.com/docs/agent-mode/oracle/) guides. --- ## Agent Decisions **Agent Decisions** brings together automatic model routing, Auto Effort, local Usage Balancing, and decision-service configuration. Open [Settings → Agent Mode → Agent Decisions](https://repoprompt.com/docs/settings/agent-decisions/) to configure these features. For a new task, use the branching-arrow routing control above the message editor to let RepoPrompt choose an execution model and initial reasoning effort. Routing uses your connected providers, decision settings, and task description. [Auto Effort](https://repoprompt.com/docs/agent-mode/auto-effort/) separately chooses effort for eligible turns while keeping the selected model. Composer with Model Router enabled and a Jev by TypeSafe routing label in place of the ordinary model selection ### Read the composer state An enabled control is highlighted, and the composer can show **Model Router · [service]** where the ordinary model choice would appear. The screenshot shows the routing control’s **Model Router** label. The pictured service is **Jev by TypeSafe**, but **Decisions by OpenAI** (the OpenAI Decisions API) is also available. Select either service in Agent Decisions settings. Click the service label to open Agent Decisions settings. If the service is unavailable, the control directs you to configuration. Configure and verify the decision service and connect an eligible execution provider before enabling routing. The decision service chooses among execution models; it is not itself the coding agent that edits your repository. Available candidates depend on provider connections, model support, and routing configuration. ### New tasks and existing sessions The model-routing switch is global and stays enabled across sessions until you turn it off. It applies to new primary sessions and eligible RepoPrompt-managed sub-agents. It does not replace an established session's model on every follow-up. Explicit model pins in agent launches remain respected. If routing fails or yields no valid choice, the task continues with the current selection or applicable role default. Local usage balancing can adjust a recommendation to a comparable eligible model. Paid Fast variants require separate eligibility settings; the router does not make those costs disappear. ### Balance usage across connected plans The new-task defaults and routing candidates favor capable models for the requested work. Inspect the effective defaults in [Agent Models](https://repoprompt.com/docs/settings/agent-models/), and use [Providers & Models](https://repoprompt.com/docs/providers/overview/) for model availability. Optional **Usage Balancing** compares connected plans' remaining allowance and reset times locally. Choose **Only near limits**, **Even pace**, or **Use expiring quota first** according to how you want to use those plans. Connect the usage sources through **Manage plan usage…**; a working coding connection alone does not establish usage readings. Balancing can substitute a comparable eligible model for a new task, including after a router recommendation. **Override Model Router when usage is critical** is a separate opt-in that can narrow the provider choices when allowance is near its limit or would otherwise expire. Established sessions and explicit MCP model pins keep their targets. See [Usage balancing settings](https://repoprompt.com/docs/settings/agent-decisions/#usage-balancing) for thresholds and refresh behavior. ### Review information sent for a decision Routing sends a short task excerpt, custom routing guidance, role references, and descriptions of candidate models and effort levels to the selected service. RepoPrompt attempts to mask sensitive text, but masking is best effort. Attached files, repository context, chat history, tool results, and execution-provider credentials are not automatically included. Sensitive information typed directly into the task or guidance can still be shared. The full task is then sent to the chosen execution agent. Review service privacy details and disable routing for tasks you do not want excerpted to that service. See [Agent Decisions settings](https://repoprompt.com/docs/settings/agent-decisions/) for service verification, available models, usage balancing, Fast-tier eligibility, and guidance. [Auto Effort](https://repoprompt.com/docs/agent-mode/auto-effort/) makes a narrower decision for eligible turns on a model you selected. ### Choose a decision service Use the [Decisions by OpenAI and Jev comparison](https://repoprompt.com/docs/settings/agent-decisions/#choosing-decisions-by-openai-or-jev) to compare account setup, verification, data handling, and the capabilities RepoPrompt actually uses. Choose routing and Auto Effort services independently; evaluate them on representative tasks rather than assuming one is universally faster, cheaper, or more accurate. --- ## Oracle **Oracle** is the brain-shaped control above the message editor. It opens Oracle conversations associated with the current context so you can inspect the reasoning model's questions, plans, reviews, and answers. Use Oracle when the executing agent would benefit from a second perspective or a model with different strengths. For an introduction to its role and when to use it, read [What Is an Oracle?](https://repoprompt.com/docs/faq/what-is-an-oracle/). ### Execution agent and Oracle The execution agent continues to own the coding task: it searches, edits, runs tools, and responds to your instructions. Oracle is a consultation that receives its prepared context and returns analysis. Consulting Oracle does not automatically replace the model shown below the message editor or apply its suggested changes. Choose the primary Oracle and up to four additional Oracles in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). A grouped request runs those models independently and keeps their results separate in roster order. The control can display **Oracles · 2**, for example, when multiple Oracles are configured or represented in the current grouped consultation. A displayed count is not a count of coding agents editing your files. Composer toolbar showing Oracle access beside the selected-context control ### Open and review consultations Click **Oracle** to inspect the relevant conversation. Oracle consultations can be created by a workflow, a direct agent request, or a Context Builder analysis follow-up. The popover favors conversations associated with the current agent session so results remain connected to the task you are viewing. Read each model's result when a consultation has several lanes. They can disagree or focus on different risks. Bring the useful conclusions back into the coding task with a clear follow-up rather than assuming every suggestion should be implemented. Where offered, **Copy All** collects a grouped consultation's results for reuse. ### Attach files to an Oracle consultation App-backed `oracle_send` and `ask_oracle` can receive an `attachments` array. Each entry names a local file through an absolute `path`, with an optional `title`. Supported types are PNG, JPEG, GIF, WebP, UTF-8 text, and PDFs where the selected route supports native documents. Images are sent as images, text is inlined, and unsupported files are refused with a reason. The file must be inside a currently loaded workspace root or be the exact file attached by the user to the current agent session. An agent can forward a pasted or dropped attachment during that turn using the path supplied with the user message. Remote URLs, relative paths, another session's attachments, and arbitrary files outside the loaded roots are not accepted. The direct headless backend does not support these attachments. Attachments apply to that Oracle turn. A continuation does not automatically resend earlier originals or transcript thumbnails. Grouped consultations send the originals to each Oracle, which increases total usage across the group; attachments are additional to text-context estimates. See the [tool reference](https://repoprompt.com/docs/mcp-server/mcp-tools/#oracle_send) for the request format. ### Read grouped results A grouped consultation returns a group identity and separate results for its Oracle lanes. Check each lane's status and answer, including any failure or cancellation. A useful answer from one lane does not mean every lane succeeded. Retain the returned conversation IDs to inspect or continue the relevant consultation rather than repeating the entire group blindly. Treat Oracle guidance as input to the coding agent's decision. Compare disagreements against the task and repository evidence, then tell the execution agent which changes to pursue. Export failures are reported separately from the consultation results, so a failed export does not by itself mean all model answers were lost. ### Supply useful context Oracle's answer depends on the context assembled for the consultation. Check selected files, relevant Code Maps, instructions, and any requested Git diff. For a review, identify which changes should be inspected; for a plan, state constraints and the intended outcome. [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/) can discover files first and then generate a plan, review, or answer using Oracle. Its discovery model is configured separately from the Oracle roster. External clients can use exposed [Oracle Model Presets](https://repoprompt.com/docs/settings/model-presets/) to select named consultation configurations. For tool-level send, continuation, model-selection, and export behavior, see [Oracle tools](https://repoprompt.com/docs/mcp-server/mcp-tools/#oracle--model-tools). --- ## Overseer The oversight control sits between **Workflow** and **Interview** above the message editor. Open it to manage the current session's relationships with other Agent sessions, including sessions in other RepoPrompt windows. The screenshot shows the control's earlier branching-symbol appearance; newer builds use oversight role marks and counts. Overseer popover with Enable overseer mode and a Session ID field for linking an existing session ### Start with a loaded session Send a first message so the session exists and is loaded. A blank composer can display **Send a first message to start this session, then add sessions to oversee**. Overseer activation requires an eligible, user-owned top-level Agent session. When the session is unavailable or ineligible, the popover explains why its controls are disabled. **Enable overseer mode** lets the session create managed lanes without first linking an existing conversation. Enabling it grants no access to unrelated sessions. The activation applies to this session until it is rebound, changes ownership, or the app restarts. ### Add an existing session Copy the target's session ID from its sidebar controls, enter it under **Oversee a session**, or choose **Paste from Clipboard**. Check the preview and choose **Oversee session**. The confirmation explains what the overseer will be allowed to read and control. Choose **Retry** if a session has just become available and the candidate information needs refreshing. This relationship can allow the overseer to read status and conversations, send instructions, steer or stop work, answer questions and applicable one-time approval requests, compact context, and receive updates. Treat the confirmation as a delegation decision. ### Organize and delegate Beyond a single link, an overseer can request a scope for organizing sessions, controlling work, creating nested coordinators, or managing worktrees on behalf of member sessions. Review the proposed coverage and permissions before granting it. A scope and a link serve different purposes; linking one session does not give access to every session in its workspace. See [delegated permissions](https://repoprompt.com/docs/overseer/#organize-sessions-with-delegated-permissions) for the available capabilities, nested-scope limits, and actions that remain with you. ### Read and manage relationships The popover lists sessions this agent oversees and sessions overseeing it. Role marks and counts help distinguish the two directions. Open a linked session to inspect its work; **Unlink** removes the relationship without deleting the conversation. Automatic wake controls decide when updates can start follow-up work and therefore affect model usage. For the full feature, continue with [Overseer Mode Overview](https://repoprompt.com/docs/overseer/), [Lanes](https://repoprompt.com/docs/overseer/lanes/), [Linking Sessions](https://repoprompt.com/docs/overseer/linking-sessions/), and [Best Practices](https://repoprompt.com/docs/overseer/best-practices/). --- ## Agent Mode Overview Agent Mode is RepoPrompt's interface for conversations with coding agents. This page identifies the main areas and controls. For your first task, follow [Getting Started](https://repoprompt.com/docs/overview/getting-started/); for workflow choices and best practices, read [Going Deeper](https://repoprompt.com/docs/overview/going-deeper/). ### Welcome screen A new session shows **What are we building?** and workflow cards. The arrows and page dots reveal more cards. The **Workflow** selector above the message editor opens the same catalog, including your custom templates. Selecting a workflow prepares instructions for the next message; it does not start work. Welcome screen with Orchestrate, Review, Deep Plan, and ChatGPT Export workflow cards See [Workflow Templates](https://repoprompt.com/docs/agent-mode/workflow-templates/) for what each choice does and how to configure the catalog. ### Message composer The **Send a message…** field is where you write the next request or follow-up. Its surrounding controls show the session's execution location, selected workflow, model, effort, and available capabilities. Message composer with execution location, workflow, context, model, effort, tools, and permission controls | Control | What it shows or opens | | --- | --- | | **Work locally / Execution location** | The workspace checkout or worktree where the agent works. See [Execution Location](https://repoprompt.com/docs/agent-mode/execution-location/). | | **Workflow** | Instructions selected for the next message. See [Workflow Templates](https://repoprompt.com/docs/agent-mode/workflow-templates/). | | Provider/model and effort menus | The execution model and available reasoning settings. See [Model and Effort](https://repoprompt.com/docs/agent-mode/model-and-effort/). | | **Tools** and **Permissions** | Provider capabilities and approval behavior. See [Tools](https://repoprompt.com/docs/agent-mode/tools/). | | Attachment button | Files staged for the next message. See [Image Support](https://repoprompt.com/docs/agent-mode/image-support/). | | Send / Stop | Submit a message or stop active work. See [Message Editor](https://repoprompt.com/docs/agent-mode/message-editor/). | Additional controls include [Interviewer](https://repoprompt.com/docs/agent-mode/interviewer/), [Re-prompt](https://repoprompt.com/docs/agent-mode/re-prompter/), [Agent Decisions](https://repoprompt.com/docs/agent-mode/model-router/), [Auto Effort](https://repoprompt.com/docs/agent-mode/auto-effort/), [Computer Use](https://repoprompt.com/docs/agent-mode/computer-use/), and [Overseer](https://repoprompt.com/docs/agent-mode/overseer/). Availability and enabled states depend on the session and connected provider. Hover over a control for its label or status. ### Conversation and review cards The conversation above the composer contains your messages, agent responses, and tool activity. Expand a tool card to inspect its arguments, output, or proposed diff. Questions, tool approvals, edit reviews, and project-hook decisions appear as separate cards when the session needs input. Use the controls on the active card to respond. The composer is for messages and steering; it does not replace a pending approval or question card. See [Approvals and Paused Sessions](https://repoprompt.com/docs/agent-mode/approvals/) for the different requests. ### Context drawer and Oracle The file/context control beside **Oracle** shows selected-file and context-usage information. It opens the Context Composer drawer, which contains **Selections**, **Prompt**, and **Context Builder** tabs. The **Oracle** control opens the related consultation conversations. See [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/) for the drawer's controls, [Prepare and Copy Context](https://repoprompt.com/docs/agent-mode/context-composer/) for manual packaging, and [Oracle](https://repoprompt.com/docs/agent-mode/oracle/) for consultations and grouped results. ### Session sidebar and navigation The session sidebar lists conversations in the workspace. Select a session to open its transcript; its status and attention indicators help you locate ongoing work or requests for input. Session actions let you organize and return to conversations without treating them as one shared chat. Use **Command+K** for the session switcher in the focused window and **Shift+Command+K** to search across sessions. These are configurable defaults. [Session History](https://repoprompt.com/docs/agent-mode/session-history/) covers navigation and recovery, and [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/) lists the bindings. --- ## Re-Prompter **Re-prompt** is the wand control above the message editor. It asks a separate model to improve your draft before you send it to the session's execution agent. Use it to make a rough request clearer, organize constraints, or turn an informal description into a more useful task brief. Enable Re-prompt confirmation describing shared information, provider billing, review behavior, and keyboard controls ### Rewrite, review, then send Enable Re-prompt and read its first-use disclosure. Write the request and press **Return** or click **Send**. In the normal review mode, this first action rewrites the text in the composer. Review and edit the visible draft, then press Return or Send again to submit it. You remain in control of the draft. Typing stops an in-progress rewrite. **Escape** restores the original for your next Send. By default, **⌘Return** asks for another rewrite, and **⌘⇧O** sends the original immediately. You can remap the two composer commands in [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/). Use these controls according to the current composer state rather than repeatedly pressing Send while a rewrite is still arriving. The rewriter can offer an optional clarification question. Answering can produce another revision. You can also continue with the visible draft without answering. This clarification happens before submission; [Interviewer](https://repoprompt.com/docs/agent-mode/interviewer/) asks the execution agent to clarify the task after submission. ### Choose a model and mode Open the control's context menu to select an available Re-prompt model, restore its automatic default, change **Mode**, or toggle **Include recent chat context**. **Agent Models Settings** opens the related configuration. If no usable model is connected, the control offers **Choose model** instead of silently selecting an unavailable provider. **Send automatically** mode dispatches completed rewrites unless a clarification question or slash-leading text needs review. Use review mode when you want to inspect every rewritten request. Your Re-prompt model is separate from the model that ultimately performs the task. #### Set rewrite guidance Open **Agent Models Settings** from the Re-prompt control, then expand **Rewrite guidance (advanced)** in the Re-prompt configuration. Describe how the rewriter should prepare your requests—for example, preserve acceptance criteria, keep file paths unchanged, or separate required changes from open questions. Choose **Save** to apply the draft settings; **Restore Default** restores the built-in guidance to the draft. Guidance changes how the draft is prepared; it does not grant the execution agent extra permissions. Review the rewritten text and any clarification before sending, especially when the request contains strict scope limits. See [Re-prompt settings](https://repoprompt.com/docs/settings/agent-models/#re-prompt) for model and context options. ### Know what is shared The rewriting provider receives your message, rewriting guidance, workspace root names and selected paths, and recent chat excerpts when enabled. File contents, attachments, Git output, and tool results are not included in that rewriting request. The screenshot's model name is an example; provider billing and retention apply to the configured route. Paths, names, excerpts, and anything you type can still be sensitive. Read the disclosure when changing providers. If model routing or [Auto Effort](https://repoprompt.com/docs/agent-mode/auto-effort/) is enabled through [Agent Decisions](https://repoprompt.com/docs/agent-mode/model-router/), the resulting task can also be evaluated by its configured decision service before the execution agent starts. --- ## Session History Session history lets you return to a task with its conversation and tool activity intact. Use it to find a previous investigation, continue an implementation, or compare what several agents found. A session's history describes its work; the files on disk can have changed since the last message. ### Find a conversation Open the Agent sessions sidebar to browse sessions in the current workspace. Rows identify the conversation and its activity; parent and child sessions can be grouped together. Select a row to open its transcript. RepoPrompt may show **Restoring conversation…** while it loads saved content. If restoration fails, use the displayed **Retry** action rather than starting a replacement task without checking the original. The **Agent Session Switcher** jumps among sessions in the focused window. **Search all Agent sessions** searches active or recent conversations across windows. Their default shortcuts are **⌘K** and **⇧⌘K**; the sessions sidebar defaults to **⌥⌘B**. All are configurable in [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/). Give long-running conversations descriptive names using **Rename chat**. A name such as “Checkout cancellation review” is easier to recognize than a generic request. Oversight marks and their tooltips identify sessions that oversee others or are overseen; they do not replace the run status. ### Move between active and stashed work Use **Shift+Command+A** to cycle through sessions in the current window with unseen completed, failed, or waiting badges. Open the selected conversation to determine whether it needs an answer, approval, or result review; the badge alone does not establish success. **Command+W** stashes a session tab. **Shift+Command+T** reopens the most recently stashed session. Stashing preserves the conversation and is separate from archiving or deleting saved history. These commands and the current-session actions can be remapped in [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/). ### Resume and inspect the work Select the session, read its latest result, and check its [execution location](https://repoprompt.com/docs/agent-mode/execution-location/) before sending a follow-up. The provider, model, permissions, and worktree can differ from the session you last viewed. A stopped or completed task does not automatically resume merely because you open its transcript. Expand tool cards to inspect file reads, searches, command results, edits, or Oracle consultations. This is useful when a result refers to a file or decision you want to verify. Some saved history loads in bounded portions; use **Show more** where offered. For a fresh provider context or another agent, use **Handoff** where available. Review the destination provider and model and the prepared handoff context. A handoff is a way to carry useful task information forward; it does not make every detail of a long conversation fit into the destination's context window. ### Archive and delete deliberately Archive conversations you want out of the active list while retaining their saved history. The **Archived Sessions** section lets you revisit archived work. Read bulk-action counts before confirming an operation. **Clear archived sessions** and **Delete chats** permanently remove saved conversations and can also remove related sub-agent chats, as stated in the confirmation. To disconnect coordination without deleting a conversation, use **Unlink** in [Overseer controls](https://repoprompt.com/docs/overseer/linking-sessions/). To find older work through an agent, the read-only [history tool](https://repoprompt.com/docs/mcp-server/mcp-tools/#history) can search saved sessions across workspaces. --- ## Skills & Slash Commands Skills are discoverable instruction files or packages. A skill can contain workflow instructions, but the words are not interchangeable: the workflow describes a process, while the skill is how a compatible host discovers and loads its instructions. RepoPrompt also has in-app workflow templates selected through the **Workflow** control. ### What Are Skills? RepoPrompt's slash-skill loader reads Markdown instruction files with optional YAML frontmatter, including folder-based `SKILL.md` files and supported legacy command files. In Agent Mode, invoking one expands its template with your task description. External coding hosts have their own discovery and invocation behavior. ### Skills in Agent Mode Agent Mode discovers skills from on-disk directories and presents them in the input bar. Type `/` at the start of your message to see available skills — they filter as you type by name and description. When you send a message with a slash skill, RepoPrompt expands the template (stripping frontmatter and substituting `$ARGUMENTS` with your task description) before sending it to the agent. **Skills vs. workflow templates** Agent Mode has two ways to load instructions for a task: the **Workflow** dropdown selects built-in or custom workflow templates, while a **slash skill** loads an on-disk instruction file typed as `/skill-name`. You can use one or the other per message, but not both. A custom in-app workflow template is not automatically an installed skill for an external coding host. ### Use skills with external agents An external coding host controls which skill locations it discovers and how skills are invoked. Connecting to RepoPrompt's MCP server provides tools but does not install skills. For supplied commands such as `/rp-build` and `/rp-review`, use [MCP Workflow Commands](https://repoprompt.com/docs/mcp-server/workflow-commands/) for installation, destinations, and MCP versus CLI variants. ### Creating Custom Skills Custom skills are Markdown files placed in specific directories. RepoPrompt automatically discovers them and makes them available — in Agent Mode and in compatible external hosts that scan those directories. #### Skill File Format Each skill file starts with optional YAML frontmatter followed by the prompt template: ```markdown --- name: my-workflow description: My custom workflow for specific tasks --- # My Custom Workflow Task: $ARGUMENTS Your detailed instructions here. The agent will follow these instructions when the skill is invoked. ## Steps 1. First, do this... 2. Then do that... ``` The `$ARGUMENTS` placeholder is replaced with whatever the user types after the slash command. #### Folder-Based Skills (Recommended) Create a folder for each skill containing a `SKILL.md` file: ```text .claude/skills/ my-skill/ SKILL.md ← skill definition deploy-workflow/ SKILL.md ← another skill ``` The folder name becomes the default command name (overridden by the `name` field in frontmatter if present). #### Flat File Skills You can also place individual `.md` files directly in a commands directory: ```text .claude/commands/ review.md ← becomes /review deploy.md ← becomes /deploy ``` ### Skill Search Locations RepoPrompt scans provider-specific directories in order of priority. Project-level skills take precedence over global ones: #### For Claude Code 1. `/.claude/skills/` — Project-level folder-based skills 2. `/.claude/commands/` — Project-level flat file skills 3. `~/.claude/skills/` — Global folder-based skills 4. `~/.claude/commands/` — Global flat file skills #### For Codex CLI 1. `/.agents/skills/` — Project-level folder-based skills 2. `/.agents/slash/` — Project-level flat file skills 3. `~/.agents/skills/` — Global folder-based skills 4. `~/.agents/slash/` — Global flat file skills If two skills have the same name, the one found first (higher priority location) wins. Agent Mode watches these directories for changes, so newly created or modified skills appear automatically. ### Installing Built-in Skills RepoPrompt can install its built-in workflow skills into the appropriate directories for your terminal agents. You can do this from: - **Onboarding wizard** — During initial setup, the MCP Setup step includes a "Skills" install button - **MCP Settings** — The settings panel has options to install skills for different providers The installer offers **MCP skills** for instructions that call native MCP tools and **rpce-cli skills** for instructions that use the terminal command. The CLI label can reflect the running build's command name. These are alternate instruction variants, not separate tool permissions or automatic installation of the CLI executable. :::tip **Tip:** Global skills (`~/.claude/skills/` or `~/.agents/skills/`) are available across all your projects. Project-level skills let you create workflows specific to a particular codebase. Skills work in both Agent Mode and with terminal agents. ::: --- ## Tools The **Tools** menu below the editor controls capabilities offered to the selected execution provider. It is useful when you want to constrain shell access, adjust provider features, or decide which configured MCP servers the session may use. The available switches depend on the provider. Codex Tools popover showing Bash, Search, Goals, Reasoning Summaries, Local Memories, and required RepoPromptCE MCP access ### Codex controls in the screenshot | Control | Effect | | --- | --- | | **Bash** | Permits Codex shell commands under the selected permission level. | | **Search** | Permits Codex's built-in search capability. RepoPrompt's own repository tools have separate MCP availability controls. | | **Goals** | Enables Codex goal support for continuing tasks. | | **Reasoning Summaries** | Controls whether Codex supplies reasoning summaries in Agent Mode; it does not select reasoning effort. | | **Local Memories** | Allows Codex to generate and reuse local memories across chats. Background or startup generation can consume quota; a new or restarted session may be needed. | | **MCP Servers** | Enables individual servers from RepoPrompt's isolated Codex configuration. **RepoPromptCE** is required and cannot be disabled here. | Tool settings are locked during an active Codex run. If a setting is unavailable, wait for the turn to finish or stop it deliberately before changing the configuration. Other providers expose different controls; [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/) describes their runtime options. ### Choose permission behavior Open **Permissions** beside Tools to inspect the current provider's approval mode. For Codex, the pictured choices are **Read Only**, **Default**, **Auto Review**, and **Full Access**. Auto Review evaluates tool requests automatically before asking you. Full Access removes the normal provider sandbox restriction and per-request tool approval prompts; separate RepoPrompt edit reviews, hook-trust decisions, and worktree merge reviews can still apply. Permissions popover with Codex sandbox levels and the separate Auto Edit switch **Auto Edit** applies file edits without a separate edit approval. It is distinct from a tool being available and from the provider's sandbox or approval policy. Read the current labels and explanation instead of assuming an enabled Tools switch approves every operation. For the actual decision cards, including rejection reasons and remembered approvals, see [Approvals and Paused Sessions](https://repoprompt.com/docs/agent-mode/approvals/). ### RepoPrompt tools and sub-agents [Settings → MCP Server → Tools](https://repoprompt.com/docs/settings/tools/) controls which RepoPrompt tools are advertised. Window access, individual tool availability, and operation-specific checks still apply. Consult the [MCP Tools Reference](https://repoprompt.com/docs/mcp-server/mcp-tools/) for those tools' behavior. Sub-agents launched through MCP have a separate policy under [Agent Permissions → Sub-Agents](https://repoprompt.com/docs/settings/agent-permissions/#sub-agents). Changing the current direct session's permission level does not by itself establish the policy for every child or overseen session. --- ## Workflow Templates A workflow template gives the agent a method for handling your request. You provide the task; the template supplies instructions about research, planning, delegation, implementation, or review. Choose a workflow when you want that structure without writing the full procedure yourself. ### Choose from the welcome screen On an empty session, select a card under **What are we building?**. The selected card prepares the next message and focuses the editor. Selecting it again clears that choice. Use the arrows or page dots to browse more cards; the cards reflect your visible workflows and featured choices. Welcome workflow cards for Orchestrate, Review, Deep Plan, and ChatGPT Export Another workflow page with Optimize, Plan and Build, Refactor, and Investigate ### Choose from the Workflow selector Open the lightning-bolt **Workflow** control above the editor. This selector offers the workflow catalog while you compose, including custom workflows you have added. The name and short description help you choose a method before sending. **Configure…** and the welcome screen's **Edit** control open workflow configuration; the refresh control reloads the available definitions. Workflow selector showing built-in templates and Configure | Template | What it asks the agent to do | | --- | --- | | **Orchestrate** | Break a complex request into tasks, delegate work, and check the results. | | **Deep Plan** | Research the code, establish how involved you want to be, and produce a detailed implementation plan. | | **Optimize** | Establish measurements, instrument the relevant behavior, and iterate using evidence. | | **Plan & Build** | Research the request, plan the change, and implement it step by step. | | **Review** | Examine code for bugs, regressions, risks, and missed edge cases. | | **Refactor** | Improve code structure while preserving its intended behavior. | | **Investigate** | Research a bug, crash, security concern, or question and report supporting evidence. | | **ChatGPT Export** | Assemble code and context into a prompt you can take to ChatGPT. | The list depends on visibility settings; a hidden built-in template remains configurable. See [Agent Workflows settings](https://repoprompt.com/docs/settings/agent-workflows/) to show, hide, feature, reorder, or clone templates and create custom Markdown workflows. ### Send the request through the template Select the template, then write a specific request: “Review the checkout changes for cancellation bugs; focus on session cleanup” is more useful than “Review.” Choose the [execution location](https://repoprompt.com/docs/agent-mode/execution-location/), check the model and permissions, and send. RepoPrompt wraps the message in the selected template and clears the selection after accepting the submission. Select another template when a later message needs a different method. Templates are instructions to an agent, so the actual work depends on the task, connected models, tools, and permissions. Selecting **Orchestrate** does not itself start other sessions, and selecting **Review** does not grant additional repository access. These Agent Mode templates are configured separately from [Copy/Chat Workflow Presets](https://repoprompt.com/docs/settings/workflow-presets/) and external [Skills & Slash Commands](https://repoprompt.com/docs/agent-mode/skills/). For external command syntax and installation, see [MCP Workflow Commands](https://repoprompt.com/docs/mcp-server/workflow-commands/). ### Built-in workflow procedures These templates describe an intended process. The agent follows their instructions using its available tools and permissions; selecting a template does not enforce every step or guarantee a result. For the Explore, Engineer, Pair, and Design roles, see [Agent Models](https://repoprompt.com/docs/settings/agent-models/#sub-agent-role-defaults). #### Orchestrate Plans a complex task, decomposes it into discrete work items, and dispatches sub-agents (`pair`, `engineer`, `design`, `explore`) to implement each one. The orchestrator stays lean — it coordinates and monitors, while worker agents handle the actual implementation in fresh context windows. Works with both UI-started and MCP-started sessions. **Flow:** Workspace verification → Contextualize task & Context Builder (`plan` + export) → Decompose into work items → Dispatch sub-agents → Monitor and verify #### Deep Plan Produces a polished, ready-to-execute architectural specification at `docs/plans/-.md` without implementing code. The workflow asks for your preferred involvement level (**Up front**, **Mid-flow**, or **Hands-off**), dispatches parallel `explore` agents across workspace seams, external research, and prior art, runs Context Builder (`plan` mode with export) to build a coverage ledger, dispatches a `design` agent to write an independent critique under `docs/reviews/`, and performs a fidelity-preserving editorial pass. **Flow:** Involvement decision (`ask_user`) → Map seams (`explore` agents) → Scaffold plan → Context Builder (`plan` + coverage ledger) → Design critique (`design` agent) → Editorial polish & fidelity verification #### Optimize Runs a delegation-first, evidence-driven performance optimization loop. The agent scouts bottleneck candidates with parallel `explore` agents, plans debug-gated instrumentation and a baseline procedure via Context Builder, dispatches a `pair` agent to capture baseline metrics in a persistent scoreboard (`prompt-exports/optimize--runs.md`), and iterates one attributed change at a time — consulting the Oracle after each run until the target metric is met, diminishing returns are reached, or the 5-iteration cap is hit. **Flow:** Bottleneck scouting (`explore` agents) → Plan metrics & instrumentation (Context Builder) → Land debug instrumentation & baseline (`pair` agent) → Serial optimization loop (Plan → Implement & measure → Verify scoreboard → Consult Oracle) → Final rollup #### Plan & Build The comprehensive end-to-end implementation workflow. The agent does a quick scan of your codebase, calls Context Builder to gather deep context and generate an architectural plan, refines the plan through Oracle Chat when ambiguities arise, and then implements the solution directly. **Flow:** Quick scan → Context Builder (with `plan`) → Refine with Oracle Chat → Implement with editing tools #### Review Surveys your git changes, determines the comparison scope (uncommitted, staged, vs `main`, etc.), and uses Context Builder to produce a thorough code review grounded in your full codebase — not just the diff. **Flow:** Survey git state → Confirm scope → Context Builder (with `review`) → Clarify findings via Oracle if needed #### Refactor Analyzes your code for redundancies and complexity using parallel `explore` scouts and Context Builder's `review` mode, generates an incremental refactoring plan via Context Builder's `plan` mode, and dispatches `pair` or `engineer` sub-agents to implement improvements step by step while verifying that existing behavior and tests are preserved. **Flow:** Scope & analyze (`explore` + Context Builder `review`) → Plan improvements (Context Builder `plan`) → Decompose & dispatch (`pair`/`engineer`) → Verify tests and diffs #### Investigate Systematic codebase exploration for debugging and root-cause analysis. The workflow template calls for read-only source inspection while creating and updating an investigation report; it explicitly rules out source-code changes. The coding agent triages symptoms into `docs/investigations/-.md`, optionally dispatches `explore` agents for git blame archaeology and external research, uses Context Builder for broad discovery, dispatches a `pair` investigator to test hypotheses, and synthesizes findings with the Oracle until the root cause is confirmed with line-level evidence. **Flow:** Triage & scaffold report → External fact-gathering (`explore`) → Broad discovery (Context Builder) → Deep investigation (`pair`) → Oracle synthesis & final report #### ChatGPT Export Builds focused context for your task using Context Builder (`clarify` mode), checks selection and token counts, and exports a self-contained Markdown prompt file under `prompt-exports/`. Use it with a model available in ChatGPT or another external AI service for a second opinion; the export does not select or grant access to a model. See [How Do I Find the ChatGPT Pro Interface?](https://repoprompt.com/docs/faq/chatgpt-pro/) for the browser workflow, account/model distinction, and how to return the analysis to a coding session. **Flow:** Classify intent → Context Builder (`clarify` mode) → Verify workspace context → Export prompt file to `prompt-exports/` ### Clarify the task and prepare context Enable [Interviewer](https://repoprompt.com/docs/agent-mode/interviewer/) in the composer when you want questions before work begins. Use [Re-prompt](https://repoprompt.com/docs/agent-mode/re-prompter/) to improve a draft before the execution agent receives it. Deep Plan also asks how involved you want to be during planning. [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/) discovers and curates relevant files; [Oracle](https://repoprompt.com/docs/agent-mode/oracle/) reasons over prepared context. Read [How It Works](https://repoprompt.com/docs/overview/how-it-works/) for the discovery and handoff pipeline, and configure Oracle rosters in [Agent Models](https://repoprompt.com/docs/settings/agent-models/#oracle-models). --- ## Version 1.x Series ### Community Edition Version 1.x Series This changelog covers RepoPrompt Community Edition releases, starting with the first CE release. The original, unsupported Classic edition [legacy documentation remains available](https://repoprompt.com/docs/classic-2.1.0/). #### 1.7.0 - October 27, 2026 RepoPrompt v1.7.0 (build 40) adds Agent workflow capabilities and improves reliability across sessions and workspaces. **Highlights** - **Provider environment filtering:** Opt in to withholding named ambient variables from new provider processes, with per-provider exceptions. See [Providers & Models](https://repoprompt.com/docs/providers/overview/#provider-environment-filtering). - **Strict MCP connection approval:** Require external-client admission for the current app run instead of relying on built-in or saved client names. See [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/#connection-approval). - **Overseer coordination:** [Session organization and nested delegation scopes](https://repoprompt.com/docs/overseer/#organize-sessions-with-delegated-permissions), [worktree operations for linked agents](https://repoprompt.com/docs/overseer/#worktrees-on-behalf-of-linked-agents), and quieter routine check-ins. - **Re-prompting:** Revise drafts before submission, review clarification questions, and configure the rewriting model and guidance. See [Re-Prompter](https://repoprompt.com/docs/agent-mode/re-prompter/). - **Model decisions:** Additional services for [Model Router](https://repoprompt.com/docs/agent-mode/model-router/) and [Auto Effort](https://repoprompt.com/docs/agent-mode/auto-effort/) in Agent Decisions, revised new-task defaults, improved usage balancing, updated model choices, and bundled Codex 0.164.0. - **Attachments and Oracle:** Broader [file-attachment support](https://repoprompt.com/docs/agent-mode/oracle/#attach-files-to-an-oracle-consultation), images in [`oracle_send`](https://repoprompt.com/docs/mcp-server/mcp-tools/#oracle_send), and clearer grouped Oracle responses and guidance. - **Keyboard controls:** Remap [keyboard shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/), stop runs, focus the composer, reopen stashed sessions, and find sessions awaiting attention. - **Recovery and performance:** Improved restoration of [sessions](https://repoprompt.com/docs/agent-mode/session-history/), [worktrees](https://repoprompt.com/docs/worktrees/), and windows; less repetitive [MCP approval](https://repoprompt.com/docs/mcp-server/mcp-connections/#connection-approval); and fixes for interrupted processes, Git reads, diff context, and background indexing. **Computer Use:** In the official build, this feature needs an OpenAI-signed Codex executable. Choose a compatible local executable in **Settings → Codex CLI → Advanced**, then restart the app. Ordinary Codex conversations continue to use the included runtime. **[Release notes](https://github.com/repoprompt/repoprompt-ce/releases/tag/v1.7.0)** · **[Full Changelog for 1.7.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.6.0...v1.7.0)** #### 1.6.0 - October 11, 2026 RepoPrompt CE v1.6.0 (build 39) brings major Agent workflow improvements, new model choices, and a smoother app experience. **Highlights** - **Overseer and Agent sessions:** Opt-in Overseer management now includes lanes, role-aware discovery, and stronger recovery after relaunch or compaction. — @baron · #1080↗ · @crstdr · #1131↗ · @crstdr · #1308↗ - **More model choices:** Adds GPT-6.1 Sol and Claude Sonnet 5.5, refreshes Cursor models and effort choices, and adds usage-balanced routing for Codex and Claude plans. — @baron · #1135↗ · @dsebban · #1160↗ · @baron · #1265↗ - **Codex Computer Use:** Opt-in computer interaction in Codex chats, with local tab consent and quieter companion activity. — @crstdr · #1253↗ · @crstdr · #1284↗ - **MCP and Context Builder reliability:** Safer bootstrap handshakes, clearer startup binding results, and a way to talk to in-app Overseers without taking them over. — @baron · #1199↗ · @baron · #1200↗ · @crstdr · #1252↗ - **Code Maps and performance:** Code Maps work in non-Git folders; incremental indexing and idle-work fixes reduce background load. — @crstdr · #994↗ · @baron · #1085↗ · @dsebban · #1259↗ **[Full Changelog for 1.6.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.5.0...v1.6.0)** #### 1.5.0 - September 25, 2026 **What's Changed** - MCP fix: skip deletion fencing for uncatalogued missing paths — @w-winter · #980↗ - Add support for multiple Oracles — @dsebban · #884↗ - Fix: prevent codemap indexing page restart on git churn — @w-winter · #984↗ - Fix selection mirror wedge recovery — @mplibunao · #472↗ - Agent Session Oversight — @crstdr · #872↗ - Refactor Agent Session Oversight internals (stacked on #872) — @baron · #938↗ - Fix completed credential migration and blocked update recovery — @baron · #988↗ - Fix Sparkle startup update isolation — @baron · #992↗ - Fix Model Presets with multiple Oracles — @w-winter · #1000↗ - Put workspace first in window titles — @crstdr · #998↗ - Reuse matching workspaces when opening folders — @aAtila · #924↗ - Fix workspace root removal and discovery readiness — @aAtila · #986↗ - chore: approve contributor luqmannurhakimbazman — @najibninaba · #1006↗ - Migrate release artifact actions to Node 24 — @baron · #1021↗ - feat(agent-mode): add Devin CLI provider — @dsebban · #999↗ - Expand sidebar checkbox hit targets — @aAtila · #1008↗ - Fix seeded worktree publication deadlock and watchdog terminal errors — @luqmannurhakimbazman · #1003↗ - Fix Context Builder settled Oracle replies after primary failure — @dsebban · #1011↗ - Fix cancellation handoff and Context Builder watchdog reliability — @dsebban · #1013↗ - Make the OpenCode thinking level configurable — @crstdr · #1009↗ - Make the subagent wait configurable in Settings — @crstdr · #1005↗ - Fix: Clamp Context Builder budget slider values — @sentry[bot] · #834↗ - Fix: Cache AgentModeViewModel binding snapshot to prevent O(N²) app hang — @sentry[bot] · #990↗ - Fix JSON-valued MCP experimental capabilities — @baron · #1022↗ - Fix Tip publisher API authentication and latest convergence — @baron · #1024↗ - Fix composer cursor jumping during typing — @jsmcx · #1025↗ - Add persistent global model routing with Jev — @baron · #1031↗ - Fix post-migration Keychain item creation — @baron · #1034↗ - Fix Agent Mode sidebar render-loop performance — @baron · #1035↗ - Improve agent orchestration observability and history analytics — @baron · #1036↗ - Add Claude Opus 5.5 model choices — @baron · #1053↗ - Update bundled Codex app-server to 0.156.0 — @baron · #1051↗ - Preserve dirty Copy and Chat overlays during Agent Models changes — @baron · #574↗ - Stop MCP read_file from inventing a one-line success — @luqmannurhakimbazman · #1015↗ - Reduce composer keystroke latency — @baron · #1043↗ - Diagnose canonical workspace state at Agent admission — @baron · #1044↗ - Add bounded workspace projection decode measurements — @baron · #1046↗ - Make physical file reads cancellation-responsive — @mplibunao · #983↗ - Show captured Context Builder behavior during active runs — @bcgalvin · #1028↗ - perf(git): bound diff cache retention with LRU eviction — @morluto · #459↗ - Add bounded MCP lifecycle diagnostics for teardown investigation — @baron · #1048↗ - Make passive appcast callback main-actor contract explicit — @sentry[bot] · #1030↗ - Add Jev multi-question judgment foundation — @baron · #1045↗ - Fix Model Router persistence and refresh routing models — @baron · #1052↗ - Stabilize workspace lifecycle regression tests (#1054) — @baron · #1055↗ - Fix Context Builder prerequisite error classification — @bcgalvin · #1049↗ - Update bundled Codex app-server to 0.156.1 — @baron · #1056↗ - Preserve file authority across context binding — @mplibunao · #982↗ - Add MCP controls for agent session pins and manual order — @baron · #1058↗ - Guard protected Agent tabs during workspace replay — @baron · #1059↗ - Fix app hang by caching sorted model options — @sentry[bot] · #1060↗ - Add independent Jev Auto effort for Codex and Claude — @baron · #1062↗ - Add automatic APFS CoW cloning for app-managed worktrees — @baron · #1064↗ - Prepare v1.5.0 stable release metadata — @baron · #1066↗ - fix(mcp): allow background-tab selection mirrors to complete — @w-winter · #1069↗ - fix(agent-mode): apply Auto effort to Claude MCP runs — @baron · #1070↗ **New Contributors** - luqmannurhakimbazman made their first contribution. - jsmcx made their first contribution. - bcgalvin made their first contribution. **[Full Changelog for 1.5.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.4.1...v1.5.0)** #### 1.4.1 - September 7, 2026 **What's Changed** - Fix split-root Stable release metadata — @baron · #911↗ - Test MCP stdio and terminal commit barriers — @baron · #912↗ - Fix: codemaps to index nested repo worktree sources — @w-winter · #913↗ - Fix Tip recovery after Stable 1.4.0 — @baron · #914↗ - Harden Tip publisher release observation — @baron · #920↗ - Add Claude Fable 5.1 to the Claude Code model catalogs — @datawisebets · #932↗ - Authenticate Tip protected-main preflight — @baron · #925↗ - Fix (MCP) - align context routing with active workspace — @w-winter · #936↗ - Fix: out-of-bounds access due to stale workspace index after async yield — @sentry[bot] · #929↗ - Add Claude Fable Latest and normalize model picker fonts — @w-winter · #934↗ - Fix Tip release publication races — @baron · #943↗ - Fix (HistoryMCP) - prevent crash in buildGroups due to force-unwrap — @sentry[bot] · #942↗ - Fix: Swift overflow when converting negative st_dev to UInt64 — @sentry[bot] · #937↗ - Fix: Sanitize AI narration text to prevent SwiftUI crashes — @sentry[bot] · #940↗ - Fix: App hang due to expensive Codex model display name computation — @sentry[bot] · #941↗ - Fix: Context menu crash on dynamic item changes — @sentry[bot] · #939↗ - Prefer Grok's direct model parser when configOptions accompany models — @datawisebets · #933↗ - Fix file search freshness after Add Folder — @aAtila · #927↗ - Fix duplicate workspace consolidation persistence — @crstdr · #915↗ - Fix release provisioning profile permissions — @baron · #948↗ - Remove artificial timeouts from Tip workflow — @baron · #950↗ - Keep new windows eligible for Merge All Windows — @nickdavis · #853↗ - Fix InterceptingWindowDelegateProxy unrecognized selector crash — @sentry[bot] · #877↗ - Fix: EXC_BREAKPOINT in duplicate workspace cleanup — @sentry[bot] · #841↗ - Fix GitWorktreeDefaultPathPlanner O(N^2) hang — @sentry[bot] · #891↗ - Reduce repeated transcript snapshot access in row construction — @sentry[bot] · #820↗ - Index hidden-session slice paths during rebase planning — @sentry[bot] · #839↗ - Give Codex model options a consistent sort order — @sentry[bot] · #813↗ - Preserve competing files during exclusive creation — @baron · #964↗ - Derive session deletion targets from validated files — @baron · #959↗ - Preserve settings after failed backup recovery — @baron · #958↗ - Retain physical authority for protected file mutations — @baron · #969↗ - Revalidate worktree identity before alternate-root operations — @baron · #965↗ - Preserve workspace affinity across MCP reconnects — @baron · #966↗ - Prevent load-time repair from resurrecting deleted sessions — @baron · #967↗ - Retain process ownership until child termination settles — @baron · #968↗ - Preserve settings across schema migration and recovery retries — @baron · #970↗ - Fix FSEvents delivery liveness — @baron · #713↗ - Enforce MCP readiness caller deadlines — @baron · #711↗ - Fix qualified reads stalling on unrelated roots — @mplibunao · #889↗ - Resolve advertised Codex Max and Ultra effort selections — @nickdavis · #953↗ - Allow selecting a local Codex runtime — @crstdr · #956↗ - Fix Context Builder shutdown during app termination — @mplibunao · #955↗ - Fix concurrent same-workspace Agent admission — @mplibunao · #897↗ - fix: support verified Cursor agent ACP entrypoint — @najibninaba · #902↗ - feat(agent-mode): add Cursor Effort and Speed controls — @najibninaba · #960↗ - Prevent concurrent settings writes from overwriting newer data — @baron · #973↗ - Protect large prompt exports from watchdog disconnects — @mplibunao · #898↗ - Fix workspace loading, cleanup, and settings preservation — @baron · #974↗ - Fix OpenCode launch validation for admin-writable Homebrew Cellar paths — @AmrMohamad · #976↗ - Make bundled Codex predictable and upgrade to 0.153.4 — @baron · #979↗ - Add Google Antigravity ACP support — @z23cc · #975↗ - Prepare v1.4.1 release metadata — @baron · #978↗ **New Contributors** - AmrMohamad made their first contribution. - z23cc made their first contribution. **[Full Changelog for 1.4.1](https://github.com/repoprompt/repoprompt-ce/compare/v1.4.0...v1.4.1)** #### 1.4.0 - August 30, 2026 **What's Changed** - Scale MCP read_file concurrency to machine capacity — @baron · #798↗ - Globalize Context Builder Settings behavior and make Analysis Budget independent — @w-winter · #801↗ - Agent Mode: eliminate app hang from AgentImageInputAdapter init — @sentry[bot] · #779↗ - Stabilize AgentRunWorktreeStartTests production-capture selection race (#420) — @moonray · #430↗ - Dismiss tooltips when owner windows change lifecycle — @0xNino · #564↗ - Add multi-select + bulk actions to Agent Mode chats — @w-winter · #802↗ - Fix: Unify exact read and mutation paths — @w-winter · #800↗ - Add stored prompt management controls — @w-winter · #799↗ - Fix: decode legacy mutation journal status — @w-winter · #815↗ - Prevent ephemeral workspace leaks and add safe bulk cleanup — @baron · #814↗ - Route direct-headless agents through existing worktrees — @nickdavis · #761↗ - Add Grok Build CLI as an ACP Agent Mode provider — @datawisebets · #817↗ - Fix: bound MCP structure settlement recovery — @w-winter · #822↗ - Fix: expose global skills to Codex agents — @w-winter · #824↗ - Add inline file browser to manually add files/codemaps to selected set in Context Composer — @w-winter · #823↗ - Fix Codex session disconnect during worktree rebinding — @baron · #826↗ - Add Grok Build reasoning-effort selection — @datawisebets · #825↗ - Fix Codex wait-agent watchdog liveness — @baron · #833↗ - Fix replace-all matching with reused full-file indexes — @morluto · #737↗ - Add Grok Build CLI to Oracle and built-in chat models — @dsebban · #838↗ - test: stabilize worktree API smoke and agent-run startup — @dsebban · #832↗ - Add a Codex project hook approval flow to Agent Mode — @mplibunao · #678↗ - Bound release network operations and recover Sentry finalization — @baron · #579↗ - Fix bind_context active workspace routing — @nickdavis · #812↗ - Add session ID copying to Agent Mode sidebar menus — @aAtila · #846↗ - Reject rootless working_dirs tab bindings — @nickdavis · #835↗ - Enable Codex apps with runtime 0.149.0 — @nickdavis · #851↗ - Harden Apple identity migration bridge — @baron · #857↗ - Fix: App hang in MessageTimestampFormatterCache.CacheKey.init — @sentry[bot] · #819↗ - Include session title in handoff prompt — @baron · #747↗ - Fix Grok Oracle returning progress text instead of an answer — @dsebban · #856↗ - Harden identity rollover runtime safety — @baron · #868↗ - Add dormant identity transition release tooling — @baron · #869↗ - Enable Tip identity transition rehearsal — @baron · #870↗ - Fix Tip identity transition release credentials — @baron · #873↗ - Make Tip identity rollout dispatches reliable and truthful — @baron · #874↗ - Fail Tip identity credential errors before staging — @baron · #876↗ - Fix Tip staged rollout authority — @baron · #879↗ - Fix Tip signed artifact handoff — @baron · #880↗ - Fix Tip appcast generation without predecessors — @baron · #883↗ - Enable Tip identity transition role — @baron · #885↗ - Fix Tip transition stage identity validation — @baron · #888↗ - Fix Tip signer identity projection — @baron · #890↗ - Separate sidebar command progress from bulk selection UI — @aAtila · #878↗ - Refactor Apple identity transition release pipeline — @baron · #894↗ - Replace Tip release machinery with a direct protected-main publisher — @baron · #895↗ - Restore automatic Tip publication for all rollout roles — @baron · #896↗ - Remove manual Tip rollout role input — @baron · #901↗ - Refactor CI tests into deterministic contract and integration lanes — @baron · #899↗ - Fix redundant Tip package notarization — @baron · #905↗ - Fix Tip package signing key authorization — @baron · #907↗ - Fix: restore global Codex instructions in Agent Mode — @w-winter · #906↗ - Refactor test suite to remove low-value and timing-dependent coverage — @baron · #908↗ - Fix CLI single-shot selector routing — @mplibunao · #904↗ - Release v1.4.0 — @baron · #909↗ **New Contributors** - 0xNino made their first contribution. **[Full Changelog for 1.4.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.3.0...v1.4.0)** #### 1.3.0 - August 11, 2026 **What's Changed** - Trace worktree startup stall in shard 2 — @baron · #721↗ - Remove the 500-tab background Agent limit — @baron · #720↗ - Use scoped locking for ACP async state transitions — @baron · #719↗ - fix: require authoritative context builder completion — @w-winter · #722↗ - feat: show sessionless compose tabs in agent chats — @w-winter · #716↗ - Fix automatic Agent Mode tab eviction — @baron · #723↗ - Cancel superseded pull request CI runs — @morluto · #741↗ - P0: Protect live Agent session identity during admission — @baron · #742↗ - Report preset save failures and roll back non-durable edits — @morluto · #733↗ - Fix workspace authority conflict recovery — @baron · #744↗ - Harden legacy defaults collection during startup — @baron · #745↗ - Prevent cancelled CLI requests from stalling or spawning — @morluto · #724↗ - Prevent cancelled tasks from entering an unlocked AsyncMutex — @morluto · #725↗ - Self-heal workspace authority revision races — @baron · #746↗ - Settle cancelled Codex stderr waiters promptly — @morluto · #738↗ - Allow MessageReaper to tear down with queued messages — @morluto · #734↗ - Synchronize transcript debug instrumentation callbacks — @morluto · #736↗ - Clear transcript refresh signatures after tab removal — @morluto · #739↗ - Migrate RepoPromptShared to Swift 6 — @baron · #753↗ - Fence tool-card presentation derivation from render recomputation — @baron · #754↗ - Establish neutral agent execution contracts — @baron · #756↗ - fix: make agent read_file selection converge — @w-winter · #755↗ - Agent Mode: classify terminal failures at settlement — @baron · #759↗ - Agent Mode: extract run-attempt lifecycle authority — @baron · #763↗ - Make agent run identity teardown stale-safe — @baron · #764↗ - Harden conductor control-plane resilience — @baron · #765↗ - Bundle Codex 0.147.0 and fix exec permissions — @nickdavis · #748↗ - Add durable conductor build cache — @baron · #766↗ - Harden workspace-switch runtime ownership transfer — @baron · #767↗ - fix(mcp): add Sonoma async frame compatibility barrier — @baron · #768↗ - Agent Mode: bind terminal settlement to exact sessions — @baron · #772↗ - Agent Mode: hoist terminal attachment disposition — @baron · #773↗ - Agent Mode: detach Claude coordinator from view model — @baron · #776↗ - feat(agent-mode): add pinned Claude Opus 4.8 picker model — @aAtila · #774↗ - Bound untrusted Agent Mode tool names before normalization — @baron · #770↗ - Enforce one accounting identity per prompt file — @baron · #777↗ - Agent Mode: centralize Claude settlement authority — @baron · #778↗ - feat: streamline Context Composer entry points — @w-winter · #783↗ - Agent Mode: extract top-level tab session — @baron · #784↗ - Update APPROVED_CONTRIBUTORS — @baron · #785↗ - Agent Mode: share transient execution classification — @baron · #786↗ - Oracle: extract headless streaming runtime — @baron · #787↗ - Prompt: extract stored-prompt persistence boundary — @baron · #788↗ - Reconstruct diff chunks without repeated array shifts — @morluto · #735↗ - Add focused-build cost reporting and high-output conductor diagnostics — @morluto · #521↗ - fix(agent-mode): eliminate O(N) snapshot copies in handoffConfig — @sentry[bot] · #780↗ - Preserve Context Builder pending context through routing — @morluto · #566↗ - Add built-in workflow parity to direct headless mode — @nickdavis · #760↗ - Agent Mode: share Codex transient execution classification — @baron · #791↗ - Agent Mode: share Claude transient execution classification — @baron · #792↗ - Agent Mode: share ACP transient execution classification — @baron · #793↗ - Add operation-level MCP concurrency evidence — @baron · #794↗ - Release v1.3.0 — @baron · #797↗ **[Full Changelog for 1.3.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.2.0...v1.3.0)** #### 1.2.0 - August 3, 2026 **What's Changed** - Surface Code Map recovery exhaustion — @baron · #689↗ - Prevent file-action watchdog stalls during mutation I/O — @baron · #688↗ - Headless runtime M1: add runtime and catalog foundation — @provencher · #640↗ - Fix Oracle heartbeat liveness tracking — @dsebban · #696↗ - Fix App Hang: Disable text checking in AttributedTextView — @sentry[bot] · #697↗ - Fix App Hang: Optimize string prefix checks — @sentry[bot] · #683↗ - Fix AnchorGeometryView app hang — @sentry[bot] · #685↗ - Fix agent workspace performance regression — @baron · #680↗ - Improve ChatGPT login resilience and managed sign-out — @baron · #698↗ - Fix EXC_BREAKPOINT from dictionary mutation during iteration — @sentry[bot] · #693↗ - Headless runtime M2: move workspace/context authority — @provencher · #643↗ - Add opt-in Codex memories setting — @baron · #691↗ - Fix Tip socket ownership startup race — @baron · #699↗ - Headless runtime M3: migrate read and discovery families — @provencher · #657↗ - Keep failed CI from evicting Tip builds — @baron · #700↗ - M4: protect MCP mutations and security boundaries — @provencher · #660↗ - Provision Keychain for packaged release smoke — @baron · #701↗ - Remove test contract ledger system — @baron · #704↗ - Stabilize ledger-free CI routing and codemap contracts — @baron · #705↗ - [6/8] M5: move AI, Agent, Context Builder, and interaction into domain runtime — @provencher · #664↗ - Fix M5 credential pruning type inference — @baron · #706↗ - Optimize Agent Mode sidebar projection caching — @baron · #703↗ - Fix protected mutation commit boundary — @baron · #707↗ - Add Compose: context inspector inspired by RP Classic — @w-winter · #535↗ - [7/8] M6: Add direct headless MCP runtime — @provencher · #674↗ - M7: complete headless MCP runtime cutover — @provencher · #677↗ - perf: coalesce compose inspector refresh work — @baron · #709↗ - Fix current-main CI blockers after M7 merge — @baron · #712↗ - Release v1.2.0 — @baron · #714↗ **[Full Changelog for 1.2.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.1.2...v1.2.0)** #### 1.1.2 - July 30, 2026 **What's Changed** - Add semantic text-direction roles for app surfaces — @baron · #670↗ - Clamp Markdown selections before TextKit restoration — @baron · #671↗ - Preserve inline-code direction in mixed RTL Markdown — @baron · #672↗ - Rebase PR #70: Linkify Agent Mode prose URLs — @dah · #684↗ - Headless runtime M0: freeze contracts and evidence gates — @provencher · #639↗ - Fix Data.WritingOptions conflict in writeHandoffPayload — @sentry[bot] · #690↗ - Fix MCP settlement across Codex turns and file mutations — @provencher · #687↗ - Release v1.1.2 — @baron · #692↗ **[Full Changelog for 1.1.2](https://github.com/repoprompt/repoprompt-ce/compare/v1.1.1...v1.1.2)** #### 1.1.1 - July 29, 2026 **What's Changed** - Fix Codex app-server tool override policy — @baron · #603↗ - Add Codex app-server schema drift gate — @baron · #604↗ - perf: reduce codemap full-load latency — @provencher · #600↗ - build: bundle pinned Codex runtimes — @baron · #605↗ - Fix worktree-bound Codex app-server startup — @mplibunao · #568↗ - Fix bundled Codex release signing — @baron · #606↗ - Stabilize synthetic watcher integration tests — @baron · #607↗ - Optimize Swift and TypeScript CodeMap pipelines — @provencher · #608↗ - Add Agent Mode session handoff prompt — @baron · #610↗ - Fix packaged MCP smoke ownership checks — @baron · #611↗ - feat: make bundled Codex runtime authoritative — @baron · #612↗ - Make Codex session routing deterministic per tab — @baron · #614↗ - Add per-root Code Map generation controls — @provencher · #609↗ - feat(deep-plan): treat the context_builder export as a preservation baseline — @w-winter · #615↗ - Bound Codex app-server liveness and silent hangs — @baron · #617↗ - fix(mcp): preserve caller binding during agent runs — @w-winter · #616↗ - Fix Codex legacy thread resume by forwarding rollout path — @baron · #618↗ - Fix MCP reconnect abort and Git artifact fence spin — @baron · #613↗ - Replace codemap projections with root-local incremental graphs — @provencher · #621↗ - Fix Codex session tenacity recovery — @baron · #623↗ - Fix release codemap event type visibility — @baron · #624↗ - Optimize Codex thread startup memory policy — @baron · #625↗ - Preserve Codex completion across active reattach — @baron · #626↗ - Add Claude Opus 5 support — @baron · #627↗ - fix(agent-run): improve respond validation diagnostics — @w-winter · #622↗ - Fix stale codemap proof reclassification — @baron · #628↗ - Make async test oracles deterministic — @provencher · #629↗ - Automate guarded Codex runtime update candidates — @baron · #633↗ - Rebase 315/316 collapse nested threads and clean up provider conversations — @dah · #630↗ - Fix Finder launch and install commands when only Xcode beta is installed — @dah · #631↗ - Restore Codex messages rejected before dispatch — @baron · #619↗ - Update bundled Codex to 0.145.0 — @baron · #635↗ - Point fork dependencies at RepoPrompt organization — @provencher · #638↗ - Fix Codex watchdog for silent long-running tools — @baron · #636↗ - Add PR-ready validation timing receipts — @baron · #634↗ - Add MCP concurrency evidence telemetry — @baron · #632↗ - Improve tip update details — @baron · #637↗ - Show build numbers in Sparkle update alerts — @baron · #641↗ - Fix MCP read timeout settlement without bridge disconnect — @baron · #644↗ - Fix CollapsibleUserMessage performance on large messages — @sentry[bot] · #601↗ - Fix bundled Codex V8 JIT entitlements — @baron · #647↗ - Keep Tip update alerts compact — @baron · #656↗ - Add reusable Agent Mode handoff instructions — @erauner12 · #645↗ - Refresh approved contributors — @provencher · #572↗ - Fix Code Map stalls and manifest write amplification — @baron · #659↗ - Harden Code Map recovery after performance cutover — @baron · #661↗ - Fix Tip release optimizer ownership crash — @baron · #663↗ - Fix Codex watchdog for composite waits — @baron · #667↗ - Fix path-scoped Git artifact publication freezes — @baron · #668↗ - Fix duplicate physical root label traps — @erauner12 · #673↗ - Include steering text in Agent Mode wait interruptions — @erauner12 · #669↗ - Fix CodeHighlighter cache race condition — @sentry[bot] · #676↗ - Fix: Prevent duplicate worktree path crash — @sentry[bot] · #553↗ - Fix dirent struct copy causing EXC_BAD_ACCESS in FileSystemService — @sentry[bot] · #602↗ - Optimize Agent Mode: Transcript snapshot access — @sentry[bot] · #658↗ - Eliminate app hang from synchronous file open — @sentry[bot] · #589↗ - Release v1.1.1 — @baron · #682↗ **New Contributors** - w-winter made their first contribution. **[Full Changelog for 1.1.1](https://github.com/repoprompt/repoprompt-ce/compare/v1.1.0...v1.1.1)** #### 1.1.0 - July 21, 2026 **What's Changed** - fix(release): support Sentry org:ci tokens — @baron · #551↗ - refactor(workspace): isolate path policy core — @provencher · #559↗ - Complete Agent Models workspace follow-ups — @crstdr · #545↗ - fix: update Codex app-server text payload key — @mplibunao · #450↗ - fix(mcp): avoid task-group teardown abort in runTransport retry backoff — @pnascimento9596 · #517↗ - Fail Codex child sessions closed when RepoPrompt MCP provisioning or routing never confirms — @mplibunao · #532↗ - Add durable MCP watchdog attribution — @baron · #567↗ - Stream Context Builder progress over standard MCP — @OCWC22 · #510↗ - Harden Context Builder MCP routing readiness — @baron · #569↗ - Preserve MCP connection on code structure timeout — @baron · #570↗ - Fix authenticated tip release lookup — @baron · #571↗ - perf(codemap): reduce manifest write amplification during indexing — @morluto · #487↗ - Avoid global manifest scans for access refreshes — @baron · #552↗ - fix: restore Sentry telemetry in Tip builds — @baron · #555↗ - perf(codemap): avoid repeated full-store scans when publishing manifests — @morluto · #488↗ - Make MCP watchdog deadlines independent of event ordering — @baron · #575↗ - Harden code-structure settlement lifecycle — @baron · #576↗ - Make MCP route confirmation and revocation authoritative — @baron · #577↗ - Bound MCP advisory progress backpressure — @baron · #578↗ - Bound agent session cleanup and preserve partial results — @baron · #582↗ - Bound history MCP work and preserve transport — @baron · #583↗ - Fix agent message bubble line counting performance — @sentry[bot] · #584↗ - Fix history tool catalog golden — @baron · #585↗ - Preserve codemap authority across publication retries — @baron · #586↗ - Fix Context Builder cancellation after discovery commit — @baron · #588↗ - Speed up Context Builder selection handoff — @baron · #591↗ - Fix Context Builder routing and settlement — @baron · #592↗ - Migrate CodeMap core to Swift 6 with exact official Tree-sitter pins — @provencher · #580↗ - Fix clean release dependency cloning — @baron · #596↗ - Remove Dart CodeMap support — @provencher · #597↗ - Release v1.1.0 — @baron · #599↗ **New Contributors** - pnascimento9596 made their first contribution. - OCWC22 made their first contribution. **[Full Changelog for 1.1.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.29...v1.1.0)** #### 1.0.29 - July 15, 2026 **What's Changed** - Make Context Builder model selection globally authoritative — @morluto · #463↗ - Prepare hosted app tests for optional sharding — @morluto · #440↗ - fix(agent-mode): stop tool-result updates from remounting unrelated cards — @morluto · #458↗ - Add RPCE maintainer guidance skill — @baron · #502↗ - Harden Sentry privacy and release metadata — @baron · #474↗ - Add scoped Agent Models settings — @crstdr · #275↗ - Fix debug provenance JSON validation — @provencher · #512↗ - Add title-adjacent Agent chat options menu — @baron · #516↗ - Fail closed on unsigned Tip appcasts — @baron · #497↗ - Fix Oracle selection packaging and mutation ingress stalls — @provencher · #520↗ - Enforce strict ledger validation for suite plans — @baron · #528↗ - Fix global settings schema rollback compatibility — @baron · #530↗ - Harden Sentry privacy and release promotion — @baron · #533↗ - Fix typed Context Builder prompt handoff (#526) — @mplibunao · #529↗ - Fix scoped Agent Models state integrity — @baron · #534↗ - Fix inactive-workspace Context Builder authority — @baron · #538↗ - Harden Git process launch lifecycle — @baron · #539↗ - Prevent recursive workspace path-index teardown overflow — @baron · #540↗ - Make TextKit external replacements undo-safe — @baron · #543↗ - Prevent duplicate workspace root ID crashes — @baron · #541↗ - Bound applied-index fallbacks and harden workspace autosave — @baron · #542↗ - Fix app hang during date formatting by pre-warming locale cache — @sentry[bot] · #438↗ - Harden transcript export against duplicate turn IDs — @sentry[bot] · #544↗ - Improve Tip build update notices — @baron · #537↗ - Harden Agent chat titlebar safety — @baron · #536↗ - Fix execution-location popover resize crash — @baron · #548↗ - Release v1.0.29 — @baron · #550↗ **New Contributors** - crstdr made their first contribution. - mplibunao made their first contribution. - sentry made their first contribution. **[Full Changelog for 1.0.29](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.28...v1.0.29)** #### 1.0.28 - July 10, 2026 **What's Changed** - Harden release packaged smoke timeout — @baron · #441↗ - Split RepoPrompt into thin executable and app target — @provencher · #437↗ - Add opt-in tip update channel and rolling publish workflow — @baron · #442↗ - Fix Tip build number override — @baron · #467↗ - Improve conductor worktree parallelism — @baron · #470↗ - Fix Context Builder teardown finalization — @baron · #448↗ - Update Codex support for GPT-5.6 models — @baron · #462↗ - Release v1.0.28 — @baron · #477↗ **[Full Changelog for 1.0.28](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.27...v1.0.28)** #### 1.0.27 - July 9, 2026 **What's Changed** RepoPrompt CE 1.0.27 is the public release for everything merged after v1.0.24. It includes the intended but unpublished v1.0.25/v1.0.26 payloads plus the follow-up CLI, test-harness, and Sentry release fixes needed to make this train safe for in-app updates. **App and Agent Mode** - History query MCP tools (`list_sessions`, `search`, `time`) with tunable idle threshold, per-day attribution, duration fixes, and review hardening. — @moonray · #303↗ - Enhanced Agent session search HUD behavior and archived-session visibility. — @baron · #397↗ - Faster, less noisy workspace switch load readiness. — @baron · #347↗ - Hardened agent CLI startup in fragile user environments. — @baron · #424↗ - Fixed git diff artifact export after alias authorization rejection. — @baron · #429↗ - Hardened build storm coordination and process cleanup. — @baron · #427↗ **Settings, CLI, and Developer Workflow** - Persist global defaults across restarts and propagate changes across windows. — @moonray · #418↗ - Speed up `dev-lint` SwiftLint discovery. — @baron · #428↗ - Recover CLI installation from stale App Translocation symlinks. — @amittell · #413↗ - Harden test harness behavior against hangs and waiter leaks. — @morluto · #435↗ **Telemetry and Release Reliability** - Integrated full Sentry telemetry. — @baron · #409↗ - Added release-pipeline dSYM generation and upload coverage. — @cameroncooke · #332↗ - Fixed Sentry-enabled release build coverage for the v1.0.26 attempt. — @baron · #433↗ - Refactored Sentry telemetry controls and added release coverage for official Sentry-enabled builds. — @baron · #436↗ - Release preparation for the unpublished v1.0.25 train and this final v1.0.27 publish. — @baron · #431↗ · @baron · #439↗ **New Contributors** - amittell made their first contribution. **[Full Changelog for 1.0.27](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.24...v1.0.27)** #### 1.0.24 - July 6, 2026 **What's Changed** - Add impacted XCTest lane and harden test tooling — @morluto · #374↗ - Refresh approved contributors — @provencher · #378↗ - fix(agent-mode): open live oracle from running tool card — @morluto · #358↗ - Stabilize CI app tests with sharding and lifecycle cleanup — @morluto · #379↗ - Polish agent sidebar worktree capsules (auto-naming, sizing, styling) — @provencher · #380↗ - Fix routed worktree inheritance for UI parents — @baron · #388↗ - Fix mutation tools when worktree scope is unavailable — @baron · #387↗ - Tail-window massive agent transcripts — @baron · #391↗ - Fix issue 390 targeted authority reconciliation — @baron · #392↗ - Add minimal Sentry runtime wiring — @baron · #393↗ - Release RepoPrompt CE 1.0.24 — @baron · #395↗ **[Full Changelog for 1.0.24](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.23...v1.0.24)** #### 1.0.23 - July 3, 2026 **What's Changed** - Add content-addressed codemaps and diff-seeded worktree startup — @provencher · #314↗ - Add Codex reasoning summary setting — @provencher · #336↗ - Collapse Interview toggle to icon-only — @baron · #321↗ - Refresh selected files popover UI and performance — @baron · #333↗ - [codex] Contain codemap selection decode failures — @provencher · #339↗ - Fix MCP token accounting freshness reporting — @provencher · #343↗ - Add Claude Sonnet 5 model support — @BetaFold3 · #338↗ - Start test-suite wallclock optimization reliability campaign — @provencher · #346↗ - build(telemetry): link Sentry conditionally and document privacy model — @cameroncooke · #323↗ - Resume inactive agent sessions when steering — @provencher · #353↗ - fix(agent-mode): stop listener leaks and orphaned Claude processes on close — @morluto · #319↗ - fix: omit nil Codex service tier — @dsebban · #317↗ - Fix Codex steer crash and resume handling — @provencher · #354↗ - Stabilize sidebar root updates during workspace switch — @baron · #351↗ - Add agent session switcher HUD — @baron · #352↗ - Fix MCP selection token freshness — @baron · #359↗ - Avoid applied-index hierarchy rebuilds for small deltas — @baron · #361↗ - Bump engineer role default to GPT-5.5 Medium — @baron · #364↗ - Fix crash restore settings persistence — @baron · #365↗ - Fix bound-tab token cache freshness — @baron · #367↗ - Prepare release 1.0.23 — @baron · #369↗ **New Contributors** - dsebban made their first contribution. **[Full Changelog for 1.0.23](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.22...v1.0.23)** #### 1.0.22 - June 28, 2026 **What's Changed** - Fix Context Builder worktree review selection authority and freshness — @provencher · #277↗ - keep @file tag paths pathful and non-absolute — @aAtila · #274↗ - build: Add Makefile help target — @cameroncooke · #272↗ - fix: resume MCP helper sessions after app restart — @clairernovotny · #286↗ - fix(claude-code): emit CLI identity preamble for GLM/z.ai backend — @moonray · #296↗ - Fix and modernize Codex agent_run transcripts — @provencher · #299↗ - Refresh approved contributors — @provencher · #300↗ - Fix symlinked global skill root readability — @BetaFold3 · #289↗ - Fix CE URL scheme routing — @baron · #101↗ - Restore Agent Mode Interview pill — @baron · #147↗ - Fix orphaned OpenCode ACP runtimes on tab teardown killing CPU memory — @morluto · #292↗ - Refresh approved contributors — @provencher · #302↗ - Fix Oracle and sub-agent role model selections resetting on restart — @datawisebets · #305↗ - Clarify sliced file selection summaries — @provencher · #262↗ - Surface OpenCode empty ACP completions — @baron · #310↗ - Prepare RepoPrompt CE 1.0.22 — @baron · #311↗ **New Contributors** - clairernovotny made their first contribution. - datawisebets made their first contribution. **[Full Changelog for 1.0.22](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.21...v1.0.22)** #### 1.0.21 - June 21, 2026 **What's Changed** - Stabilize workspace switch cleanup tests — @erauner12 · #263↗ - Refresh approved contributors — @provencher · #269↗ - Fix duplicate Check for Updates menu item — @BetaFold3 · #268↗ - Optimize workspace file search index readiness — @provencher · #270↗ - Add generated Xcode workspace workflow — @provencher · #260↗ - fix(xcode): Support generated workspace in Xcode 26 and 27 — @cameroncooke · #271↗ - Fix Oracle review diffs for worktrees — @provencher · #265↗ - Release RepoPrompt CE 1.0.21 — @provencher · #273↗ **New Contributors** - cameroncooke made their first contribution. **[Full Changelog for 1.0.21](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.20...v1.0.21)** #### 1.0.20 - June 19, 2026 **What's Changed** - Preserve Agent chat order when opening sessions — @provencher · #253↗ - Fix Context Builder completion after discovery peer EOF — @provencher · #254↗ - Fix file search scope failures and cold catalog cost — @provencher · #255↗ - Reduce Agent Mode file-tool MainActor stalls — @provencher · #256↗ - Refactor Oracle routing policy boundaries — @provencher · #251↗ - Improve Cursor Agent CLI launch resolution diagnostics — @dlcen · #208↗ - Add smart Agent Mode timestamps — @antonioc-cl · #182↗ - Show a Built-in badge instead of a no-op Remove button for default trusted clients — @BetaFold3 · #178↗ - Fix Claude Safe Managed launch settings and MCP CLI wait bounds — @morluto · #252↗ - Release RepoPrompt CE 1.0.20 — @provencher · #258↗ **New Contributors** - dlcen made their first contribution. - antonioc-cl made their first contribution. - morluto made their first contribution. **[Full Changelog for 1.0.20](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.19...v1.0.20)** #### 1.0.19 - June 18, 2026 **What's Changed** - Refresh approved contributors — @provencher · #234↗ - Optimize XCTest suite lifecycle and runtime — @provencher · #236↗ - Add repo skill for standardized issue creation — @erauner12 · #237↗ - Fix Agent Mode Oracle transcript routing — @provencher · #247↗ - Add MCP read latency diagnostics — @provencher · #239↗ - Fix canonical codemap selection and packaging — @provencher · #245↗ - Refresh approved contributors — @provencher · #243↗ - Add Z.ai GLM 5.2 model support — @baron · #240↗ - Fix Agent sidebar restore hierarchy and ordering — @provencher · #246↗ - Fix worktree readiness and parallel agent startup — @provencher · #248↗ - Release RepoPrompt CE 1.0.19 — @provencher · #250↗ **[Full Changelog for 1.0.19](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.18...v1.0.19)** #### 1.0.18 - June 16, 2026 **What's Changed** - Reduce structural tests and harden test lifecycle — @provencher · #218↗ - Fix Agent Files preview loading state — @erauner12 · #221↗ - Avoid duplicate manage_selection freshness work — @provencher · #220↗ - Integrate MCP lifecycle and bounded search freshness fixes — @provencher · #226↗ - Fix role-default rows under filtered availability — @baron · #224↗ - Fix agent preview retention architecture — @baron · #225↗ - Reduce parallel MCP contention and preserve Agent selections — @provencher · #231↗ - Release RepoPrompt CE 1.0.18 — @baron · #233↗ **[Full Changelog for 1.0.18](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.17...v1.0.18)** #### 1.0.17 - June 14, 2026 **What's Changed** - Stabilize descriptor inheritance test — @provencher · #198↗ - Stabilize watcher restart barrier coverage — @provencher · #199↗ - Fix Git pipe drain descriptor race — @provencher · #201↗ - Stabilize codemap unload reentrancy test teardown — @provencher · #203↗ - Fix CC Zai availability refresh for preconfigured keys — @baron · #188↗ - Refresh approved contributors — @provencher · #202↗ - Fix test runtime lifecycle disposal — @provencher · #209↗ - Fix composer binding after chat handoff — @provencher · #204↗ - Integrate PR #195 worktree test settings stabilization — @provencher · #200↗ - Fix warm file_search validation stalls — @provencher · #205↗ - Show workspace names in window and native tab titles — @nickdavis · #180↗ - Improve Agent Mode workspace footer readability — @erauner12 · #185↗ - Fix Git cancellation output-drain stall — @provencher · #210↗ - Fix Context Builder MCP response teardown race — @provencher · #211↗ - Add active worktree context actions — @erauner12 · #193↗ - Prepare RepoPrompt CE 1.0.17 — @provencher · #213↗ **New Contributors** - nickdavis made their first contribution. - erauner12 made their first contribution. **[Full Changelog for 1.0.17](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.16...v1.0.17)** #### 1.0.16 - June 14, 2026 **What's Changed** - chore: update approved contributor handles — @provencher · #179↗ - Integrate MCP throughput remediation into staging — @baron · #176↗ - Promote MCP throughput remediation staging to main — @provencher · #186↗ - Fix MCP transport timeout recovery — @provencher · #171↗ - Fix Agent Mode wait recovery and Codex managed defaults — @provencher · #190↗ - Keep CLI provider disclosures user-controlled — @provencher · #191↗ - Fix resumed agent ownership and file-search tail latency — @provencher · #192↗ - Integrate PR #146 worktree-aware Context Builder on main — @provencher · #194↗ - Fix Context Builder model restoration on launch — @provencher · #196↗ - Prepare RepoPrompt CE 1.0.16 — @provencher · #197↗ **[Full Changelog for 1.0.16](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.15...v1.0.16)** #### 1.0.15 - June 11, 2026 **What's Changed** - Fix Codex steering and composer submission races — @provencher · #152↗ - Make MCP transport stderr diagnostics crash-safe on closed pipes — @provencher · #163↗ - Prepare RepoPrompt CE 1.0.15 — @baron · #165↗ **[Full Changelog for 1.0.15](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.14...v1.0.15)** #### 1.0.14 - June 11, 2026 **What's Changed** - Add Claude Fable 5 across Agent Mode model catalogs — @BetaFold3 · #142↗ - Harden MCP concurrency and workspace switching — @provencher · #155↗ - Prefer OpenCode provider path before native defaults — @fitchmultz · #148↗ - Model picker missing Z.ai options at startup — @moonray · #116↗ - Fix Cursor CLI Composer ACP routing — @baron · #126↗ - Prepare RepoPrompt CE 1.0.14 — @baron · #162↗ **New Contributors** - BetaFold3 made their first contribution. **[Full Changelog for 1.0.14](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.13...v1.0.14)** #### 1.0.10 - June 9, 2026 **What's Changed** - Harden runtime test coverage — @provencher · #111↗ - Fix Agent Mode capsule label compression — @provencher · #112↗ - Add worktree controls to agent_explore.start — @provencher · #113↗ - Fix ACP mode negotiation and OpenCode routing — @provencher · #97↗ - Prepare RepoPrompt CE 1.0.10 release — @provencher · #119↗ **[Full Changelog for 1.0.10](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.9...v1.0.10)** #### 1.0.9 - June 9, 2026 **What's Changed** - [codex] Avoid stale descriptor assertions in socket cleanup tests — @provencher · #91↗ - Fix onboarding Skip All routing — @fitchmultz · #93↗ - Fix branch popover scroll containment — @strickvl · #89↗ - Add Dock New Window menu item — @dah · #58↗ - Harden MCP response delivery, execution, and agent waiters — @provencher · #96↗ - Distinguish web tool card action labels — @strickvl · #68↗ - Refresh approved contributors — @provencher · #87↗ - Document Homebrew tap install path — @najibninaba · #88↗ - Add expanded file mention picker style — @aAtila · #95↗ - Fix local self-signed production packaging — @fitchmultz · #92↗ - Enforce custom hover tooltips — @provencher · #98↗ - Refresh SwiftPM release lockfile — @provencher · #99↗ - Add PR batch merge skill — @provencher · #100↗ - Optimize store-backed file search performance — @provencher · #104↗ - Fix Codex submit during agent wait drain — @provencher · #105↗ - Fix Git process output drain race — @provencher · #107↗ - Add lean test quality skill — @provencher · #106↗ - Fix conductor daemon stdin handling for local install — @dah · #103↗ - Prepare RepoPrompt CE 1.0.9 release — @provencher · #109↗ **New Contributors** - fitchmultz made their first contribution. - dah made their first contribution. **[Full Changelog for 1.0.9](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.8...v1.0.9)** #### 1.0.8 - June 7, 2026 **What's Changed** - Allow ad-hoc release manifests without designated requirements — @provencher · #83↗ - Fix warm Agent Mode tab activation — @provencher · #85↗ - Prepare RepoPrompt CE 1.0.8 release — @provencher · #86↗ **[Full Changelog for 1.0.8](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.7...v1.0.8)** #### 1.0.7 - June 7, 2026 **What's Changed** - [codex] Refresh approved contributors — @provencher · #67↗ - Harden flaky worktree CI tests — @strickvl · #72↗ - Refresh approved contributors — @provencher · #75↗ - Fix Keyboard Shortcuts settings crash — @strickvl · #73↗ - Fix stalls in long Agent Mode and Context Builder runs — @provencher · #74↗ - Document KeyboardShortcuts packaging workaround — @strickvl · #78↗ - Harden Keychain signing domains and MCP release packaging — @provencher · #80↗ - Prevent MCP frame starvation and lifecycle cleanup races — @provencher · #81↗ - Fix / improve Agent mode Git branch and worktree UI — @strickvl · #69↗ - Prepare RepoPrompt CE 1.0.7 release — @provencher · #82↗ **[Full Changelog for 1.0.7](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.6...v1.0.7)** #### 1.0.6 - June 4, 2026 **What's Changed** - Package CE releases with the CE bundle name — @provencher · #65↗ - Prepare RepoPrompt CE 1.0.6 release — @provencher · #66↗ - Add Agent Mode session row context menus — @strickvl · #60↗ - Add .worktreeinclude support for managed worktrees — @strickvl · #61↗ - Show Git worktree context in Agent sidebar — @strickvl · #62↗ **[Full Changelog for 1.0.6](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.5...v1.0.6)** #### 1.0.5 - June 4, 2026 **What's Changed** - Sync MCP CLI version during release prep — @provencher · #56↗ - Prepare RepoPrompt CE 1.0.5 release — @provencher · #63↗ **[Full Changelog for 1.0.5](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.4...v1.0.5)** #### 1.0.4 - June 3, 2026 **What's Changed** - Prepare RepoPrompt CE 1.0.4 release — @provencher · #55↗ - Harden signed test build workflow — @baron · #45↗ - Improve native Web Search tool cards — @HomunculusLabs · #50↗ - Fix `scripts/doctor.sh` SDK version detection — @strickvl · #53↗ **New Contributors** - baron made their first contribution. - HomunculusLabs made their first contribution. - strickvl made their first contribution. **[Full Changelog for 1.0.4](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.3...v1.0.4)** #### 1.0.3 - June 2, 2026 **What's Changed** - Prepare RepoPrompt CE 1.0.3 release — @provencher · #43↗ - docs(readme): document debug signing setup — @aAtila · #36↗ **New Contributors** - aAtila made their first contribution. **[Full Changelog for 1.0.3](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.2...v1.0.3)** #### 1.0.2 - June 2, 2026 **What's Changed** - Harden workspace file mutation paths — @provencher · #39↗ - Default-enable Codex goal support — @najibninaba · #33↗ - Harden OSS release validation — @provencher · #40↗ - Prepare RepoPrompt CE 1.0.2 release — @provencher · #41↗ **[Full Changelog for 1.0.2](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.1...v1.0.2)** #### 1.0.0 - June 1, 2026 ## RepoPrompt CE 1.0.0 RepoPrompt CE is a native macOS app for orchestrating coding agents with a focus on context engineering. It builds an agent harness around an MCP server, giving you a shared place to prepare repository context, connect compatible CLI agents, run focused tasks, and inspect the work they produce. The goal is simple: make it easier to give agents the right context and keep multi-step engineering work understandable. **Highlights** - Native macOS workspace for context engineering and agent orchestration. - MCP-based harness for integrating compatible CLI agents. - Repository-aware context selection, search, diffs, and worktree workflows. - Public Sparkle update channel for signed, notarized releases. - Fully open source and free to use. **Install The App** Download `RepoPrompt-1.0.0-1.dmg`, open it, and install `RepoPrompt CE.app` in your Applications folder. **First Public Release** This is the first RepoPrompt CE release. It starts a new `1.0.0` version line with its own bundle identifier, signing setup, and update channel. --- ## Do I Need an API Key? It depends on the connection you use. A coding-agent runtime can use its own account sign-in, while direct hosted API requests usually require an API credential. A local model server can provide another route. Use [Providers & Models](https://repoprompt.com/docs/providers/overview/) to choose the connection before obtaining a key. ### Does my coding subscription include API access? Do not assume so. Signing into a coding runtime does not automatically configure the same company's direct API. API usage, coding-plan allowances, and local inference have separate requirements. See [AI service costs](https://repoprompt.com/docs/faq/pay-for-services/) for the billing distinction. Oracle and Context Builder can use different connections from your execution session. A working coding-agent login therefore does not prove that every model feature is configured. ### Where do I add or remove a key? Use the corresponding provider's settings. [API Providers](https://repoprompt.com/docs/settings/api-providers/) documents direct-provider controls; [OpenRouter](https://repoprompt.com/docs/settings/openrouter/) and [Custom API](https://repoprompt.com/docs/settings/custom-api/) have their own pages. Runtime-specific credentials and login controls belong under [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/). You can configure several provider connections. This does not mean every provider supports multiple saved keys or automatic key rotation. Follow its actual controls. Deleting a saved key removes that local credential; revoke it with the issuing service if you intend to invalidate the key itself. ### Where are credentials stored and used? Official builds use local macOS Keychain-backed secure storage for credentials managed by the app. Coding runtimes can maintain separate login state. Ad-hoc debug builds use temporary secure storage; see [source-build behavior](https://repoprompt.com/docs/faq/how-to-build/). Credentials are used by the configured connection, including validation and model requests. Some integrations also pass a saved key to a child coding runtime; a custom endpoint receives requests routed to that endpoint. Local storage does not mean the credential never leaves the app process. The provider reference explains shared credentials and account boundaries. If a credential appears missing after an upgrade, use [Credential Recovery](https://repoprompt.com/docs/faq/credential-recovery/) before replacing it. Storage repair and successful authentication with the service are separate checks. --- ## How Do I Find the ChatGPT Pro Interface? For this workflow, use ChatGPT's browser conversation at [chatgpt.com](https://chatgpt.com). **ChatGPT Pro** is an account plan; it is not a separate RepoPrompt interface or a model name. A model or reasoning option labeled **Pro**, when offered, is a separate selection inside ChatGPT. Account access and labels can change, so confirm the option actually selected in your conversation. ### Why use it with RepoPrompt? Use a separate reasoning conversation for architectural planning, a difficult diagnosis, or a second review of a proposed change. RepoPrompt supplies focused code context; the receiving model can concentrate on the question rather than reconstructing the repository through a long series of searches. This is useful when you want an independent analysis before implementation. It can be slower than a quick response, and neither a paid plan nor a higher reasoning setting guarantees a better answer. Compare the result with the actual code and your acceptance criteria. OpenAI's [model-selection guidance](https://learn.chatgpt.com/docs/model-selection) explains the depth, speed, and usage tradeoff. ### Find it manually on chatgpt.com 1. Open [chatgpt.com](https://chatgpt.com) in your browser and sign in to the account with the access you intend to use. 2. Start a new conversation. If the interface offers **Chat** and **Work**, choose **Chat** for this question-and-answer workflow. You do not need to start a Codex task to paste a prepared prompt. 3. Open the conversation's model selector and inspect its model and reasoning choices. Use the displayed model control rather than assuming the account's Pro badge identifies the selected model. 4. If your account offers a **Pro** reasoning/model choice, select it explicitly. Otherwise, choose an available reasoning model suited to the task, or check your account/workspace access if you specifically need the Pro option. A missing choice is not evidence that a direct URL will unlock it. 5. Confirm the selected model and any reasoning setting before sending the prompt. Increase reasoning effort when deeper analysis is useful and the additional time and usage fit the task. OpenAI's [web quickstart](https://learn.chatgpt.com/docs/web) documents signing in, choosing Chat or Work, and model selection. The exact controls depend on your account and rollout; this guide does not promise a permanently named Pro menu item or fixed model release. ### Prepare and send the context In RepoPrompt, use **ChatGPT Export** to assemble a self-contained prompt, or use [Prepare and Copy Context](https://repoprompt.com/docs/agent-mode/context-composer/) to inspect the selected code, receiving-model instructions, and Git changes before copying. The [export workflow](https://repoprompt.com/docs/agent-mode/workflow-templates/#chatgpt-export) can produce a Markdown prompt under `prompt-exports/`; inspect the actual result before using it. Paste the prepared prompt into the browser conversation. Check that the instructions and code arrived intact and fit the receiving interface's limits. If they do not fit, reduce irrelevant context rather than assuming a Pro plan accepts an unlimited repository. Send a concrete analysis request, for example: > Review the attached context and propose an implementation plan. Identify assumptions, affected files, risks, and verification steps. Do not implement changes. Ask for missing code rather than inventing its behavior. Use context you are permitted to share with that service. Pasting the export does not connect the conversation to your live checkout or automatically send later file changes. ### Bring the result back to RepoPrompt Read the analysis, resolve open questions, and copy the useful plan or findings into the intended RepoPrompt session. Include the source context and note any repository changes made since export. For a long plan, save it as a project document and tell the coding agent which file to read. Ask the coding agent to verify the analysis against the current checkout before implementing it. For example: “Check this plan against the current code, flag mismatches, then implement the agreed changes and run the permitted checks.” Review the resulting diff and validation evidence. ChatGPT's answer does not itself apply edits, merge a worktree, or prove the implementation works. ChatGPT account access, API billing, and RepoPrompt's provider connections are separate. See [AI Service Costs](https://repoprompt.com/docs/faq/pay-for-services/) and [Models](https://repoprompt.com/docs/providers/models/) for those distinctions. --- ## How Can I Contribute? You can help with reproducible bug reports, documentation corrections, focused code changes, and tested improvements. Start with the repository responsible for the change; application and documentation contributions follow separate policies. ### Contribute to the application Read the [application contribution guide](https://github.com/repoprompt/repoprompt-ce/blob/main/CONTRIBUTING.md) before opening an issue or pull request. The current guide describes a contribution gate: issues from accounts without issue approval and pull requests from accounts without PR approval are closed automatically. Maintainers may review and reopen worthwhile issues. The tracked approved-contributor list distinguishes issue approval from PR approval; neither grants repository access. Follow the policy's approval process rather than repeatedly reopening or duplicating a closed submission. Historical customer status alone is not a substitute for checking the project's current rules. For code changes, read the application's `AGENTS.md`, keep the patch focused, and run the relevant checks required by that repository. Include what changed, why, and validation results. AI-assisted work is welcome under the contribution guide, but you should understand and be able to explain the code you submit. Do not include raw generated investigation or prompt dumps as a substitute for a clear change description. See [How to Build](https://repoprompt.com/docs/faq/how-to-build/) if you need a local development environment. ### Improve the documentation Correct an inaccurate step, explain a missing workflow, improve accessible image descriptions, or fix a broken link. Use the documentation repository's contribution guide for its process. Substantial rewrites and new sections should be discussed there first; small corrections can go directly to a focused pull request. Edit the current documentation collection and verify instructions against application source or the relevant interface. Keep Classic archived, link shared provider facts to Providers & Models, and prefer capabilities over release-specific model lists. Include the affected page and how you checked the correction. ### Not ready to write a patch? A minimal reproduction, a precise documentation correction, or a well-scoped proposal can be useful on its own. Follow [Issue and Feature Request guidance](https://repoprompt.com/docs/faq/report-issue/) so the report reaches the right project with enough information to assess it. --- ## Recover Credentials After an Upgrade If a previously saved API credential appears missing after upgrading an official build, it may still exist in the older Keychain service. RepoPrompt provides an explicit repair flow; it does not scan legacy accounts automatically at startup. This flow repairs known secure-storage accounts. It does not sign a CLI runtime into its provider, renew a subscription, or grant API access. First identify the connection in [Providers & Models](https://repoprompt.com/docs/providers/overview/), especially when the same company offers separate CLI and API products. The legacy service targeted by this repair belongs to earlier RepoPrompt CE builds; it is not a general Classic import. For that transition, see [Migrating from Classic to RepoPrompt CE](https://repoprompt.com/docs/faq/migrate-from-classic/). ### Inspect known legacy accounts 1. Open **Settings → Models & Providers → API Providers**. 2. Under **Legacy secure storage repair**, choose **Review…**. 3. Choose **Scan Known Accounts**. Scanning is noninteractive; importing a selected account may subsequently request macOS Keychain approval. 4. Read the status for the intended account before choosing an action. **No legacy value** means that scan did not find a value for that known account; it does not prove that the credential never existed elsewhere. **Ready to import** and **Import may require Keychain approval** identify accounts you can attempt to import. ### Import without replacing a current value Choose **Import** for the relevant account and respond to any Keychain prompt. A successful import reports **Imported and verified**. Legacy values are retained by default so that an older build can still use them. If the status says **A different v2 value already exists**, automatic replacement is withheld. **Replace v2…** opens a separate confirmation. Replace only when you intend to overwrite that account's current stored value; the legacy value is still retained. “Verified” describes the storage repair result. Check the relevant provider's connection or validation control separately to confirm that the credential still works with the service. ### Cancelled or failed imports **Import was cancelled** and **Repair failed; retry this account** allow another import attempt. Read the reported state, check whether a Keychain request needs attention, and retry the affected account. **Rescan** refreshes the known-account list. If no usable legacy value is available, re-enter the credential using the appropriate [provider guide](https://repoprompt.com/docs/providers/overview/). ### Keep rollback possible After a verified import, **Delete Legacy…** may be available. Its confirmation explains that deleting the old value can make a return to an older build require re-entry. Deletion is optional and separate from importing; leave the legacy value in place when you still need rollback access. For a locally built app, check [How to Build](https://repoprompt.com/docs/faq/how-to-build/) as well: ad-hoc debug builds use temporary secure storage, so losing saved credentials after quitting can be expected for that build type rather than an upgrade migration failure. --- ## How can I build the application? RepoPrompt is a native macOS application. To build it from source, use the public [RepoPrompt CE repository](https://github.com/repoprompt/repoprompt-ce). ### Requirements - macOS 26 or later. - Xcode 26 or later, installed as the full `Xcode.app`. The Command Line Tools package alone is not enough because the app and its dependencies use Swift macros shipped with Xcode. - Python 3 for the Finder launchers and generated Xcode workflow. From Terminal, clone the repository and check the build toolchain: ```bash git clone https://github.com/repoprompt/repoprompt-ce.git cd repoprompt-ce ./Scripts/doctor.sh ``` The doctor script checks whether the required development tools are available. Resolve any reported Xcode or SDK issue before building. ### Build and launch a debug app For a quick local build, double-click **Launch RepoPrompt CE.command** in Finder. The launcher builds the debug app, opens it, and leaves a small Terminal window available for rebuild and stop controls. It requires Python 3 and coordinates build and launch operations through the repository's developer daemon. If your Mac has an Apple Development signing identity, the launcher uses it. Without one, you can build and launch from Terminal with explicit ad-hoc signing: ```bash ALLOW_ADHOC_SIGNING=1 ./conductor app relaunch ``` Ad-hoc debug builds use temporary in-memory secure storage. API keys and secure permission changes do not persist after the app closes. To use persistent Keychain storage for local development, set your installed Apple Development identity: ```bash SIGN_IDENTITY="Apple Development: Your Name (TEAMID)" ./conductor app relaunch ``` Replace the example identity with one installed on your Mac. You can list available signing identities with `security find-identity -v -p codesigning`. ### Open the project in Xcode Generate and open the disposable contributor workspace from the repository root: ```bash make xcode ``` The generated workspace lives in `.build/xcode/RepoPromptCE.xcworkspace`; it is derived output and should not be edited or committed. In Xcode, use the **RepoPrompt CE App** scheme to build and run the packaged debug application. The **RepoPrompt CE MCP** scheme builds the coordinated MCP executable. The **RepoPrompt CE Tests** scheme delegates tests to the repository's conductor workflow. For generation, validation, cleanup, and scheme details, see the repository's [Generated Xcode Workspace guide](https://github.com/repoprompt/repoprompt-ce/blob/main/docs/architecture/xcode-workspace.md). ### Install a local release-mode build To build and install a release-mode app locally, install Python 3 and double-click **Install RepoPrompt CE Local Production.command** in Finder. It builds from source and replaces `/Applications/RepoPrompt CE.app` with a locally signed app. macOS may ask you to approve the local self-signed certificate. This local build is not notarized. Keep it on your Mac; it is not the distribution method for another computer. For the signed, notarized public application, follow the repository's [Homebrew installation instructions](https://github.com/repoprompt/repoprompt-ce#install-with-homebrew), which install the released app rather than building from source. ### Troubleshooting - If the toolchain check fails, install or select a full Xcode 26+ installation and run `./Scripts/doctor.sh` again. - If the debug app cannot sign, use the explicit ad-hoc command above or configure an Apple Development identity. - If an ad-hoc build appears to lose saved API keys or secure permission changes, that is expected: ad-hoc builds use ephemeral secure storage. - If you need more build detail, see the repository's [README build instructions](https://github.com/repoprompt/repoprompt-ce#build-and-launch-locally) and [contributor guide](https://github.com/repoprompt/repoprompt-ce/blob/main/AGENTS.md). ### Build Tip code with Xcode Tip Builds follow development on the repository's `main` branch. To build that code locally, start with a fresh clone of the repository, or update an existing clean checkout to the latest `main`. If you want to reproduce the source used for a particular published Tip Build, check out the commit identified in that release before generating the workspace. From the repository root, run `make xcode` to generate and open the contributor workspace. In Xcode, select the **RepoPrompt CE App** scheme and the **My Mac** destination, then choose **Product → Run** to build and launch the packaged debug app. Use the same macOS, full Xcode, Python, and signing requirements described above. After updating your checkout, run `make xcode` again to regenerate the workspace for that source revision. This gives you a local development build of the Tip source. The official Tip distribution is signed and notarized by the project's release workflow; Xcode's contributor workspace builds the debug app and does not perform that release packaging. To install the published Tip Build instead, follow [Installing Tip Build](https://repoprompt.com/docs/overview/installation/#installing-tip-build). --- ## Why Is My MCP Connection Not Working? Start by identifying the symptom. Installing an MCP connection, authenticating a coding runtime, and configuring an Oracle model are separate operations. A failure in one does not necessarily mean the others are broken. ### The client cannot find the executable Copy configuration from the running RepoPrompt CE app using **Quick Setup** or **Settings → MCP Server**. Confirm that the generated command path exists and belongs to the intended release or debug build. Do not reuse a Classic executable path. If the CLI Tools row reports **Needs update**, use **Update**, then reconnect the client. Follow the [Setup Guide](https://repoprompt.com/docs/mcp-server/mcp-setup/) for installation and a connection check. Installing workflow instructions alone does not install the MCP server connection. ### The executable starts, but the client cannot connect Keep RepoPrompt open and enable MCP access for the intended window. **Active** indicates that the listener and that window's access are ready; **Waiting for listener…** does not. Bring the app forward to inspect any pending connection request, then check **Status Dashboard** and its errors. The app-backed bridge uses local UNIX sockets. Changing a firewall, VPN, or TCP port is not the first troubleshooting step for this path. See [Transport Modes](https://repoprompt.com/docs/mcp-server/mcp-transport/) and [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/#troubleshooting-connections). ### The client connects, but tools are missing Check window access and [MCP Tools settings](https://repoprompt.com/docs/settings/tools/). Disabled tools and connection policy affect the advertised list; some tools are available only in eligible session contexts. Reconnect a client that cached an earlier tool list. A connection approval is not a blanket grant for all tools or workspace mutations. ### Tools use the wrong project or conversation Use `bind_context` with `op="list"` to discover contexts and `op="status"` to inspect the binding. Bind the intended workspace roots or a returned context ID. Switching the visible tab does not reliably replace an explicit connection binding. See [Context Binding](https://repoprompt.com/docs/mcp-server/mcp-connections/#context-binding). Multiple clients and windows are supported. Diagnose their bindings rather than disconnecting every other client as a general rule. ### Oracle or Context Builder fails after connection Check the selected model connection, authentication, and provider response. [Agent Models](https://repoprompt.com/docs/settings/agent-models/) configures Oracle and discovery choices; they need not use the same connection. Use the current [Tools Reference](https://repoprompt.com/docs/mcp-server/mcp-tools/), rather than Classic examples for obsolete planning tools. If the failure persists, record the exact error, app version, client, and a minimal reproduction. Follow [Issue Reporting](https://repoprompt.com/docs/faq/report-issue/); remove credentials and private repository content from shared diagnostics. --- ## How Do I Safely Migrate from Classic to RepoPrompt CE? Treat the move as setting up a different application and verifying the workflows you need. RepoPrompt CE is the active community codebase, but it is not a feature-for-feature replacement for Classic. Keep your working Classic setup and backups until you have confirmed that RepoPrompt meets your needs. ### The simple answer: Ask your favorite AI harness to do it for you. Or... ### 1. Preserve your work before changing anything Finish or stop active coding sessions, then back up your project folders, including uncommitted work and local files you need. A Git commit does not preserve ignored files, application settings, or credentials. Quit Classic before copying its application data. Preserve its installed app, saved workspace data, custom storage location if you use one, and custom prompts or workflow files. Keep a macOS backup that includes the Keychain rather than copying secrets into a plaintext migration note. Record which features and external clients you rely on. The [Classic documentation archive](https://repoprompt.com/docs/classic-2.1.0/) remains available for reference. Its **Classic 2.1.0** label is an archive label, not necessarily the version of your installed application. ### 2. Install RepoPrompt and start with one project Follow [Installation](https://repoprompt.com/docs/overview/installation/) and start with the Stable channel unless you specifically need a Tip change. Keep the Classic installation available while evaluating RepoPrompt. Check that you launched the intended app before changing settings or reconnecting clients. Do not replace RepoPrompt CE's application-data directory with Classic's directory or assume that copying a preferences file migrates every workspace, conversation, and setting. RepoPrompt CE's preference and storage migrations serve specific schemas and application identities; they are not a general guarantee of Classic compatibility. ### 3. Reconnect providers and credentials Use [Providers & Models](https://repoprompt.com/docs/providers/overview/) to configure the coding runtime and the model connections your workflow needs. Check Oracle and Context Builder choices separately. A working CLI login does not automatically configure direct API access. [Credential Recovery](https://repoprompt.com/docs/faq/credential-recovery/) covers known legacy RepoPrompt CE accounts only; it does not import Classic credentials. When moving from Classic, authenticate with the provider through [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/), or re-enter your API credential through [API Providers](https://repoprompt.com/docs/settings/api-providers/), as appropriate for your connection. :::warning[Protect your credentials] API keys and tokens can grant access to your accounts and paid services. Do not paste them into AI conversations, public issues, screenshots, or plaintext migration notes. Use the provider's sign-in flow or the intended credential field in Settings. If a credential is exposed, revoke it with the provider and create a replacement. ::: Validate the connection before changing or removing old credentials. Keep legacy values while you still need rollback access; deleting a local key is different from revoking it with the provider. :::warning[Use caution with macOS Keychain] Do not reset your Keychain, delete unrelated entries, or broaden access permissions to complete this migration; those changes can affect other applications and accounts. Check the requesting application and intended item before approving access. If you are unsure, cancel and use the provider's current sign-in or credential-entry controls instead. ::: ### 4. Reconnect external tools and review custom prompts Generate a new MCP configuration from the RepoPrompt app for each external client. Follow [MCP Setup](https://repoprompt.com/docs/mcp-server/mcp-setup/), rather than reusing Classic executable paths or command examples. Check which integration is enabled, verify the RepoPrompt connection, and bind the intended project before asking the client to work. Avoid letting Classic and RepoPrompt sessions edit the same checkout at the same time. Install the matching RepoPrompt [workflow instructions](https://repoprompt.com/docs/mcp-server/workflow-commands/) when needed; connecting MCP alone does not install their skill folders or prompt files. Review custom prompts for old tool names, XML-editing instructions, paths, and assumptions about Classic features. RepoPrompt has **Import Prompts** and **Export Prompts** under [Advanced → Saved Prompts](https://repoprompt.com/docs/settings/advanced/#saved-prompts). Import requires a compatible format; it is not a whole-application restore. Preserve the original export, inspect imported content, and copy prompt text manually if the old format is unsupported. Recreate the settings you need instead of assuming every old preset has an equivalent. ### 5. Verify a small workflow Start with a bounded request such as explaining a function without editing files. Confirm the selected provider, project path, returned context, and any usage charges. Then try a small, isolated change and inspect its diff and validation results. Check the features you actually use: [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/), [Oracle](https://repoprompt.com/docs/faq/what-is-an-oracle/), [manual context copying](https://repoprompt.com/docs/agent-mode/context-composer/), and [approval behavior](https://repoprompt.com/docs/agent-mode/approvals/). Keep Classic for a workflow you still need if RepoPrompt does not provide an equivalent. ### 6. Retire the old setup only after verification Once your normal work succeeds in RepoPrompt, you can remove obsolete client integrations and decide whether to retain the Classic app. Keep dated backups of its data and exported prompts. Uninstalling an app is not a substitute for checking which configurations and credentials your external tools still use. If you return to Classic, use its preserved data or backup; do not overwrite it with RepoPrompt data and assume backward compatibility. Project-file changes remain project changes regardless of which app created them. Review or restore those separately. RepoPrompt does not require an old paid license. See [What Happened to the Paid Version?](https://repoprompt.com/docs/faq/paid-version/) for the transition history and [Issue Reporting](https://repoprompt.com/docs/faq/report-issue/) if a reproducible migration problem remains. --- ## What Happened to the Paid Version of RepoPrompt? RepoPrompt moved from the paid Classic product to a free, open-source Community Edition. The founder's [transition announcement](https://repoprompt.com/blog/repo-prompt-next-chapter/) states that Classic's licensing restrictions were removed in the **2.1.32 update** and that all then-current subscriptions were cancelled. Community Edition itself does not require an old Classic license or a new RepoPrompt subscription. ### What should I install now? For the current community application, follow [Installation](https://repoprompt.com/docs/overview/installation/). The [Community Edition launch announcement](https://repoprompt.com/blog/repo-prompt-community-edition/) links the active RepoPrompt CE repository and the archived Classic source and download. If you already use Classic, follow [How Do I Safely Migrate from Classic to RepoPrompt CE?](https://repoprompt.com/docs/faq/migrate-from-classic/) before replacing your setup. Classic remains an archived product, not the current RepoPrompt CE interface. The documentation label **Classic 2.1.0** identifies the archive; it is not a claim that Classic stopped at that application version. Use the documentation appropriate to the app you installed. ### Does RepoPrompt include every feature from the paid app? Do not assume feature-for-feature equivalence. RepoPrompt CE concentrates on context engineering and coding-agent workflows; the launch announcement describes the removal of legacy features. Consult current guides for a specific workflow rather than treating an old purchase, screenshot, or tutorial as a current feature list. ### Why might I still pay for AI usage? Removing RepoPrompt's application subscription did not make external services free. Coding-runtime plans, API usage, and other services have their own terms and billing. See [Do I Need to Pay for AI Services?](https://repoprompt.com/docs/faq/pay-for-services/) and the [provider directory](https://repoprompt.com/docs/providers/overview/) for those account boundaries. For current participation and support, see [Who Maintains RepoPrompt?](https://repoprompt.com/docs/faq/solo-project/). --- ## Do I need to pay for AI services? RepoPrompt is free and open source. AI usage depends on the connection you choose: a coding-agent account, an API credential, or a model server you operate. ### What RepoPrompt charges RepoPrompt does not charge for the application or add a markup to provider bills. You supply the relevant account or service. Its terms, quotas, pricing, and data practices apply to requests sent through that route. A CLI subscription does not automatically pay for direct API requests, and an API key does not establish access to a separate subscription product. Check which account and connection the task actually uses. For the transition from the former application subscription, see [What Happened to the Paid Version?](https://repoprompt.com/docs/faq/paid-version/). For credentials, see [Do I Need an API Key?](https://repoprompt.com/docs/faq/api-keys/). ### Supported AI providers The [Providers & Models directory](https://repoprompt.com/docs/providers/overview/) maintains the supported coding-agent, API, compatible-backend, and local-service references. Each provider page explains prerequisites, authentication, capabilities, account boundaries, and billing distinctions. #### Provider setup and current model catalogs Use the provider's reference page for its connection instructions and official catalog links. [Models](https://repoprompt.com/docs/providers/models/) explains discovery, availability, aliases, effort, and how selections differ between execution, Oracle, and Context Builder. Model names and prices change, so this FAQ does not maintain a second catalog. ### How to keep costs predictable - Inspect the provider account that owns the login or API key and review its current pricing, quotas, and billing controls. - Keep context focused and choose a capability level suited to the task. A workflow can make several model requests, including discovery, consultation, or draft rewriting. - Review paid speed tiers and automatic follow-up features before using them for extended tasks. - For [local models](https://repoprompt.com/docs/providers/local-models/), confirm that inference actually stays local and account for hardware and electricity use. A local server can also be configured to call a hosted route with separate charges. ### What is free and what is not The application is free. AI access is free only when the selected service, account, model, and usage are free under its current terms, or when inference runs locally without a hosted API bill. RepoPrompt cannot guarantee a provider's free allowance or subscription entitlement. --- ## How Do I Report an Issue or Submit a Feature Request? Search for an existing report first. Add useful reproduction details to a matching issue rather than creating duplicates. Then choose the project responsible for the problem. ### Application bugs and feature requests Use the [RepoPrompt CE application issue tracker](https://github.com/repoprompt/repoprompt-ce/issues). Read its [contribution policy](https://github.com/repoprompt/repoprompt-ce/blob/main/CONTRIBUTING.md) first: the project automatically closes issues from accounts without issue approval. An automatic closure can reflect that gate rather than a decision on the report's technical merits; maintainers may review and reopen worthwhile submissions. Do not assume that opening a public issue bypasses the gate. For a bug, include: - The app version/build, Stable or Tip channel, and macOS version. - Steps to reproduce, what you expected, and what happened. - The affected feature and provider/runtime when relevant. - The exact error and a small example or redacted screenshot that demonstrates it. For a feature request, describe the user problem, the current workaround, and a concrete example of the desired outcome. Explain why the existing workflow does not address it. A request starts a discussion; it does not establish a release commitment. ### Documentation or website problems Use the documentation issue tracker for incorrect instructions, broken links, confusing explanations, screenshots, and website behavior. Include the page URL, documentation version, and the exact sentence or step. Add browser/device details for a display problem and app-version details for an application instruction. The documentation repository has its own participation rules; application contributor approval does not automatically describe its process. See [How Can I Contribute?](https://repoprompt.com/docs/faq/contributing/) if you want to submit a correction. ### Security problems and exposed credentials Report suspected vulnerabilities privately through the affected repository's **Security → Report a vulnerability** flow, following its security policy. Do not put credentials, private project content, or exploit details in a public issue. If private reporting is unavailable, ask a maintainer to enable a private channel without disclosing the sensitive details publicly. For a connection problem, first try [MCP Troubleshooting](https://repoprompt.com/docs/faq/mcp-troubleshooting/). For a paused coding session, see [Approvals and Paused Sessions](https://repoprompt.com/docs/agent-mode/approvals/). Community support has no guaranteed response time. --- ## Who Maintains RepoPrompt? RepoPrompt began as a solo project, but the Classic answer “RepoPrompt is currently a solo project” does not describe Community Edition's maintenance model. RepoPrompt CE is developed through the community repository, where maintainers review contributions and the project records its participation rules. The founder's [transition announcement](https://repoprompt.com/blog/repo-prompt-next-chapter/) explains the move away from daily stewardship. The [Community Edition announcement](https://repoprompt.com/blog/repo-prompt-community-edition/) identifies the open-source repository as the active development home and invites community participation. ### Where should I go for help? Use the [application repository](https://github.com/repoprompt/repoprompt-ce) for application behavior, source builds, and feature proposals. Documentation corrections belong with the documentation project. Read [Issue Reporting](https://repoprompt.com/docs/faq/report-issue/) before submitting, including the application's contributor-approval policy. Support is community-based, with no guaranteed response time. See [the paid-version FAQ](https://repoprompt.com/docs/faq/paid-version/) for what the transition announcement says about licensing and subscriptions. ### Can I participate? Yes, subject to the relevant repository's contribution rules. See [How Can I Contribute?](https://repoprompt.com/docs/faq/contributing/) for focused ways to help and the difference between application and documentation contributions. Maintainer roles and contributor approval are governed by the project, rather than a permanent team-size claim in this FAQ. --- ## What Is the Tip Version and Should I Use It? **Tip Builds** are official signed and notarized builds from the latest passing main branch. They make development changes available before the next curated Stable release. **Stable** is the default update channel. ### Which should I choose? Use Stable for routine work when you do not need a particular development change. Consider Tip when you want to try a recent fix or feature, help test ongoing development, and can tolerate regressions or changing behavior. A passing build and notarization do not guarantee that every workflow is free of bugs. Tip is a distribution channel, not a different subscription or an included model plan. A locally compiled source build is also different from the official signed Tip distribution; see [How to Build](https://repoprompt.com/docs/faq/how-to-build/). ### How do I install it? Install and launch RepoPrompt, then open **Settings → General → Updates**. Change **Update Channel** to **Tip Builds**, choose **Check for Updates**, and follow the updater's prompts if an eligible build is offered. Changing the selector or checking alone does not establish that a new version was installed. Read the offered build information and preserve work you need before changing versions. If you report a regression, include the exact build and Tip channel in the [issue report](https://repoprompt.com/docs/faq/report-issue/). ### How do I return to Stable? Set **Update Channel** back to **Stable**. The updater switches with the next applicable Stable release; it does not necessarily downgrade an installed Tip build immediately. To return immediately, reinstall the Stable app using the official installation or recovery download path. Reinstalling the application is separate from reverting repository changes or migrating saved application data. Do not delete workspace data or Keychain entries merely to switch channels. See [Software Updates](https://repoprompt.com/docs/settings/updates/) for channel controls and [Installation](https://repoprompt.com/docs/overview/installation/) for getting the application. --- ## Are There Videos to Watch? Yes. Start with a guided walkthrough, choose a topic from the **RepoPrompt 101** playlist, or watch the **Rate Limited** podcast for broader discussions about AI-assisted coding. :::warning[The software is way past this recording] Many of these videos and podcast episodes are several months old (if not longer), and RepoPrompt has come a long way since they were recorded. The fundamentals remain useful, but the recordings include Classic Edition interfaces, earlier workflow names, and older model releases. Use them to understand the ideas and see examples, then follow [Getting Started](https://repoprompt.com/docs/overview/getting-started/), [Going Deeper](https://repoprompt.com/docs/overview/going-deeper/), and [Providers & Models](https://repoprompt.com/docs/providers/overview/) for current instructions, controls, and supported connections. ::: ### Start with a guided walkthrough **[Ray Fernando: Repo Prompt — Why Is Nobody Talking About This?](https://www.youtube.com/watch?v=G8TLeEdcdAM)** · About 11 minutes Ray takes a project through setup and a refactoring workflow. The demonstration shows repository exploration, planning, and concurrent implementation agents working through connected coding runtimes. Watch this when you want to see how the pieces fit together before trying your own task. :::tip[Learn the flow, then follow the current guide] This walkthrough is several months old. RepoPrompt's setup and workflows have developed substantially since then, so follow the current installation guide for the exact steps while using the video to learn the overall flow. ::: Useful places to jump in: - [0:57 — Setup wizard](https://www.youtube.com/watch?v=G8TLeEdcdAM&t=57s): connect the tools used in the demonstration. - [3:34 — Refactoring a project](https://www.youtube.com/watch?v=G8TLeEdcdAM&t=214s): move from setup to a concrete coding task. - [5:03 — Repository exploration](https://www.youtube.com/watch?v=G8TLeEdcdAM&t=303s): see how the discovery stage gathers context. - [8:38 — Concurrent implementation](https://www.youtube.com/watch?v=G8TLeEdcdAM&t=518s): follow more than one coding agent working on the task. For the written path, start with [Installation](https://repoprompt.com/docs/overview/installation/), then complete the four steps in [Getting Started](https://repoprompt.com/docs/overview/getting-started/). ### Workflow demonstration **[Eric Provencher: Orchestrate with RepoPrompt](https://www.youtube.com/watch?v=5YNOxxdSHVk)** · About 14 minutes The founder's demonstration follows the coordination side of a coding task: connecting runtimes, building context, delegating work, steering agents, consulting an Oracle, and reviewing the result. It is also part of the RepoPrompt 101 playlist below. :::warning[Earlier interface and capabilities] The recording shows the software as it worked several months ago. Context preparation, delegation, and review are still central ideas, but the current app has progressed well beyond the interface and capabilities shown here. ::: Choose the part that matches what you want to learn: - [0:48 — Coding-runtime connections](https://www.youtube.com/watch?v=5YNOxxdSHVk&t=48s). - [2:13 — Preparing context](https://www.youtube.com/watch?v=5YNOxxdSHVk&t=133s). - [3:27 — Delegating work](https://www.youtube.com/watch?v=5YNOxxdSHVk&t=207s). - [5:57 — Steering active agents](https://www.youtube.com/watch?v=5YNOxxdSHVk&t=357s). - [8:32 — Consulting an Oracle](https://www.youtube.com/watch?v=5YNOxxdSHVk&t=512s). - [11:08 — Reviewing work](https://www.youtube.com/watch?v=5YNOxxdSHVk&t=668s). Use [Going Deeper](https://repoprompt.com/docs/overview/going-deeper/) for a current, step-by-step workflow and [Agent Mode Overview](https://repoprompt.com/docs/agent-mode/overview/) to identify the interface controls. ### Explore RepoPrompt 101 by topic **[Open the complete RepoPrompt 101 playlist](https://www.youtube.com/playlist?list=PLFg9suyZ1OnLh3Tv5bP6jvWXcKKTlI_4m)** for Eric Provencher's feature demonstrations. You can watch the series or choose an individual topic below. Durations are approximate. :::tip[Use the lessons for fundamentals] These lessons were recorded at different stages of RepoPrompt's development, many months ago. Treat them as explanations of the fundamentals rather than a complete tour of today's software; use the linked written guides for current features and settings. ::: #### Purpose and context preparation - **[What RepoPrompt is for](https://www.youtube.com/watch?v=ncY6cqOCd_Y)** · 17 minutes. A broader introduction to the problems RepoPrompt addresses and where it fits into AI-assisted coding. - **[Context Builder walkthrough](https://www.youtube.com/watch?v=qHl116OG2DM)** · 3 minutes. A short demonstration focused on preparing repository context with Context Builder. - **[Keeping an agent grounded](https://www.youtube.com/watch?v=amaYBcjz6Ck)** · 10 minutes. An explanation of how repository context helps keep an agent's work connected to the codebase. - **[Helping an agent get oriented](https://www.youtube.com/watch?v=9tQijoWr-QM)** · 3 minutes. A focused look at getting a coding agent familiar with a repository. Read [How Context Works](https://repoprompt.com/docs/overview/how-it-works/) for the written explanation, or open [Context Builder settings](https://repoprompt.com/docs/settings/context-builder/) for its controls. #### Agent workflows and iteration - **[Agent workflow overview](https://www.youtube.com/watch?v=9v87dJijk9c)** · 5 minutes. A brief tour of RepoPrompt's approach to supporting coding agents. - **[Fitting RepoPrompt into an existing workflow](https://www.youtube.com/watch?v=060MqOx-Ex0)** · 3 minutes. Guidance on using RepoPrompt alongside an agent workflow you already have. - **[Rapid iteration](https://www.youtube.com/watch?v=LSQBi0Vx3Y4)** · 4 minutes. A demonstration focused on working through successive changes with RepoPrompt. The longer [workflow demonstration](https://repoprompt.com/docs/faq/videos/#workflow-demonstration) covers orchestration. See [Workflow Templates](https://repoprompt.com/docs/agent-mode/workflow-templates/) for the current workflow choices. #### Oracle consultations and code review - **[Giving an MCP-connected agent an Oracle](https://www.youtube.com/watch?v=hdaOxCE-dbI)** · 7 minutes. A demonstration of adding Oracle consultation to an external coding agent through RepoPrompt's MCP tools. - **[Code review through ChatGPT](https://www.youtube.com/watch?v=pgLHMOFQ_sA)** · 5 minutes. A focused review workflow using ChatGPT. The model shown is an example from the recording; check [Providers & Models](https://repoprompt.com/docs/providers/overview/) for current options. For the written references, see [What Is an Oracle?](https://repoprompt.com/docs/faq/what-is-an-oracle/), [MCP Setup](https://repoprompt.com/docs/mcp-server/mcp-setup/), and [MCP Tools](https://repoprompt.com/docs/mcp-server/mcp-tools/). ### Watch or listen to Rate Limited **[Rate Limited on YouTube](https://www.youtube.com/@ratelimitedpod)** brings together Eric Provencher, Ray Fernando, and Adam Larson, also known as Gosu Coder, for discussions about AI-assisted coding. Choose this for longer conversations about how developers use agents, rather than a step-by-step RepoPrompt lesson. Topics include: - **Working with agents:** workflow design, coordination, review, and the engineer's role. - **Context and reliability:** context limits, compaction, tools, and keeping a task on track. - **Provider tradeoffs:** model capabilities, subscriptions, pricing, and rate limits. :::warning[Discussions reflect the time of recording] Many episodes are several months old. Their discussions of context, coordination, and reviewing AI-generated work remain useful, but RepoPrompt and the surrounding AI tools have advanced substantially since those conversations. Episode titles identify the topic being discussed. Product names, prices, and opinions reflect the time of recording; use the current documentation when making a setup or provider choice. ::: ### Prefer written instructions? YouTube may offer captions, transcripts, and chapter navigation, depending on the recording. Use those controls when available. The written guides are the current alternative for following the workflow at your own pace: - [Getting Started](https://repoprompt.com/docs/overview/getting-started/): complete a first task in four steps. - [Going Deeper](https://repoprompt.com/docs/overview/going-deeper/): explore the workflow and optional techniques in more detail. - [Agent Mode Overview](https://repoprompt.com/docs/agent-mode/overview/): find the controls in the main interface. - [Providers & Models](https://repoprompt.com/docs/providers/overview/): check current connections and capabilities. --- ## What Is an Oracle? An **Oracle** is a model consultation that helps you or your coding agent think through a problem using prepared project context. It returns analysis: an implementation plan, a code review, an explanation, or a second perspective on a difficult decision. Think of it as asking a reviewer who has been given the relevant code and a clear question. The value comes from both the model's reasoning and the context it receives. ### How is it different from the coding agent? The execution coding agent carries out the task: it searches the repository, edits files, and runs permitted tools. The Oracle reasons over the context supplied to its consultation and returns an answer. Consulting it does not automatically apply changes or replace the execution model in your session. An Oracle is a role in the workflow, not a particular model brand. You can choose its model separately from the model doing the coding. See [Models and their roles](https://repoprompt.com/docs/providers/models/#model-roles). ### When would I use one? - **Before a substantial change:** ask for a plan that considers existing interfaces, dependencies, and constraints. - **During an investigation:** ask it to explain how the selected code could produce a particular failure. - **Before accepting a change:** ask for a review of the diff together with the surrounding implementation. - **When an approach is uncertain:** ask it to compare alternatives and identify assumptions that need checking. For example: “Review this change for cancellation bugs. Use the selected implementation and callers to explain any findings, and identify missing context before drawing conclusions.” ### Where does its context come from? The consultation uses a prepared package that can include selected files, Code Maps, instructions, conversation context, and relevant Git changes. [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/) can discover and assemble the code before an Oracle analyzes it. Discovery and analysis are separate stages; they can use different models. The Oracle does not automatically know your entire repository. If an answer overlooks an important dependency, inspect the supplied context, add what is missing, and ask a focused follow-up. ### How do I configure it and read the answer? Choose the Oracle model in **Settings → Agent Mode → Agent Models**. You can configure additional Oracles for independent perspectives; their answers remain separate, so compare their reasoning rather than assuming agreement or automatic synthesis. The brain-shaped **Oracle** control above the session editor opens the associated consultations. They can be created by a workflow, a coding-agent request, or a Context Builder analysis follow-up. Follow the [Oracle interface guide](https://repoprompt.com/docs/agent-mode/oracle/) for the controls and [Agent Models settings](https://repoprompt.com/docs/settings/agent-models/) for configuration. Bring useful findings back into the coding task, verify them against the current code, and review the resulting changes. An Oracle answer is advice, not proof that a change is correct. Consultations also use the selected provider's allowance or billing; see [AI Service Costs](https://repoprompt.com/docs/faq/pay-for-services/). --- ## Does RepoPrompt Run on Windows or Linux? The RepoPrompt desktop application documented here is a native macOS app. These installation and interface instructions do not describe an official Windows or Linux desktop release. ### Does open source mean it runs on every platform? No. The application uses macOS interfaces and services. Making source code available lets contributors adapt it, but it does not establish that the complete app builds or behaves the same way on another operating system. Community experiments and package-level portability work are different from a supported desktop distribution. Check the project's actual release artifacts before treating a port as available. This FAQ does not promise a port or a release date, and the old Classic waitlist is not the installation path for RepoPrompt CE. ### Can I use the CLI instead? The documented app-backed `rpce-cli` and MCP bridge connect to the running macOS app. Installing a client or copying its configuration does not install an equivalent Windows or Linux application. Individual source components can have different requirements from that app-backed workflow. For macOS installation, see [Installation](https://repoprompt.com/docs/overview/installation/). Building the development source has its own toolchain requirements in [How to Build](https://repoprompt.com/docs/faq/how-to-build/); those are not a universal compatibility statement for every previously published binary. ### Can I help with another platform? Read [How Can I Contribute?](https://repoprompt.com/docs/faq/contributing/) and the application's contribution policy before proposing a port. A proposal should identify the target platform, which UI and system integrations it replaces, and how it will be maintained and tested. --- ## Introduction **Bring your code, context, and AI coding tools together.** RepoPrompt gives you a well-thought-out, unified workspace for exploring a repository and working with your go-to AI coding tools. Use its first-class tooling to explore an extensive repo, trace unfamiliar code, work through an architectural decision, review a series of changes, or coordinate work across coding agents you already use. The macOS application is **free and open source**. Connect your own coding-runtime account, API provider, or local model service; [AI service costs](https://repoprompt.com/docs/faq/pay-for-services/) depend on the connection you use. ### tl;dr: Jump In Right Now Don't want to read right now? That's OK...we'll be here when you get back. Take a five-minute jump into the pool with [Getting Started](https://repoprompt.com/docs/overview/getting-started/), or take your time and explore the workflow with [Going Deeper](https://repoprompt.com/docs/overview/going-deeper/). ### Give your coding work the right tools and the right context Before any coding agent can make production-ready changes, it needs to understand the code already there: the relevant files, their interfaces, the changes in progress, and the constraints that matter. We all know that finding and sharing that context can take longer than writing the plan or prompt. RepoPrompt helps you build a focused view of the task and assemble that context accurately and narrowly so you get the best results from your favorite models from your preferred providers. It gathers full files when implementation details matter, slices when only a few lines are relevant, and delivers Code Maps when structure and signatures are enough. Add Git changes and clear instructions to show the model what you want it to examine. Then select a battle-tested, pre-built workflow or manually inspect and adjust the package before asking for a plan, review, or implementation. You still judge the answer and verify the resulting changes. [See how context preparation works →](https://repoprompt.com/docs/overview/how-it-works/) ### Choose how you want to work #### Run a coding session in RepoPrompt Choose a connected coding runtime, then describe the task, choose a workflow, and follow the work in conversations and the Oracles that guide the results. You can inspect tool activity and changes, answer questions, and steer the agent as it works, all without switching between terminal sessions. RepoPrompt session composer with workflow, context, model, tools, and permission controls [Get to know the session interface →](https://repoprompt.com/docs/agent-mode/overview/) #### Keep using your preferred coding tools Connect an MCP-compatible client to RepoPrompt's repository and context tools. Your external coding agent can search files, inspect Code Maps, assemble context, and consult an Oracle while you review the work in RepoPrompt. [Connect an external coding tool →](https://repoprompt.com/docs/mcp-server/mcp-setup/) #### Prepare a prompt for another model Select code, add instructions and Git changes, then copy a self-contained package. Use it for a design discussion or an independent review in ChatGPT or another service, and bring the useful findings back to your coding session. [Prepare and copy your context →](https://repoprompt.com/docs/agent-mode/context-composer/) ### Start with the task you need to finish Choose a built-in workflow from the welcome cards or the **Workflow** selector, then describe what you want to accomplish. Let RepoPrompt go from there. | What you want to do | Where to start | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | | Coordinate a larger piece of work | **Orchestrate** breaks down the task, delegates work, and checks the results. | | Check changes for bugs and regressions | **Review** examines the change with its surrounding code. | | Understand a bug or unfamiliar behavior | **Investigate** gathers evidence and explores the relevant code. | | Plan a substantial change before editing | **Deep Plan** develops an implementation plan grounded in the repository. | | Build a feature or fix | **Plan & Build** guides research, planning, and implementation. | | Improve code structure | **Refactor** focuses on preserving intended behavior while improving the implementation. | | Get an independent perspective | **ChatGPT Export** prepares context for a conversation outside RepoPrompt. | [Choose a workflow for your task →](https://repoprompt.com/docs/agent-mode/workflow-templates/) ### Make RepoPrompt Your Partner 1. **Describe the task.** The Context Builder gathers relevant code, and Oracle drafts an execution plan. A narrow context window and a double-checked plan is key for the best results. 2. **Divide the work.** The Orchestrator assigns tasks with clear file boundaries. No hidden "Thinking..." output here. 3. **Implement.** Agents work sequentially or in parallel from a shared plan, with the Orchestrator steering progress. The division of tasks and clarity that the Orchestrator offers is part of our "secret sauce." 4. **Verify.** The Orchestrator checks the results against the plan and continues until complete. All together, this is what yields production-quality code. ### Coordinate larger changes without losing sight of them RepoPrompt overcomes the AI-assisted nightmare of big edits. For a larger change, you can use separate sessions for investigation, implementation, and review. **Overseer Mode** lets a coordinating conversation follow linked sessions and direct the next steps. Use **worktrees** when parallel tasks need separate checkouts; separate conversations can still edit the same checkout. Review the work, merge it into the intended target, and verify the combined result. [Coordinate sessions with Overseer →](https://repoprompt.com/docs/overseer/) · [Create and use a worktree →](https://repoprompt.com/docs/worktrees/create-and-use/) · [Review and merge the result →](https://repoprompt.com/docs/worktrees/review-and-merge/) ### Keep control as the work develops - **Make the request clearer.** Use [Interviewer](https://repoprompt.com/docs/agent-mode/interviewer/) to resolve open questions or [Re-Prompter](https://repoprompt.com/docs/agent-mode/re-prompter/) to refine a draft before sending. - **Show the problem.** Attach a [screenshot or mockup](https://repoprompt.com/docs/agent-mode/image-support/). Eligible Codex sessions can also use [Computer Use](https://repoprompt.com/docs/agent-mode/computer-use/) for tasks that need the visible interface. - **Choose how the model works.** Set the [model and reasoning effort](https://repoprompt.com/docs/agent-mode/model-and-effort/) yourself, or configure [Agent Decisions](https://repoprompt.com/docs/agent-mode/model-router/) for eligible new tasks. - **Review the decisions that matter.** Inspect [approval requests and edit reviews](https://repoprompt.com/docs/agent-mode/approvals/), then return to [session history](https://repoprompt.com/docs/agent-mode/session-history/) when you need the context behind a result. ### Use the connection that fits your work Connect a supported coding runtime for implementation, a direct API for model features, or a local model server. Configure Oracle consultations separately when you want another model to assess a plan or review the code. The **Providers & Models** reference explains what each integration needs and what it supports. Available models depend on your connected accounts or APIs you bring to the table. You can start with a focused task and adjust the settings as you go; you do not need to choose every model and experiment with thinking levels and settings before trying. [Compare providers and model availability →](https://repoprompt.com/docs/providers/overview/) ### Try it on one real task Start with a question you can evaluate: understand an unfamiliar function, investigate a reproducible bug, or review a small change. A narrow first task makes it easier to see what RepoPrompt adds to your existing workflow. 1. **Open your project** and connect the provider you want to use. 2. **Describe the outcome.** Include the behavior you care about, known constraints, and how you will check the result. 3. **Choose the workflow and location.** Use a separate worktree when you want an isolated checkout. 4. **Inspect and guide the work.** Review the selected context, answer questions, and check the resulting code and test results. [Follow the getting-started walkthrough →](https://repoprompt.com/docs/overview/getting-started/) ### Talk to These Docs Use **Copy page** to bring an article into an AI conversation. For the complete documentation, use the LLM index or full documentation export. Include your app version and the task you need help with. --- ## App Settings Tool The `app_settings` MCP tool lets agents read and write an allowlisted set of RepoPrompt's global preferences — appearance, prompt packaging, preferred models and the Oracle roster, Context Builder's agent/model, preset visibility, Code Maps, file scanning, selected Agent Mode preferences, and notifications — without opening the Settings UI. Credentials and workspace-specific profiles are not exposed. :::tip **Companion pages:** Use this page for the MCP/JSON surface. The same arguments can be sent with `rpce-cli` after [CLI installation](https://repoprompt.com/docs/mcp-server/mcp-setup/#terminal-access). See [Settings Reference](https://repoprompt.com/docs/reference/settings/) for the in-app controls. ::: ### When to Use It - Match the user's preferred appearance or prompt packaging before building a copy preset. - Review `mcp.show_model_presets` when configuring Oracle discovery. - Reset `models.planning_model` to `null` so RepoPrompt falls back to defaults. - Temporarily disable Code Maps globally via `code_maps.globally_disabled` during large refactors. - Inspect file-scanning and notification preferences without editing the raw settings document. ### Operations | `op` | Selectors | Purpose | | --- | --- | --- | | `list` | optional `group` | Browse the allowlist catalog. Each entry includes the current value and, for keys that have them, `options_available: true`. | | `get` | exactly one of `key`, `keys`, `group` | Read one or more setting values. Selectors are mutually exclusive. | | `set` | `key` and `value` | Update exactly one setting. `keys` and `group` are rejected on `set`. | | `options` | `key`, optional `agent`, `limit`, `detailed` | List candidate values for keys that advertise `options_available: true`, including model and font-scale settings. | #### Parameters | Parameter | Type | Notes | | --- | --- | --- | | `op` | `list \| get \| set \| options` | Required. | | `group` | string | `ui`, `prompt_packaging`, `models`, `context_builder`, `mcp`, `code_maps`, `file_system`, `agent_mode`, or `notifications`. Used by `list` and as a selector for `get`. | | `key` | string | Fully qualified key (e.g., `ui.appearance_mode`). Required for `set`; optional selector for `get`. | | `keys` | array of strings | Multi-key selector for `get`. Mutually exclusive with `key` and `group`. | | `value` | boolean, number, string, string array, or null | Required on `set`. Match the catalog's declared `type`: the additional Oracle roster uses an array, while `prompt_packaging.prompt_sections_order` uses a string containing a JSON array. | | `agent` | string | For `options` on model settings: filter candidates to a supported CLI backend, such as `claudeCode` or `codexExec`. | | `limit` | integer | For `options`: maximum number of candidates returned (1–200, default 60). | | `detailed` | boolean | For `options`: include descriptions and model metadata in each candidate. | ### Groups The allowlist is organized into nine groups so an agent can browse narrowly before reaching for `set`. If you are not sure about the exact key, type, or allowed values, call `list` first; `set` validates strictly and rejects unknown or out-of-range values without partial application. The returned catalog is the authority for the running build, including any debug-only entries. #### `ui` — Appearance and chrome | Key | Type | Details | | --- | --- | --- | | `ui.appearance_mode` | string enum | `System` \| `Light` \| `Dark`. App appearance mode. | | `ui.show_tooltips` | boolean | Whether RepoPrompt shows app tooltips. | | `ui.enable_keyboard_shortcuts` | boolean | Global keyboard shortcuts. New/changed shortcuts may only take effect after reopening a window. | | `ui.font_scale` | number | An app font-size preset value. Use `list` and `options` for accepted values; arbitrary sizes are rejected. | #### `prompt_packaging` — How prompts are assembled | Key | Type | Details | | --- | --- | --- | | `prompt_packaging.prompt_sections_order` | string containing a JSON array | The wire value is a string, not a native JSON array. Its decoded array must contain each prompt section exactly once. Call `{"op":"list","group":"prompt_packaging"}` first and read `allowed_items` for the canonical section raw values before sending `set`. | | `prompt_packaging.duplicate_user_instructions_at_top` | boolean | Whether user instructions are duplicated at the top of packaged prompts. | | `prompt_packaging.file_path_display_option` | string enum | `Full` \| `Relative`. How file paths are displayed in packaged context. | | `prompt_packaging.selected_files_sort_method` | string enum | `nameAscending` \| `nameDescending` \| `tokenAscending` \| `tokenDescending`. | | `prompt_packaging.include_datetime_in_user_instructions` | boolean | Whether packaged user instructions include the current date/time. | #### Legacy editing preferences The current allowlist has no `editing` group. Classic keys such as `editing.file_edit_format`, `editing.allow_diff_models_to_rewrite`, and `editing.complex_edit_strategy` should not be sent to this tool. Configure the relevant UI workflow instead; the current Oracle send contract offers `chat`, `plan`, and `review` modes. #### `models` — Model selection and inference defaults | Key | Type | Details | | --- | --- | --- | | `models.preferred_compose_model` — **Built-in Chat Model** | string \| null | Preferred Built-in Chat model raw identifier, if set. Advertises `options_available: true`. Set `null` to clear. | | `models.planning_model` — **Oracle Model** | string \| null | Preferred Oracle model raw identifier, if set. Advertises `options_available: true`. Set `null` to clear. | | `models.additional_oracle_models` | string array | Ordered additional Oracle model IDs, with at most four entries. The primary model is configured separately. | | `models.sync_chat_model_with_oracle` — **Sync Built-in Chat with Oracle** | boolean | Whether the Built-in Chat model is kept in sync with the Oracle model. | | `models.temperature` | number | Range `0.0`–`2.0`. Only applied when `models.temperature_enabled` is `true`. | | `models.temperature_enabled` | boolean | Whether the global temperature is sent with model requests. | | `models.custom_planning_prompt` — **Custom Oracle System Prompt** | string | Custom system prompt used by the Oracle. Empty string restores the built-in default. | #### `context_builder` — Context Builder agent & model | Key | Type | Details | | --- | --- | --- | | `context_builder.agent` | string enum | CLI agent used by Context Builder. Call `list` and read `allowed_values` for eligible backend IDs. Writes preserve the backend's remembered model when one exists, or use its default. | | `context_builder.model` | string \| null | Remembered model ID for the selected backend; null clears that slot. An unusable saved backend can read as null; inspect the agent catalog before setting a replacement. `options` normally scopes candidates to the current backend. | #### `mcp` — MCP preset visibility | Key | Type | Details | | --- | --- | --- | | `mcp.show_model_presets` | boolean | Whether MCP model presets are exposed. Internal temporary suppression is separate and is not a durable allowlisted preference. | **Auto-Start** and live listener lifecycle controls remain in the app UI. The Classic `mcp.auto_start` example is not part of the current registry. #### `code_maps` — Global Code Maps toggle | Key | Type | Details | | --- | --- | --- | | `code_maps.globally_disabled` | boolean | When `true`, Code Maps are globally disabled and the MCP `get_code_structure` tool is suppressed. | | `code_maps.non_git_enabled` | boolean | Opt in to Code Maps in non-Git folders. | #### `file_system` — Workspace folder scanning These preferences affect scanning. Local `.repo_ignore` file contents remain repository content, rather than a scalar application setting. | Key | Type | Details | | --- | --- | --- | | `file_system.respect_repo_ignore` | boolean | Honor RepoPrompt-specific ignore rules. | | `file_system.respect_cursorignore` | boolean | Honor `.cursorignore` rules. | | `file_system.global_ignore_defaults` | string | Global ignore patterns separated by newlines; limited to 20,000 characters. | | `file_system.enable_hierarchical_ignores` | boolean | Honor ignore files in nested directories. | | `file_system.skip_symlinks` | boolean | Skip symbolic links; the inverse of the UI's Follow symbolic links option. | | `file_system.show_empty_folders` | boolean | Include empty folders in workspace listings. | #### `agent_mode` — Selected global behavior | Key | Type | Details | | --- | --- | --- | | `agent_mode.show_built_in_workflow_cleanup_guidance` | boolean | Include housekeeping guidance in built-in Agent Mode workflow templates. Custom templates and external workflow instructions are separate. | | `agent_mode.codex_goal_support_enabled` | boolean | Enable Codex goal-support feature configuration. | | `agent_mode.codex_reasoning_summaries_enabled` | boolean | Request Codex reasoning summaries in Agent Mode; separate from reasoning effort. | | `agent_mode.claude_usage_quota_enabled` | boolean | Passive run rate-limit diagnostics; does not connect a Claude account or authorize account usage reads. | | `agent_mode.codex_usage_quota_enabled` | boolean | Observe-only Codex quota display preference. Quota readings are not returned over MCP. | | `agent_mode.usage_limits_display_enabled` | boolean | Display already-enabled usage sources; does not connect a source or change routing. | | `agent_mode.provider_conversation_cleanup_action` | enum | Provider conversation cleanup preference. Discover accepted values from `list`. | | `agent_mode.subagent_default_wait_seconds` | integer enum | Default otherwise-quiet sub-agent wait: `120`, `300`, `600`, `1200`, `1800`, or `3600` seconds. | #### `notifications` — Notification preferences The registry exposes notification descriptor keys as booleans. Call `{"op":"list","group":"notifications"}` for the exact names, descriptions, and values in your build, then use a returned key with `set`. These preferences control app notification behavior; macOS notification authorization is managed by the operating system. See [Notifications settings](https://repoprompt.com/docs/settings/notifications/). ### Examples (MCP JSON) Each example shows the arguments object passed to `app_settings`: The prompt-section order is JSON encoded inside the string-valued `value`. This example uses the section names declared in the application source; compare them with the running catalog's `allowed_items` before changing the order: ```json { "op": "set", "key": "prompt_packaging.prompt_sections_order", "value": "[\"fileMap\",\"fileContents\",\"gitDiff\",\"metaPrompts\",\"userInstructions\"]" } ``` ```text // Browse the full catalog (values always included) { "op": "list" } // Inspect one group { "op": "list", "group": "ui" } // Batch read a few keys { "op": "get", "keys": ["ui.appearance_mode", "mcp.show_model_presets"] } // Toggle a boolean { "op": "set", "key": "ui.show_tooltips", "value": false } // Update an enum { "op": "set", "key": "ui.appearance_mode", "value": "Dark" } // Clear an optional model (null is valid for nullable keys) { "op": "set", "key": "models.planning_model", "value": null } // Change a numeric setting { "op": "set", "key": "models.temperature", "value": 1.25 } // Switch the Context Builder agent (remembered model is preserved) { "op": "set", "key": "context_builder.agent", "value": "codexExec" } // List candidate models for the current Context Builder backend { "op": "options", "key": "context_builder.model" } // Narrow candidates to one CLI backend { "op": "options", "key": "models.planning_model", "agent": "codexExec", "limit": 25 } ``` ### Error Behavior - **Unknown keys:** Rejected with a clear error. Call `list` (or `list` with a `group`) to discover the correct key. - **Wrong types:** Booleans, numbers, strings, and `null` are each validated against the entry's declared `type`. - **Out-of-range values:** Numeric ranges (e.g., `models.temperature` 0.0–2.0) and enum values are enforced. - **No partial application:** Validation fails closed — if any check fails, nothing is written. - **One key per `set`:** Passing `keys` or `group` on `set` is rejected. ### Safety & Deliberately Excluded This surface is intentionally narrow. The following are **not** reachable through `app_settings` and must be managed in the Settings UI: - API credentials and raw provider secrets for any provider. - MCP tool ACLs, auto-start lifecycle controls (`mcp.auto_start`), and agent permission documents. - Workspace approvals and workspace-scoped chat/copy settings. - Agent permission policies, human-only strict approval controls (specifically `agent_mode.codex_hook_approval_strict_mode_enabled`, which is classified in `humanOnlySettingKeys` and explicitly rejected over MCP), and workspace model override dictionaries. Selected durable global Agent Mode preferences are explicitly allowlisted above. - Internal migration flags and settings absent from the catalog. Development builds can expose additional diagnostic entries; do not assume they exist in release builds. If a preference is dangerous, secret, or workspace-specific, it is kept UI-only by design. Agents can still discover what *is* reachable with `op=list`. ### See Also - [Setup Guide](https://repoprompt.com/docs/mcp-server/mcp-setup/#terminal-access) — install terminal access with `rpce-cli`. - [MCP Tools Reference](https://repoprompt.com/docs/mcp-server/mcp-tools/) — schemas for every MCP tool. - [Settings Reference](https://repoprompt.com/docs/reference/settings/) — the in-app Settings UI equivalents. - [MCP Server Overview](https://repoprompt.com/docs/mcp-server/) — IDE-for-agents framing and capability map. --- ## Connection Management RepoPrompt 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 toolbar's MCP icon opens the server popover. The popover identifies the window being configured and provides live listener and connection feedback: | Status | Meaning | | --- | --- | | **Active** | The listener is running and MCP tools are enabled for this window. | | **Waiting for listener…** | Window access is enabled but the listener is not running. | | **Listener active** with tools disabled | The shared listener is available, but this window is not exposing its tools. | | **Inactive** | This window is not exposing tools and the listener is not running. | | Running tool name / **Cancel** | A tool call is in progress; cancellation is available where supported. | The connection badge opens client details. In Settings, **Status Dashboard** opens diagnostics; an error indicator opens contextual error information. Use the window switch to change this window's access. **Force Stop Listener** stops the shared listener for all windows and clients. ### Connection Approval A new external client process can trigger a **Connection Request** overlay showing its identity and executable information when available. Review the process and the connection you initiated before approving. With [Strict connection approval](https://repoprompt.com/docs/settings/mcp-server/#strict-connection-approval) off, common client names are approved automatically and **Always allow this client** can save approval by name. Clear that option to use **Allow Session** (when executable identity is available) or **Allow Once** instead. Name-based trust can admit another program using the same name. With strict approval on, saved and built-in names are ignored. Approvals last for the current RepoPrompt run, including reconnects from the same running app. **Deny** rejects the request. Agents started inside RepoPrompt do not require this connection prompt. Connection admission, workspace-operation approval, and agent permissions are distinct. Allowing a client to connect does not authorize it to create or delete a workspace, approve an agent shell command, or widen its tools. See [Workspace Approvals](https://repoprompt.com/docs/settings/workspace-approvals/) and [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/). ### Multi-Window Context RepoPrompt supports multiple windows, each showing a workspace, behind one shared listener. The current UI provides a per-window MCP access switch. It does not require the old **Multi-Window Mode** setup step from Classic documentation. #### Context Binding Use `bind_context` to discover, inspect, and bind the workspace context for this connection. Start with `op="list"`, then bind by absolute workspace root paths or a returned context UUID. Root matching first looks for an exact set, then an eligible superset; pass workspace roots rather than arbitrary descendant files. ```json {"op":"bind","working_dirs":["/Users/example/Project"]} ``` When a suitable saved workspace is not already open, the app can open it. `create_if_missing=true` allows a new workspace to be requested when no match exists, subject to workspace approval. To pin a compose context rather than following the active tab, bind a `context_id` returned by discovery: ```json {"op":"bind","context_id":"RETURNED-CONTEXT-UUID"} ``` Call `{"op":"status"}` to inspect the current binding. The current global `bind_context` schema does **not** accept `window_id`; use the fields returned by your connection's schema. Compose context IDs and Agent Mode session IDs serve different purposes and must not be substituted for each other. #### Workspace Lifecycle `manage_workspaces` lists saved workspaces and handles workspace creation, switching, hiding, deletion, folders, and compose tabs. `list` excludes hidden workspaces by default; `include_hidden=true` includes them. Hiding keeps a workspace recoverable, while deletion is a separate operation. ```text // List saved visible workspaces { "action": "list" } // Include recoverable hidden workspaces { "action": "list", "include_hidden": true } // Open a saved workspace in a new window { "action": "switch", "workspace": "MyProject", "open_in_new_window": true } // Create a new workspace and switch to it, subject to approval { "action": "create", "name": "NewProject", "folder_path": "/Users/example/NewProject", "switch_to_created": true } // Add a folder to an existing workspace { "action": "add_folder", "workspace": "MyProject", "folder_path": "/Users/example/Shared" } ``` Use exact workspace UUIDs when names are ambiguous. Some lifecycle operations also accept a `window_id`; that is separate from the global context-binding API. ### Tab Management Compose tabs allow parallel work contexts within a single window. MCP clients can manage tabs programmatically: #### Listing Tabs ```text // List tabs in current window { "action": "list_tabs" } // Response includes: // - Tab ID and name // - [active] = Currently visible tab // - [bound] = Tab this MCP connection is pinned to ``` #### Tab Binding A workspace/window affinity can follow the active tab. For operations that need a stable selection and prompt, bind the compose context explicitly before starting. `manage_workspaces` retains these legacy tab operations; prefer `bind_context op=list` and `op=bind context_id=...` for new integrations: ```text // Bind to a specific tab for consistent context { "action": "select_tab", "tab": "Feature-Auth", "focus": false } // 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. ```text // Create a blank background tab and bind this MCP connection to it { "action": "create_tab", "name": "Bugfix", "bind": true, "focus": false } // Fork an existing tab into a new background tab { "action": "create_tab", "mode": "fork", "source_tab": "Feature-Auth", "name": "Feature-Auth Follow-up" } ``` `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 RepoPrompt applies safety checks to prevent destructive or confusing behavior. ```text // Close a non-active tab by name or UUID { "action": "close_tab", "tab": "Bugfix" } // Explicitly allow closing the currently visible tab { "action": "close_tab", "tab": "Bugfix", "allow_active": true } ``` - 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 Oracle History Use `oracle_utils` with `op="sessions"` to find Oracle conversations at workspace or context scope. Supply a context UUID discovered through `bind_context` to narrow the list: ```json {"op":"sessions","context_id":"RETURNED-CONTEXT-UUID","limit":10} ``` During eligible Agent Mode runs, `oracle_chat_log` returns recent Oracle messages; `chat_id` selects a conversation, `limit` bounds the response, and `include_user` controls whether the caller's messages are included. Use `oracle_send` or `ask_oracle`, as advertised, to continue a conversation. The Classic `chats` tool's `action="list"` and `action="log"` examples are not the current contract. #### Context Builder Discovery Tab An external app-backed `context_builder` call normally creates a fresh compose tab for its discovery context. During an Agent Mode run, the tool reuses the current agent tab. Check the returned context and conversation IDs before continuing; do not assume discovery always creates a new tab. ### 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 | Low | According to Workspace Approvals policy | | Add folder | Medium | According to Workspace Approvals policy | | Remove folder | Medium | According to Workspace Approvals policy | | Delete workspace | High | According to Workspace Approvals policy | ### Connection Lifecycle 1. **Server start:** RepoPrompt opens its local bootstrap listener. 2. **Client launch:** The external tool spawns `repoprompt-mcp` with the generated `--backend app` arguments over stdio. 3. **Handshake:** The bridge connects locally and negotiates the tool surface. 4. **Admission:** The app validates the connection and requests approval when required. 5. **Binding:** The client resolves the intended workspace context before repository work. 6. **Active use:** Tool calls and responses flow between the client and the app. 7. **Disconnect:** The client closes, or the listener stops, and session resources are released. ### Reconnection Behavior A lost app connection and a client restart can require a fresh handshake and binding. Reconnection support does not guarantee replay of an interrupted edit, a running model request, or restoration of every window/tab selection. After reconnecting, inspect `bind_context op=status`, refresh the tool list if necessary, and inspect workspace or run state before retrying a mutation. Keep an agent run's returned `session_id` for its control operations, and use its latest snapshot to determine whether the run finished or still needs input. Do not start a duplicate run merely because the external client stopped waiting. ### Troubleshooting Connections #### Connection Not Appearing - Ensure MCP Server is enabled in Settings - Bring RepoPrompt forward and inspect pending connection requests - Verify the client configuration points to the correct `repoprompt-mcp` path #### Stale Connection State - Toggle the MCP Server off and on in Settings - Restart the external client - Inspect **Status Dashboard** and connection errors before resetting configuration; avoid deleting runtime files while the app is running #### Wrong Window/Tab Receiving Tools - Use `list_tabs` to verify which tab is bound - Use `select_tab` to explicitly bind to the correct tab - Use `bind_context op=status` and rebind the intended workspace roots or context ID :::tip **Pro Tip:** For long-running agent sessions, bind to the intended context using `bind_context` early in the session. This prevents context confusion if tabs are switched during operation. ::: --- ## MCP Server 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. RepoPrompt's MCP server exposes file selection, Code Maps, Context Builder, Oracle conversations, edits, workspace and tab lifecycle, allowlisted app preferences, and policy-controlled Agent Mode session operations. Clients discover the tools available to their connection rather than assuming every tool is always exposed. The app-backed tools are reachable two ways: - **Direct MCP** — persistent connections for agents that natively speak MCP. - **[rpce-cli](https://repoprompt.com/docs/mcp-server/mcp-setup/#terminal-access)** — ephemeral shell invocations for agents and humans that prefer a terminal. Both surfaces let you switch workspaces, create tabs, select files, run Context Builder, consult an Oracle, apply edits, and update allowlisted preferences. Tool toggles, connection policy, workspace access, and Agent Mode permissions still apply. Some capabilities are only advertised inside an eligible Agent Mode or discovery session. #### Quick Access: MCP Controls Click the **MCP Server** indicator in the toolbar for quick access to the server popover. The adjacent lightbulb opens the [Setup Wizard](https://repoprompt.com/docs/mcp-server/setup-wizard/), which recommends model and agent settings. Toolbar controls: a Setup Wizard lightbulb and an MCP server icon Current MCP Server popover showing window access, Auto-Start, Oracle Model Presets, Context Builder, and Quick Setup **Key settings to configure:** - **Window access:** Enable MCP tools for the workspace window you want clients to use. - **Auto-Start:** Request automatic listener startup when you launch RepoPrompt. - **Oracle Model Presets:** Expose named Oracle configurations to external clients. Current source uses `oracle_utils` and `oracle_send`; Agent Mode also provides `ask_oracle`. - **Context Builder:** Review its selected CLI agent and model, and change them in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). - **Quick Setup:** Install the client integration and optional workflow instructions separately. The popover displays the count of currently advertised tools (typically **21 available** for standard external MCP clients, covering workspace lifecycle, file operations, Code Maps, context curation, Git, Oracle consultations, history, and the agent control plane). An additional set of policy-gated tools (`ask_user`, `ask_oracle`, `oracle_chat_log`, `agent_session_link`, `session_admin`, `become_overseer`, `self_compact`, `share_thoughts`, `set_status`, `wait_for_next_user_instruction`) are dynamically activated during eligible Agent Mode or oversight sessions. This guide follows the current implementation where it differs from Classic tool names. :::tip **Showing 0 tools?** First check that the listener is running and tools are enabled for the target window. Reconnect or restart the external client if it cached an earlier empty list. See [Setup troubleshooting](https://repoprompt.com/docs/mcp-server/mcp-setup/#troubleshooting-setup). ::: #### RepoPrompt as an IDE for Agents Think of RepoPrompt'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 an Oracle for planning, reviewing, and questions with your configured models. Oracle consultation and the agent's subsequent implementation are separate steps. ##### File Editing Create, move, and delete files. Apply search/replace edits or full rewrites with diff previews and applicable approval checks. Review the returned result rather than assuming every requested edit was applied. ##### Workspace Management List, switch, and create workspaces. Manage compose tabs for parallel tasks. Full programmatic control. ##### Multi-Window Support Use multiple windows for different workspaces. Clients discover and bind workspace context through `bind_context`; compose-tab binding keeps a selection and prompt isolated from UI tab changes. ##### 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](https://repoprompt.com/docs/mcp-server/mcp-tools/) for details. ##### App Settings Read and update allowlisted preferences for appearance, prompt packaging, models, MCP preset visibility, Code Maps, file scanning, selected Agent Mode behavior, and notifications through `app_settings`. See [App Settings Tool](https://repoprompt.com/docs/mcp-server/mcp-app-settings/) for the current catalog. Auto-Start and permission policies remain app controls. #### Architecture Overview The MCP server uses a secure, local-only architecture with UNIX socket transport: **Local Socket Transport:** External Client → repoprompt-mcp bridge (stdio) → UNIX Socket → RepoPrompt App The app bridge uses local UNIX sockets, without exposing an MCP TCP listener. Client admission and filesystem permissions protect access. This describes the client-to-app connection: Oracle, Context Builder, and agent requests can still contact the AI providers you configure. #### Compatible Clients RepoPrompt provides native one-click configuration for: - **Claude Code** — Anthropic's official coding CLI with deep MCP and skill integration - **Cursor** — AI-native code editor with deeplink MCP installation - **Codex CLI** — OpenAI's CLI agent with isolated prompt and skill discovery - **VS Code** — Visual Studio Code with standard stdio MCP configuration - **OpenCode** — Modern open-source terminal coding assistant - **Claude Desktop** — Anthropic's desktop application - **Any MCP Client** — Any client supporting the open Model Context Protocol standard Compatible clients can also install RepoPrompt's built-in [Workflow Commands](https://repoprompt.com/docs/mcp-server/workflow-commands/), providing slash commands for orchestration, deep planning, optimization, code review, refactoring, implementation, bug investigation, and prompt exporting. #### Sibling: rpce-cli Prefer a shell, or running on an agent that doesn't natively speak MCP? The same tools are reachable from [`rpce-cli`](https://repoprompt.com/docs/mcp-server/mcp-setup/#terminal-access), 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](https://repoprompt.com/docs/mcp-server/mcp-app-settings/) for the CLI view of the same `app_settings` surface. #### Quick Start: claude-rpce For a preconfigured Claude Code launch, install the `claude-rpce` wrapper from **Settings → MCP Server → CLI Tools**. Use the corresponding debug command name when running a debug build. 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 is needed — just run `claude-rpce` 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 RepoPrompt's UI - **Human Oversight:** Approve connections, review edits before applying - **Reviewable Changes:** Inspect tool results, previews, and workspace state as agents work. #### Security Model - External clients pass the app's connection-admission checks; approval can be required for a new client process. - 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 - A shared listener serves window-scoped tools; each window's tool access and the connection's context binding determine where calls run. :::tip **Getting Started:** Click the **MCP Server** button in the toolbar to enable the server, configure your models, and install the integration in your preferred client. See the Setup Guide for step-by-step instructions. ::: --- ## 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. Current MCP Server popover with window status, Oracle presets, Context Builder, and Quick Setup *Note: The screenshots (`mcp-server-popover.png` and `mcp-window-access.png`) are historical captures showing **21 available** tools. RepoPrompt defines **31 total domain tools**: **21 are advertised** to standard external MCP clients (**3 global** tools and **18 window-scoped** tools), while the remaining **10 policy-gated and sub-agent internal tools** are dynamically exposed within eligible Agent Mode and oversight sessions. See [Policy-Gated and Sub-Agent Internal Tools](https://repoprompt.com/docs/mcp-server/mcp-tools/#policy-gated-and-sub-agent-internal-tools).* This is the primary location to configure the MCP server, including: - **Server activation** - Enable/disable MCP tools for external clients - **Oracle Model Presets** - Expose named Oracle model configurations to external clients - **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, RepoPrompt requests automatic listener startup on launch. This is useful if you always want MCP available for your AI tools. The target window must also have tools enabled. #### Status Indicator **Active** means the shared listener is running and tools are enabled for this window. **Waiting for listener…** means window access is enabled but the listener is not running. With window access disabled, a running listener can still serve other windows. The connection badge shows attached clients; the window number identifies the window being configured. Window access, Auto-Start, and connection count The full Settings pane also offers **Status Dashboard** for diagnostics and **Force Stop Listener**. Force Stop affects every window and client; use the window access switch to limit only this window. A running tool can expose a **Cancel** action. ### Oracle Model Presets Control which AI models are available to MCP clients when they use the `oracle_send` and `oracle_utils` tools. #### Use Oracle Model Presets for MCP When enabled, configured Oracle presets are exposed to MCP clients, allowing an agent to select from named model configurations. A preset can supply the primary model, additional Oracles, and its mapped Chat Preset. Grouped Oracle requests run their models independently and keep their results separate. When presets are disabled, the current Oracle configuration supplies the default. If no presets are defined, the popover offers the Oracle fallback model choice. If the Setup Wizard temporarily hid presets, **Show presets** restores their exposure without deleting their definitions. Oracle Model Presets with Manage, the model picker, and Show presets #### How Agents Use Presets Use `oracle_utils` with `op="models"` to discover model choices, then `oracle_send` to consult an Oracle. A `model` override is valid only for an explicit `new_chat=true` start. An exact exposed preset UUID or name takes precedence over a raw model identifier; continuing an existing conversation preserves its established configuration. ```json {"op":"models"} ``` The JSON above is passed to `oracle_utils`. A new consultation can then use an exposed preset: ```json {"message":"Review the selected changes for regressions.","mode":"review","new_chat":true,"model":"Review"} ``` Pass the second object to `oracle_send`, substituting a preset name returned by your own connection. Manage definitions in [Model Presets](https://repoprompt.com/docs/settings/model-presets/) or click **Manage** in the popover. Older Classic tool names `list_models` and `chat_send` have been replaced in the current source contract. ### 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 The row summarizes the CLI agent and model used by `context_builder`. Change them in [Agent Models](https://repoprompt.com/docs/settings/agent-models/), where global settings and workspace overrides are shown explicitly. Supported choices depend on configured providers and the Context Builder selection surface; the model shown in the screenshot is an example. Context Builder agent and model summary [Setup Wizard](https://repoprompt.com/docs/mcp-server/setup-wizard/) recommendations use the same model-selection engine. Discovery configuration is independent of the Oracle models used for the plan, question, or review that follows. #### How context\_builder Works When an MCP client calls `context_builder` with task instructions, RepoPrompt's Context Builder agent: 1. Analyzes the task requirements 2. Explores the codebase to find relevant files 3. Builds a selection toward the configured context budget 4. Returns the selection, or runs the requested plan, question, or review with Oracle context This enables AI agents to automatically gather context without manual file selection. ### Quick Setup The popover's **Install…** menu has three groups: **MCP Server** configures a client connection, **CLI (rpce-cli)** provides terminal access, and **claude-rpce (Claude Code wrapper)** provides a preconfigured Claude Code launcher. **Skills** installs reusable workflow instructions separately. Installing one of these does not install or authenticate the client application itself. #### Install MCP Server Choose a client under **MCP Server** in **Install…**. The Settings pane labels this button **Install MCP…** and places terminal installation actions in its separate **CLI Tools** section. | Option | What it configures | | --- | --- | | **Cursor** | Opens Cursor's MCP installation link with RepoPrompt's generated server configuration. Complete the installation in Cursor. | | **VS Code** | Opens VS Code's MCP installation link with the generated stdio server entry. Complete the client-side setup. | | **Codex CLI** | Configures and enables the server in RepoPrompt's isolated Codex configuration and installs its MCP workflow prompts there. This does not configure every separate Codex installation or its ordinary user home. | | **OpenCode** | Adds the persistent MCP server entry to `~/.config/opencode/opencode.json`. RepoPrompt's runtime agent modes are separate from this persistent connection entry. | | **Claude Desktop** | Adds the server entry to Claude Desktop's configuration. The installer reports failure if Claude Desktop's application-support folder is absent; install and open that client first. | | **Claude Code (per-project)** | Runs Claude Code's MCP installation command in each loaded workspace root. Open the intended project folders first and make sure the Claude Code CLI is installed. | The two **Install to PATH** and **Uninstall from PATH** pairs belong to different commands, as described below. Restart or reconnect the selected client if it does not discover its new MCP configuration immediately. Install menu with six MCP client choices, rpce-cli PATH actions, and separate claude-rpce wrapper PATH actions #### CLI Installation (rpce-cli) Under **CLI (rpce-cli)**, **Install to PATH** installs the managed `rpce-cli` command in `/usr/local/bin` for terminal access to RepoPrompt's MCP tools. This enables scripting, automation, and interactive codebase exploration. macOS can request administrator authorization to write that location; the directory must be on your shell's PATH to invoke the command by name. **Uninstall from PATH** removes that managed terminal command. It does not uninstall RepoPrompt or remove MCP configurations already added to external clients. Debug builds use `rpce-cli-debug`, so use the command name displayed by the running build. ```bash rpce-cli -e 'call get_file_tree {"type":"roots"}' rpce-cli -e 'call workspace_context {"include":["selection","tokens"]}' ``` #### claude-rpce Wrapper Under **claude-rpce (Claude Code wrapper)**, **Install to PATH** installs a managed launcher in `/usr/local/bin`. It runs an already-installed Claude Code CLI with RepoPrompt's MCP configuration, strict MCP configuration mode, and the built-in Read, Write, Edit, Glob, and Grep tools disabled. This directs those file operations through RepoPrompt's tools. The wrapper's **Uninstall from PATH** removes its managed launcher, not Claude Code itself or the separate `rpce-cli` command. Debug builds use `claude-rpce-debug`. The wrapper requires the Claude Code CLI and a running RepoPrompt app with MCP tools enabled. **Why use claude-rpce?** - **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 ```bash # Instead of running: claude # Run: claude-rpce # This automatically: # - Points to RepoPrompt's MCP config # - Enables strict MCP mode (ignores other configs) # - Disables Claude's built-in Read, Write, Edit, Glob, Grep tools ``` :::info **Prerequisite:** RepoPrompt must be running with MCP Server enabled for `claude-rpce` to work. ::: #### Skills Menu **Skills** installs reusable workflow prompts: `/rp-orchestrate`, `/rp-deep-plan`, `/rp-optimize`, `/rp-review`, `/rp-refactor`, `/rp-build`, `/rp-investigate`, `/rp-oracle-export`, and `/rp-reminder`. Choose a destination based on which client should discover them and whether they should apply across projects or only within the loaded project folders. | Menu group and option | Scope and destination | | --- | --- | | **Shared (.agents/skills) → Global (~/.agents/skills)** | Installs shared skill directories under your home folder for clients that discover this convention, including Codex and other compatible agents. | | **Shared (.agents/skills) → Per-project (.agents/skills)** | Installs shared skills in each loaded workspace root's `.agents/skills` folder. Use this to keep instructions project-specific. | | **Claude Code (.claude/commands) → Per-project** | Installs Claude Code workflow skills for the loaded roots. The menu retains the older `.claude/commands` label; the current implementation writes `.claude/skills//SKILL.md` and migrates legacy flat command files. | | **RepoPrompt Codex (isolated prompts) → Global** | Installs workflow prompt files in the `prompts` directory of RepoPrompt's isolated Codex home. Global here means that isolated environment, not every external Codex installation. | Each destination submenu offers **MCP skills**, **rpce-cli skills** (or the running build's CLI name), and **Uninstall**. The MCP variant instructs an agent to call RepoPrompt tools directly. The CLI variant instructs it to use the installed terminal command and uses skill names with a `-cli` suffix. Choose the variant that matches how your client accesses RepoPrompt; installing a CLI variant does not install the executable for you. **Uninstall** removes RepoPrompt-managed MCP and CLI workflow files from the chosen destination, leaving unrelated skills alone. Per-project install options require loaded workspace folders and are disabled or report **Open a folder first** when none are available. The grey section labels and **Works with Codex and other agents** text are descriptions, not additional actions. Skills menu showing global and per-project shared skills, per-project Claude Code skills, and global prompts in RepoPrompt's isolated Codex environment This installs workflow instructions as skill folders or prompt files for the chosen destination; it does not connect a client, authenticate a provider, or expand tool permissions. If the client has already loaded its instruction files, refresh its picker or restart it. See [Workflow Commands](https://repoprompt.com/docs/mcp-server/workflow-commands/) for the current command catalog. #### Copy JSON Copies the MCP server configuration to your clipboard for manual installation in any MCP-compatible client: ```json { "mcpServers": { "RepoPromptCE": { "command": "/path/to/repoprompt-mcp", "args": ["--backend", "app"] } } } ``` :::info **Note:** After installing, restart the client application if the integration isn't detected immediately. ::: ### Advanced Settings The Settings pane contains **CLI Tools** and expandable **JSON Configuration** sections beyond the popover. CLI rows report **Installed**, **Not installed**, **Needs update**, or **Exists but not managed**, with actions appropriate to that state. Debug builds use their separate debug command names. Use **Status Dashboard** for connection diagnostics and active-client inspection. Individual tool enablement is documented in [MCP Tools settings](https://repoprompt.com/docs/settings/tools/). Workspace context routing is described in [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/). See [Transport & Security](https://repoprompt.com/docs/mcp-server/mcp-transport/) and [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/) for details. --- ## Setup Guide Get RepoPrompt's MCP server connected to your preferred AI tool. The server enables external agents to use RepoPrompt's context building, code intelligence, editing, and workspace capabilities. ### Quick Setup 1. Open a workspace in RepoPrompt, then click the toolbar's **MCP Server** icon or open **Settings → MCP Server**. 2. Enable MCP tools for that window. **Active** confirms both a running listener and enabled window access; **Waiting for listener…** means the window is enabled but the listener is not ready. 3. Under **Quick Setup**, open **Install…** (shown as **Install MCP…** in Settings) and choose your client. 4. Restart or reconnect that client if it does not discover the integration immediately. Respond to any connection request shown in RepoPrompt. 5. Discover and bind the intended workspace before running repository tools. MCP window status and Auto-Start controls ### Client-Specific Instructions The installer generates configuration for the RepoPrompt CE app you are running. Use it instead of carrying an old Classic executable path into the new client configuration. #### Cursor Open **Quick Setup → Install… → Cursor**. RepoPrompt opens Cursor's MCP installation link with its generated command configuration. Complete the client-side installation, then reconnect or restart Cursor. Approve the connection in RepoPrompt if requested. #### Claude Code Choose **Claude Code (per-project)** from the Install menu with the intended workspace folders loaded. The installer configures those projects. Alternatively, copy the generated JSON and add its server entry using your client's MCP configuration workflow. Restart the client when necessary and verify that it discovers RepoPrompt's tools. #### Codex CLI Choose **Codex CLI** from the Install menu. RepoPrompt updates the Codex MCP configuration with the generated app bridge and its supported timeout settings. Restart or reconnect Codex after installation. Use the installer rather than a hand-written `codex.toml` example from an older guide. #### Other Supported Clients The current Install menu also offers **VS Code**, **OpenCode**, and **Claude Desktop**. OpenCode installation targets its CLI configuration; Claude Desktop installation reports if the application is not found. Client installation and provider authentication are different operations: installing MCP does not sign a CLI agent in to its AI service. #### Other MCP Clients Copy the JSON with the copy button beside **Skills**, or expand **JSON Configuration** in Settings. Add the generated server entry to your client's MCP server configuration. The client launches the bundled `repoprompt-mcp` bridge over stdio, and the bridge connects to the app locally. ### Configuration Format The generated app-backed configuration has this shape. The command below is a placeholder; replace it with the exact absolute path copied from the running app. ```json { "mcpServers": { "RepoPromptCE": { "command": "/absolute/path/copied/from/RepoPrompt/repoprompt-mcp", "args": ["--backend", "app"] } } } ``` The `--backend app` arguments explicitly select the running app backend. The command normally uses a managed user-space link, with a bundled executable path as a fallback. RepoPrompt release and debug builds have distinct identities. Always copy the configuration for the build you intend to connect to. ### Connection Approval When an external client needs approval, RepoPrompt shows a **Connection Request** overlay with its client and, when available, executable information. Review the process before choosing **Allow Session**, **Allow Once**, or **Deny**. With strict connection approval off, **Always allow this client** can save approval by app name, and common names may connect automatically. Enable [Strict connection approval](https://repoprompt.com/docs/settings/mcp-server/#strict-connection-approval) to require per-run approval instead of trusting saved or built-in client names. Connection approval admits the client; it does not approve every workspace mutation, file edit, or agent operation. Those actions remain subject to their own policies. See [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/). ### Verifying the Connection Check that the intended RepoPrompt window reports **Active** and that the connection badge shows an attached client. In the external client, ask the agent to discover available tools, call `bind_context` with `op="list"`, and bind the intended workspace roots. Then request `get_file_tree` or a `workspace_context` snapshot. ```json {"op":"bind","working_dirs":["/Users/example/Project"]} ``` This JSON is an arguments object for `bind_context`, not a complete client configuration. Use exact workspace root paths; see [context binding](https://repoprompt.com/docs/mcp-server/mcp-connections/#context-binding) for tab-specific isolation. ### Terminal Access In Settings, the **CLI Tools** section installs **rpce-cli** for shell access and **claude-rpce** as the Claude Code wrapper. Debug builds use **rpce-cli-debug** and **claude-rpce-debug**. Follow the row's **Install** or **Update** action, then use the command name it displays. The app must be running with MCP access enabled for app-backed calls. For example, after installing the release CLI, `rpce-cli -e 'call get_file_tree {"type":"roots"}'` calls the same repository tool from a shell. The CLI supports JSON arguments; it does not use the obsolete `rp-cli tree` and `rp-cli context --all` examples from Classic documentation. ### Workflow instructions Use **Quick Setup → Skills** to install MCP or CLI workflow instructions for your client. The installer writes skill folders or prompt files, depending on the destination, for commands such as `/rp-orchestrate` and `/rp-build`. It does not install the server connection itself. See [Workflow Commands](https://repoprompt.com/docs/mcp-server/workflow-commands/) for destinations, variants, and the complete command catalog. Quick Setup with Install, Skills, and copy-configuration controls ### Troubleshooting Setup Use the [MCP Troubleshooting FAQ](https://repoprompt.com/docs/faq/mcp-troubleshooting/) to distinguish connection failures, missing tools, wrong context bindings, and model-service errors. #### Client can't find repoprompt-mcp Re-copy the configuration from the installed RepoPrompt app and check that its command path exists. Avoid pointing a RepoPrompt client at an old Classic app or a different debug build. If the CLI Tools row reports **Needs update**, use **Update** before reconnecting. #### No approval dialog appears Check window access and listener status first. Bring RepoPrompt forward and look for a pending connection request. Inspect **Status Dashboard** and any error indicator in Settings before changing configuration. A client that was never launched or has the wrong executable path cannot reach the approval step. #### Connection keeps dropping Restart the external client after confirming the app and listener are running. Re-copy configuration after changing app builds. The app bridge uses UNIX sockets; the current setup has no user-facing **Filesystem transport** switch, and firewall or VPN changes are not the first troubleshooting step. #### Tools not appearing in client Check [MCP Tools](https://repoprompt.com/docs/settings/tools/) and the target window's access switch. Disabled tools, global Code Maps suppression, and connection policy can reduce the advertised list. Reconnect or restart a client that cached an earlier list; the screenshot's **21 available** is not a fixed count for every build or session. Once connected, explore the [Tools Reference](https://repoprompt.com/docs/mcp-server/mcp-tools/), use the [Setup Wizard](https://repoprompt.com/docs/mcp-server/setup-wizard/) for model recommendations, or read [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/) for workspaces and compose tabs. --- ## Tools Reference This reference follows the current RepoPrompt source contracts. Tools are organized by category; ordinary tool toggles live in [MCP Tools settings](https://repoprompt.com/docs/settings/tools/). Some tools are additionally limited to Agent Mode, discovery, or an authorized control relationship. Your connection's live schema determines which tools and arguments are available. The MCP settings status displays **21 available** tools for standard external client connections. RepoPrompt defines **31 total domain tools** (`MCPDomainToolCatalog.swift`): - **21 advertised tools** exposed to standard external MCP clients, consisting of **3 global tools** (`app_settings`, `bind_context`, `manage_workspaces`) and **18 window-scoped tools** (`agent_explore`, `agent_manage`, `agent_run`, `apply_edits`, `context_builder`, `file_actions`, `file_search`, `get_code_structure`, `get_file_tree`, `git`, `history`, `manage_selection`, `manage_worktree`, `oracle_send`, `oracle_utils`, `prompt`, `read_file`, `workspace_context`). - **10 policy-gated and sub-agent internal tools** (`ask_user`, `ask_oracle`, `oracle_chat_log`, `agent_session_link`, `session_admin`, `become_overseer`, `self_compact`, `share_thoughts`, `set_status`, `wait_for_next_user_instruction`) that are reserved for and dynamically activated within eligible Agent Mode and cross-session oversight contexts. See [Policy-Gated and Sub-Agent Internal Tools](https://repoprompt.com/docs/mcp-server/mcp-tools/#policy-gated-and-sub-agent-internal-tools). ### Tool catalog at a glance These short descriptions follow the built-in Settings catalog shown in the reference screenshot. The detailed sections below explain current arguments, limitations, and behaviors; use the schema advertised by your connected build for the exact contract. | Tool | What it does | | --- | --- | | [`agent_explore`](https://repoprompt.com/docs/mcp-server/mcp-tools/#agent_explore) | Starts short-lived, read-only Explore agents for focused codebase probes. Each child gets a fresh session and context. | | [`agent_manage`](https://repoprompt.com/docs/mcp-server/mcp-tools/#agent_manage) | Lists agents, sessions, and workflows; reads logs and handoffs; creates, resumes, stops, or cleans up eligible sessions. | | [`agent_run`](https://repoprompt.com/docs/mcp-server/mcp-tools/#agent_run) | Starts and controls Agent Mode sessions, including waiting for input, steering, responding, and cancellation. | | [`app_settings`](https://repoprompt.com/docs/mcp-server/mcp-tools/#app_settings) | Reads or updates the allowlisted RepoPrompt preferences. Settings outside the allowlist are not exposed. | | [`apply_edits`](https://repoprompt.com/docs/mcp-server/mcp-tools/#apply_edits) | Applies a whole-file rewrite, one literal replacement, or a batch of literal replacements. Choose exactly one mode. | | [`bind_context`](https://repoprompt.com/docs/mcp-server/mcp-tools/#bind_context) | Discovers, inspects, and binds the workspace context for this MCP connection. | | [`context_builder`](https://repoprompt.com/docs/mcp-server/mcp-tools/#context_builder) | Explores the codebase, selects relevant files, and builds task context within a token budget. | | [`file_actions`](https://repoprompt.com/docs/mcp-server/mcp-tools/#file_actions) | Creates, moves, or deletes files. Paths are absolute; deletion moves items to Trash. | | [`file_search`](https://repoprompt.com/docs/mcp-server/mcp-tools/#file_search) | Searches file paths, contents, or both, with regex, extension, path, and exclusion filters. | | [`get_code_structure`](https://repoprompt.com/docs/mcp-server/mcp-tools/#get_code_structure) | Returns root-local Code Map structure for files, folders, or the current selection. | | [`get_file_tree`](https://repoprompt.com/docs/mcp-server/mcp-tools/#get_file_tree) | Generates a project directory tree or lists loaded root folders. | | [`git`](https://repoprompt.com/docs/mcp-server/mcp-tools/#git) | Inspects Git status, diffs, history, file versions, and blame without committing or pushing. | | [`history`](https://repoprompt.com/docs/mcp-server/mcp-tools/#history) | Searches Agent Mode session history across saved workspaces and reads bounded transcript excerpts. | | [`manage_selection`](https://repoprompt.com/docs/mcp-server/mcp-tools/#manage_selection) | Manages selected files and their representation as full content, line slices, or Code Maps. | | [`manage_workspaces`](https://repoprompt.com/docs/mcp-server/mcp-tools/#manage_workspaces) | Manages workspaces, folders, and Compose tabs across RepoPrompt windows. | | [`manage_worktree`](https://repoprompt.com/docs/mcp-server/mcp-tools/#manage_worktree) | Manages Git worktrees and session bindings, and supports previewing or applying session-bound merges. | | [`oracle_send`](https://repoprompt.com/docs/mcp-server/mcp-tools/#oracle_send) | Starts or continues an Oracle conversation for chat, planning, or review. | | [`oracle_utils`](https://repoprompt.com/docs/mcp-server/mcp-tools/#oracle_utils) | Discovers Oracle model choices or lists Oracle conversations; it does not send messages. | | [`prompt`](https://repoprompt.com/docs/mcp-server/mcp-tools/#prompt) | Reads or changes shared prompt text, and lists or selects copy presets. | | [`read_file`](https://repoprompt.com/docs/mcp-server/mcp-tools/#read_file) | Reads a workspace file in full or by line range. | | [`workspace_context`](https://repoprompt.com/docs/mcp-server/mcp-tools/#workspace_context) | Builds, renders, or exports the current workspace context and its selected components. | The descriptions in this catalog explain purpose, not permission. A tool being listed or enabled does not grant workspace approval, connect a provider, or bypass a tool's validation rules. ### Changes from Classic | Classic example | Current source contract | | --- | --- | | `chat_send` | `oracle_send` for external consultations; `ask_oracle` inside eligible Agent Mode sessions. | | `list_models` | `oracle_utils` with `op="models"`. | | `chats` list/log | `oracle_utils op="sessions"`; eligible Agent Mode runs can use `oracle_chat_log`. | | Initial routing through select_tab | Prefer `bind_context` discovery and binding. Legacy compose-tab lifecycle actions remain available. | | Fixed five-minute agent waits | Configurable sub-agent default wait, with explicit per-call timeouts. | | App settings editing or auto-start keys | Use the current [allowlist](https://repoprompt.com/docs/mcp-server/mcp-app-settings/); obsolete keys are rejected. | ### Context Binding #### `bind_context` List, inspect, and bind the workspace context used by this MCP connection. `op` is `list`, `status`, or `bind`. Bind with `working_dirs`, a comma-separated string of absolute workspace roots, or a `context_id` returned by discovery. `create_if_missing` requests creation when no suitable workspace exists, subject to approval. The current global schema does not accept `window_id`. ```json {"op":"bind","working_dirs":"/Users/example/Project"} ``` Use a returned `context_id` when a stable compose-tab context is required. See [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/#context-binding). ### 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: \[{start\_line, end\_line, description}\]} | | `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. With op=set, full and codemap_only replace the corresponding selection, while slices replaces slices for the specified files and preserves unrelated full files and slices. Manual codemap_only, promote, or demote operations disable automatic codemap management. Use the returned selection to check the final representation. #### `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, Code Maps, and token counts in a single call. Default includes are `prompt`, `selection`, `code`, and `tokens`; full file contents and the selected-file tree are opt-in. Additional operations are `snapshot`, `export`, `list_presets`, and `select_preset`. Use `path` for export and returned preset identities for selection; `copy_preset` overrides rendering or token-calculation presets. #### `prompt` Get or modify the shared prompt/instructions text. | Parameter | Description | | --- | --- | | `op` | get \| set \| append \| clear \| export \| list_presets \| select_preset | | `text` | Text for set/append operations | | `path` | Output file for export | | `preset` | UUID, kind, or name for select_preset; requires an explicitly bound tab | | `copy_preset` | Optional export rendering override | #### `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) | An external app-backed call creates a fresh compose tab and runs discovery toward the context budget. During Agent Mode, it reuses the current agent tab. A `question`, `plan`, or `review` response adds Oracle analysis and returns conversation information for follow-up. Continue with the Oracle tool advertised to your connection, using the returned `chat_id`. `export_response=true` can write generated analysis to a shareable file. App-backed analysis also accepts an exposed `oracle_preset` to select its Oracle roster independently of discovery. Direct-headless execution uses a separate `context_pack_ref` contract for a persisted frozen package and rejects `oracle_preset`. Runtime depends on repository size, task scope, provider latency, and analysis type. ### 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 term or path pattern. Required. | | `mode` | `auto` (default), `path`, `content`, or `both`. Auto detects path versus content search from the pattern. | | `regex` | Regex is auto-detected by default. Set `false` for literal content matching or glob-style path matching; set `true` to force regular expressions. | | `context_lines` | Number of surrounding lines to include for content matches. | | `whole_word` | Match complete words only. | | `count_only` | Return match counts without match content. | | `max_results` | Maximum results to return (default: 50). | | `filter` | Optional `extensions`, `exclude`, and `paths` constraints. `paths` limits search to loaded workspace roots or subfolders. | Regex mode supports groups, lookarounds, and anchors. Literal mode treats special characters as text; in path mode, `*`, `?`, and `**` remain path wildcards. Large responses can be capped, with excess results omitted and the count reported. #### `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`). Reuse exact returned workspace paths. For an explicit root-qualified path, use `//`. Current read and edit resolution does not guess by basename or suffix. A worktree-bound session can show logical paths while reading from its bound checkout; inspect worktree_scope when returned. #### `get_code_structure` Get root-local Code Maps for explicit files/directories or the current selection, with optional dependency expansion. | Parameter | Description | | --- | --- | | `paths` | Optional seed files or directories; omit for the current selection. | | `expand` | `uses`, `used_by`, or `both`; omit for seeds only. | | `depth` | Relationship depth 1–4; default 1 when expansion is requested. | | `signatures` | Include signature text; default true. False requests graph-only output. | | `size` | `small`, `medium` (default), or `large`. | Inspect per-root results in mixed workspaces. `updates_pending` data can still be usable; if output reports truncation, retry with a larger `size`. Classic's `scope` and `max_results` examples are not the current schema. Global Code Maps disabling suppresses this tool. #### `file_actions` Create, delete, or move files. | Parameter | Description | | --- | --- | | `action` | create \| delete \| move | | `path` | Absolute file or folder path for every action. | | `content` | File content (for create) | | `new_path` | Absolute destination path for move. | | `if_exists` | error (default) \| overwrite | All create, delete, and move paths must be absolute, including in a single-root workspace. Create makes missing parent directories and selects the new file; `if_exists` defaults to `error`, while `overwrite` permits replacing an existing file. Delete moves the item to the macOS Trash, where it remains recoverable until Trash is emptied. Move fails if the destination exists and transfers the file's selection state. The optional operation_id is a correlation identifier, not a deduplication or replay-safety token. #### `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 {search, replace, all} for multiple edits | | `rewrite` | Complete file content for full rewrite | | `all` | Replace all occurrences (default: false) | | `verbose` | Include diff preview in response | | `on_missing` | For rewrite only: error (default) or create. | Rewrite, single search/replace, and an edits array are mutually exclusive request modes. Supply exactly one. An optional operation_id is echoed as correlation information; it does not make a repeated edit safe to replay. Applies validated edits with applicable approval checks. Use diff previews and returned status to confirm results. Workspace paths use literal-first exact resolution: reuse returned paths unchanged, or use `//` for explicit root qualification. Basename and suffix guessing are not supported. Approved external read paths remain read-only. :::tip **CLI usage:** `apply_edits` requires JSON format via `rpce-cli`: ```bash rpce-cli -e 'call apply_edits {"path":"file.ts","search":"old","replace":"new"}' rpce-cli -c apply_edits -j edits.json # From .json file (auto-detected) rpce-cli -c apply_edits -j @edits.json # From file (explicit @) echo '...' | rpce-cli -c apply_edits -j @- # From stdin ``` Use valid JSON with the intended literal search and replacement text, and inspect validation errors rather than relying on input repair. ::: ### Oracle & Model Tools #### `oracle_send` Start or continue Oracle conversations for questions, planning, or review using the configured context and models. | Parameter | Description | | --- | --- | | `message` | Your message to send | | `new_chat` | Set true to force a new conversation; otherwise a missing chat_id resumes the selected or most recent eligible conversation. | | `mode` | chat \| plan \| review | | `model` | Exposed preset name/UUID or available raw primary model override; valid only with explicit new_chat=true. | | `chat_id` | Specific chat to continue | | `attachments` | App-backed file inputs: an array of `{ "path": "/absolute/path", "title": "Optional label" }` entries. See below for supported types and path boundaries. | | `export_response` | Write the response to a shareable file and return its export information. | **Modes:** - **chat:** General conversation - **plan:** Architectural planning without immediate edits - **review:** Code review with git diff context from selected files An exact exposed preset identity wins over a raw model ID and supplies the complete Oracle roster and mapped Chat Preset. A raw override replaces the primary while retaining configured additional Oracles. Continuation preserves the established conversation configuration and rejects model overrides. Oracle consultation is separate from the agent applying file edits. **Attachments:** Use `attachments` for supported images (PNG, JPEG, GIF, WebP), UTF-8 text, and PDFs on routes that accept native documents. Each path must be canonical and absolute, inside a loaded workspace root or the exact path of a file the user attached to this agent session. Unsupported input is refused; files are not silently omitted. Remote URLs and direct-headless attachment requests are not supported. The older `images` argument is an image-only compatibility alias; do not send it together with `attachments`. ```json { "message": "Review the layout against this screenshot.", "new_chat": true, "mode": "review", "attachments": [{"path": "/Users/example/Project/design/current.png", "title": "Current layout"}] } ``` Originals are sent for this turn only, and to each lane in a grouped request. Continue with the returned conversation IDs and explicitly attach files again if needed. Inspect individual lane statuses and export errors before retrying. See [Oracle](https://repoprompt.com/docs/agent-mode/oracle/) for grouped-result review and attachment usage. Oracle attachment limits are **10 files**, **20 MiB per file**, and **50 MiB total** before provider encoding. UTF-8 text files must also fit the **512 KiB** inline-text limit; larger files are refused rather than truncated. Provider request and model-context limits still apply. #### `ask_oracle` During eligible Agent Mode runs, consult an Oracle in the current agent context with `message`, optional `chat_id`, `new_chat`, `mode`, `attachments`, and `export_response`. Omit chat_id or set new_chat=true to start; otherwise continue that conversation. A primary `model` override is allowed on a new conversation and rejected on continuation. Use the tool actually advertised to your connection. #### `oracle_utils` Read-only helpers for model choices and Oracle conversation discovery. | Parameter | Description | | --- | --- | | `op` | models \| sessions | | `context_id` | Narrow sessions to a context UUID returned by bind_context. | | `scope` | workspace \| tab; context_id infers the narrowed scope. | | `limit` | Bound the session list. | With `op="models"`, list model choices and exposed presets relevant to Oracle sends. Use a returned identity rather than guessing a model or preset name. With `op="sessions"`, discover conversations to inspect or continue. #### `oracle_chat_log` During eligible Agent Mode runs, recover recent Oracle messages after compaction or while continuing a consultation. Supply optional `chat_id`, `limit` of 1–50 messages (default 8), and `include_user` (default false). This reads history without sending a new turn. ### Git Tools #### `git` Safe, token-efficient git abstraction for MCP agents. Also supports Jujutsu (jj) repositories natively. See [Workflow Commands](https://repoprompt.com/docs/mcp-server/workflow-commands/#git-integration) for review-oriented usage. | Parameter | Description | | --- | --- | | `op` | status \| diff \| log \| show \| blame | | `repo_root` | Repository path or loaded root name. Use `@main` for the main checkout or `@wt` for the current checkout, either alone or appended to a root such as `Project@main`. Omission uses the session-aware default described below. | | `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` and `trunk` 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 **Default repository:** When `repo_root` is omitted, the session's sole applicable worktree binding selects the checkout. With no session worktree bindings, the default is the workspace's declared **PRIMARY** root, not the first root to finish loading. If that root is unavailable or is not a Git repository, the tool does not silently fall back to another root. Multiple session bindings have no default: identify the repository explicitly with a path, root name, or `repo_key`. Bare `@main` and `@wt` still require a default repository and do not resolve that ambiguity. **Worktrees:** Status and diff output include worktree metadata such as the branch and main checkout path. Use a qualified selector such as `Project@main` or `Project@wt` to identify both the repository and checkout. The `@main` selector chooses a checkout; `compare="main"` chooses a comparison base. These are separate settings. **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 \| hide \| unhide \| 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 for supported lifecycle operations; separate from bind_context. | | `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. #### `manage_worktree` List, inspect, create, and bind Git worktrees for Agent sessions, or preview and apply a session-bound merge. Management operations are `list`, `show`, `create`, `bind`, `select`, and `unbind`; merge operations are `preview`, `apply`, `status`, `continue`, and `abort`. Use returned worktree IDs and an explicit session_id when routing does not resolve an active Agent session. Preview is non-mutating; apply requires its operation_id and the applicable confirmation or routed UI approval. Continue and abort require confirmation outside routed UI flows. See [Worktrees](https://repoprompt.com/docs/worktrees/). The source must be clean and committed, and the target must be clean. For the human review card, stale previews, and conflict recovery in the target checkout, see [Review and Merge](https://repoprompt.com/docs/worktrees/review-and-merge/). ### App Settings #### `app_settings` Read and update allowlisted global preferences for appearance, prompt packaging, models, Context Builder, MCP preset visibility, Code Maps, file scanning, selected Agent Mode behavior, and notifications. Credentials, tool ACLs, permission policies, and workspace model override dictionaries are excluded. | Parameter | Description | | --- | --- | | `op` | `list` \| `get` \| `set` \| `options` | | `group` | `ui`, `prompt_packaging`, `models`, `context_builder`, `mcp`, `code_maps`, `file_system`, `agent_mode`, `notifications`. 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, string array, or null, matching the catalog's declared type. The additional Oracle roster is an array; `prompt_packaging.prompt_sections_order` is a string containing a JSON array, not a native array. | | `agent` | For options: filter to a supported CLI backend, such as claudeCode or codexExec. | | `limit` | For `options`: maximum number of candidates returned (1–200, default 60). | | `detailed` | For `options`: include descriptions and model metadata in each candidate. | Call list first to discover the actual keys and types in the running build. Obsolete Classic editing and auto-start keys are not part of the current registry. **Examples:** ```text # Browse the catalog (values always included) { "op": "list" } # Inspect one group { "op": "list", "group": "ui" } # Batch read { "op": "get", "keys": ["ui.appearance_mode", "mcp.show_model_presets"] } # Toggle a flag { "op": "set", "key": "ui.show_tooltips", "value": false } # Clear an optional model { "op": "set", "key": "models.planning_model", "value": null } # Switch the Context Builder agent (remembered model is preserved) { "op": "set", "key": "context_builder.agent", "value": "codexExec" } # List candidate values for a setting that advertises options_available { "op": "options", "key": "models.planning_model", "agent": "codexExec" } ``` **See the standalone** [App Settings Tool](https://repoprompt.com/docs/mcp-server/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 RepoPrompt's Agent Mode sessions. ::: #### `agent_run` Session-based control surface for long-running Agent Mode runs. Each start returns a session_id for poll, wait, steer, respond, and cancel. Use agent_manage for durable session history and metadata. Discover authoritative role mappings in its task_labels response; an omitted start model_id resolves through the pair role. Explicit model/effort targets come from the live catalog. Start-only worktree arguments can establish an isolated checkout before provider startup. When model routing is enabled in Agent Decisions, new starts with an omitted model_id or a role label can be routed across configured sub-agent targets. A compound model_id or explicit model_parameters pins the target and bypasses that automatic routing. A wait timeout bounds the waiting call; inspect the returned status and keep monitoring an active run rather than starting a duplicate. **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`, optional `timeout` | Blocks until input is needed or a terminal/interesting state is reached. A multi-session wait returns when the first session reaches such a state. Default is the configured sub-agent wait, initially 120 seconds. Timeout=0 polls immediately. 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 the existing session, injecting into an active run or starting its next run after completion. Optional wait=true or timeout_seconds waits for a result using the configured default when no explicit timeout is given. Use respond for waiting_for_input. Start always creates a new session. | | `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:** Depending on state and operation, responses can include session_id, status, status_text, assistant_text, transcript_item_count, failure_reason, session identity and parentage, and available agent/model information. Use the current snapshot's interaction_id and advertised response choices rather than reusing an older pending interaction. **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:** 1. Call `agent_run op=start message="..."` → receive `session_id` 2. Call `agent_run op=wait session_id="..."` → waits up to the configured duration or explicit timeout until input is needed or the run reaches an interesting state 3. When `status=waiting_for_input`, call `agent_run op=respond` with the returned `interaction_id` and an appropriate `response` 4. 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` | optional `roles_only` | List task_labels role mappings and exact agent/model/effort targets. roles_only=true omits the full explicit target catalog. | | `list_sessions` | `limit`, `state` | List live and persisted sessions, returning session IDs. Agent Mode callers are scoped to their spawned sessions. Filter by advertised state values; MCP-originated sessions are identified in the response. | | `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 up to 256 unique valid MCP-originated session UUIDs. User-created and active sessions are protected. Validates the array before mutation and reports per-ID outcomes; inspect partial, cancellation, and retry results. | | `extract_handoff` / `handoff` | `session_id` | Export handoff XML for a live or persisted session. Use output_path for a file; file-content snapshots require an active live source context. | | `list_workflows` | — | List available agent workflows. | **Session IDs:** Use returned full UUIDs. Within agent_manage, use list_sessions for metadata and get_log for faithful transcript XML with turn pagination. The separate history tool has a bounded get_session operation for historical search results. **Workflow runs:** To start a workflow-backed run, use agent_run op=start with workflow_id or workflow_name and a message. Then use its returned session_id for wait, respond, and other run-control operations. #### Agent Control Plane Examples ```text # Discover available agents and workflows agent_manage op=list_agents agent_manage op=list_workflows # List recent sessions, filter by state agent_manage op=list_sessions limit=10 agent_manage op=list_sessions state=failed # Read a session transcript agent_manage op=get_log session_id="" limit=5 # Stop a running session agent_manage op=stop_session session_id="" # Clean up old MCP-originated sessions agent_manage op=cleanup_sessions session_ids=["",""] # Start a run and control it agent_run op=start message="Investigate the auth flow" agent_run op=wait session_id="" agent_run op=wait session_id="" timeout=10 # Steer and wait for result in one call agent_run op=steer session_id="" message="Now fix it" wait=true # Respond to a pending approval agent_run op=respond session_id="" interaction_id="" response="accept" # Respond to a question agent_run op=respond session_id="" interaction_id="" response="Use the staging API" # Start a workflow-backed run agent_run op=start workflow_id="" message="Add logout support" # Then use agent_run to wait/respond on the returned session_id # Orchestrate: start multiple agents in parallel, wait for the first to finish agent_run op=start model_id="engineer" message="Task A" detach=true # → session_id_1 agent_run op=start model_id="engineer" message="Task B" detach=true # → session_id_2 agent_run op=wait session_ids=["",""] timeout=60 # Poll all agents at once for a dashboard view agent_run op=poll session_ids=["","",""] # Use the orchestrate workflow for automatic planning and delegation agent_run op=start workflow_name="orchestrate" message="Refactor auth into separate module" ``` :::tip **Tool Availability:** Individual tools can be enabled or disabled in **MCP Tools settings**. Disabled tools are withdrawn from the advertised list. Agent control tools are also gated by connection policy and may not appear on every connection. ::: ### Policy-Gated and Sub-Agent Internal Tools In addition to the 21 advertised tools above, RepoPrompt defines **10 policy-gated and sub-agent internal tools** that are omitted from the standard external catalog and activated dynamically within eligible Agent Mode and authorized cross-session oversight contexts: | Tool | Brief Description | | --- | --- | | [`ask_user`](https://repoprompt.com/docs/mcp-server/mcp-tools/#ask_user) | Prompts the user with structured questions, optional suggested answers, and configurable timeouts. | | [`ask_oracle`](https://repoprompt.com/docs/mcp-server/mcp-tools/#ask_oracle) | Consults the configured Oracle model directly from an eligible Agent Mode session. | | [`oracle_chat_log`](https://repoprompt.com/docs/mcp-server/mcp-tools/#oracle_chat_log) | Reads recent Oracle conversation history (`limit` 1–50) during an Agent Mode run without sending a new turn. | | `agent_session_link` | Manages cross-window and cross-session communication links, steering, model targeting, and auto-wake snoozing. | | `session_admin` | Administers sessions within a user-granted delegation scope, including session tree inspection, organization, worktree binding, and merge coordination. | | `become_overseer` | Requests promotion of the calling session to an overseer role to coordinate sibling sessions. | | `self_compact` | Requests self-compaction or context inspection (`op="context"` or `"compact"`) of the agent's own session context. | | `share_thoughts` | Publishes reasoning thoughts or plan progress to the session timeline. | | `set_status` | Updates the human-visible status indicator on the session card. | | `wait_for_next_user_instruction` | Signals that the agent has completed its turn and is waiting for the next user instruction. | ### Exploration, History, and Session Coordination #### `agent_explore` Launch short-lived read-only exploration children for narrow codebase probes. Operations are start, poll, wait, and cancel. Supply message or a batch of messages, save the returned session IDs, and use session_id or session_ids for monitoring. The role is always Explore, with no custom model/workflow selection, session reuse, steering, or responding. Explore children cannot edit, consult Oracles, or recursively delegate. Start-only worktree controls can isolate their reads. #### `history` Search saved Agent Mode transcripts across workspaces with list_sessions, search, time, and bounded get_session operations. Window context does not automatically restrict history to one workspace; pass a workspace filter when needed. Search first, then read a small turn window using the returned session ID and turn location. Narrow truncated scans by workspace, dates, or session rather than requesting a whole transcript. #### `ask_user` Ask structured questions, each with stable id and question fields and optional suggested answers. Title and context frame the interaction. The optional timeout_seconds overrides the global Question Timeout. Inspect timed_out, skipped, and answers keyed by question ID. Availability depends on the session's interaction policy. #### Oversight tools For the interface and ordinary task workflow, see [Overseer Mode](https://repoprompt.com/docs/overseer/), including [Lanes](https://repoprompt.com/docs/overseer/lanes/) and [Linking Sessions](https://repoprompt.com/docs/overseer/linking-sessions/). For authorized cross-session oversight and multi-agent administration, RepoPrompt provides three policy-gated tools: - **`agent_session_link`** — Manages cross-window and cross-session communication links. Supported operations: `list`, `poll`, `wait`, `read`, `send`, `cancel_pending_send`, `compact`, `set_waiting_on`, `snooze_auto_wake`, `request_attention`, `respond`, `steer`, `stop`, `create_lane`, `retire_lane`, and `set_model`. - **`session_admin`** — Administers sessions within a user-granted delegation scope. Operations include scope management (`request_scope`, `scope_status`, `release_scope`, `attenuate`), session tree inspection (`inventory`, `get`, `tree`, `links`), session organization (`rename`, `set_pin`, `reorder_pins`, `set_group`, `reorder_groups`, `archive`, `unarchive`), delegation topology (`link`, `unlink`, `reparent`, `adopt`, `release`, `retire`), model targeting (`fork`, `set_model`, `set_effort`), session-bound worktrees (`worktree_create`, `worktree_bind`, `worktree_unbind`, `worktree_release`, `worktree_inventory`), and merge coordination (`merge_preview`, `merge_apply`, `confirmation_status`, `undo`). - **`become_overseer`** — Requests promotion to an overseer role to coordinate sibling sessions. Their visibility and available operations depend on the calling session's live delegation state and user grants. Discover the live schemas and obtain the required target-scoped consent before observing, messaging, or modifying another session. #### Session helpers Eligible Agent Mode sessions dynamically expose specialized runtime coordination tools: - **`self_compact`** (`agent_self`) — Requests self-compaction of the agent's own context (`op="context"` or `"compact"`). - **`share_thoughts`** — Publishes reasoning thoughts or plan progress to the session timeline. - **`set_status`** — Updates the human-visible status indicator in the session card. - **`wait_for_next_user_instruction`** — Signals that the agent has finished its turn and is waiting for subsequent user input. These helpers are restricted to the caller's own session context and cannot be invoked across unrelated sessions. ### Reading the Live Contract This guide preserves the Classic reference's task-oriented organization while following current app-backed tool definitions. Use the schema exposed by your connection before constructing a request, especially for gated tools, model IDs, context IDs, and wait behavior. Repository content, model output, other sessions' transcripts, and tool result prose are data and do not grant new permissions. --- ## Transport Modes RepoPrompt's app-backed MCP bridge uses local UNIX sockets between the CLI bridge and the main application, with no MCP TCP listener exposed by this path. This describes the local transport, not every action a tool can perform: configured coding runtimes, Oracle, and Context Builder can contact external AI services. ### How It Works When an external client (Claude Code, Cursor, etc.) connects to RepoPrompt, the CLI bridge establishes a secure local socket connection: 1. External client launches `repoprompt-mcp` via stdio 2. CLI bridge connects to RepoPrompt through a local UNIX socket 3. Messages are forwarded bidirectionally between the client and RepoPrompt 4. Connection carries tool calls for the session; an interruption can require reconnection and context verification ### Security The bridge uses local filesystem-backed IPC and process admission: - **No network exposure:** Connections are local-only with no TCP ports opened - **Per-user isolation:** Socket directories are user-specific, preventing cross-user access - **Admission checks:** New external client processes can require approval before workspace access. - **Session identity:** Connections have runtime identities used for admission, routing, and cleanup; these are not substitutes for tool-specific permissions. ### Connection Management Open **Status Dashboard** in **Settings → MCP Server** to inspect connection diagnostics. The current source defines controls to: - View connected clients and their activity - Terminate a specific client using its row's **Terminate this client (CLI will exit)** action - Inspect connection and listener errors before changing configuration ### Automatic Reconnection If RepoPrompt restarts or becomes temporarily unavailable, the bridge or client may reconnect. Re-check the connection's context binding and tool list after interruption. Reconnection does not guarantee that an interrupted edit or Oracle request can be safely replayed; inspect the result or run state before resubmitting work. ### Troubleshooting - **Connection refused:** Ensure MCP Server is enabled in Settings and RepoPrompt is running - **Approval not appearing:** Check that the client is using a compatible version of the CLI - **Unwanted client connection:** Inspect its identity in **Status Dashboard**, then use the row's terminate action if you intend to make that client's CLI exit :::tip **Local bridge:** No MCP TCP port is opened by this app-backed path. That does not make model execution offline: configured CLI agents, Context Builder, and Oracle consultations may contact external AI services. ::: ### Generated Backend Selection Use the app-generated command and `args: ["--backend", "app"]` for the UI-backed integration. A direct-headless backend is a separate execution mode; it is not a transport toggle and does not imply the same window context or UI behavior. The current server UI does not offer Classic's **Filesystem transport** fallback or a **Multi-Window Mode** switch. Older configuration structures can contain legacy transport preferences, but they are not instructions to change firewall, VPN, or local-network permissions for this socket bridge. ### Window Access and Shared Listener The listener is shared, while MCP tool access is controlled per window. Disabling a window's tools is different from stopping the listener. **Force Stop Listener** in Settings shuts down the listener for every window and client; use the per-window access switch when only that window should stop exposing tools. See [Settings & Presets](https://repoprompt.com/docs/mcp-server/mcp-settings/) for the controls and [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/) for context binding and reconnection checks. --- ## Setup Wizard The Setup Wizard recommends a configuration based on your available providers and the app's best-practice profiles. It helps align Oracle models, Context Builder, MCP preset exposure, and sub-agent role defaults. It configures model choices; installing the external MCP client connection remains a separate step in [Setup Guide](https://repoprompt.com/docs/mcp-server/mcp-setup/). ### Open the Wizard Click the toolbar's lightbulb to open **Setup Wizard**. The neighboring server icon opens the MCP Server popover. A yellow lightbulb indicates active recommendations. Toolbar lightbulb for Setup Wizard beside the green MCP server icon The intro lists recommendations, provider status, and a **Best Models by Use Case** reference. **Start Wizard** reviews the recommendations step by step. **Quick Apply All** applies eligible, unsatisfied recommendations that have not been muted. Setup Wizard intro with one Context Builder recommendation, provider status, best-model reference, Quick Apply All, and Start Wizard The screenshots capture particular model choices, connected providers, and a four-step walkthrough from an earlier build. Recommendations change with the app's catalog, provider availability, settings, and provider filter. See [Models → Recommendations and screenshots](https://repoprompt.com/docs/providers/models/#recommendations-and-screenshots) for how to interpret these examples. The number and order of steps also vary: satisfied or muted recommendations can be omitted, while an available role-defaults review can still be shown. ### Check the Settings Scope Read the **Agent Models** label near the heading and footer before applying a recommendation. **Global settings** means the workspace inherits the global Agent Models profile, so changes affect that profile. **Workspace — [name]** means the wizard targets that workspace's overrides. The wizard follows the effective Agent Models scope; it is not always creating workspace-local changes. MCP preset exposure has its own global scope. A recommendation to hide or show presets changes what MCP can discover without deleting the saved presets. Use [Agent Models](https://repoprompt.com/docs/settings/agent-models/) to inspect inheritance, workspace overrides, Oracle models, and role defaults. ### Choose Providers for Recommendations Open **Providers** to choose which provider families the recommendation engine may consider. The screenshot includes Codex CLI, Claude Code, Cursor CLI, Grok Build, and OpenAI API. Unchecked providers are excluded from the next recommendation calculation. Providers for Recommendations popover with five checked provider families, Reset, and Apply Choose **Apply** to recompute recommendations using the selected set, or **Reset** to restore all providers. This filter shapes recommendations; it does not install a provider, authenticate an account, disconnect an integration, or change which provider a manually selected session can use. Provider readiness and the selection filter are separate facts. ### Review Context Builder The Context Builder step shows a recommended agent, model, and explanation. Context Builder explores your codebase and selects files toward a context budget before the requested follow-up analysis. Its discovery model is distinct from the Oracle model used for a plan, review, or answer. Context Builder recommendation showing the selected Codex discovery model and its explanation **Apply & Next** saves the recommendation to the displayed settings scope and advances. **Skip** advances without applying it. **Back** returns to an earlier step. The recommendation in the screenshot is not a model you must choose; configure a supported, authenticated provider that fits your account and task. Change the discovery model later in [Agent Models](https://repoprompt.com/docs/settings/agent-models/); question behavior and context budgets live in [Context Builder settings](https://repoprompt.com/docs/settings/context-builder/). Complete Context Builder recommendation step with Back, Skip, overflow menu, and Apply & Next controls ### Skip or Mute a Recommendation Skipping leaves the current settings as they are. To dismiss a recurring recommendation, open the step's overflow menu and choose **Mute this recommendation**. The intro also offers a dismissal control beside active recommendations. Muting suppresses that recommendation in the wizard; it does not apply the recommended value. Muted differences can appear under **Dismissed Recommendations**, with **Restore** to make them eligible for review again. This is separate from **Show presets** in the MCP popover, which restores preset exposure. Full wizard footer with Skip, the overflow menu, Apply & Next, and Mute this recommendation ### Review Agent Role Defaults The role-defaults step shows the recommended CLI agent and model for each task label. External callers use these roles when launching agents without pinning an exact compound model target. The current `agent_run` contract resolves an omitted `model_id` through the `pair` role; clients can discover the authoritative role mappings with `agent_manage op="list_agents"` and its `task_labels` response. | Role | Intended work | | --- | --- | | **Explore** | Fast, read-only exploration and codebase mapping. | | **Engineer** | Balanced engineering work. | | **Pair** | Interactive pair programming with a higher-capability model (default when `model_id` is omitted in `agent_run`). | | **Design** | Architecture, design critique, and creative problem solving (produces Markdown design/review documents under `docs/`). | Agent Role Defaults step with Explore, Engineer, Pair, and Design model choices and a Configure button Use **Configure…** to inspect or adjust the role configuration, then **Next** to continue. The model names shown are examples, not permanent defaults for every installation. An explicit model target from the live agent catalog can pin a different provider/model/effort combination. ### Summary and Next Steps The Summary shows the resulting Oracle and role configuration, including settings that already matched. **All Set!** can therefore appear without applying a change during this walkthrough. Check the summary and choose **Done** to close it. Wizard Summary showing an already-matching Oracle and role configuration, followed by Context Builder and MCP next steps Try Context Builder from the Compose view to curate context, or connect an external client and invoke `context_builder` over MCP. Consult the [Tools Reference](https://repoprompt.com/docs/mcp-server/mcp-tools/) for the current names and parameters rather than using tool names from older Classic guides. Complete Summary step showing the matched configuration, next steps, Back, and Done ### When No Recommendations Are Needed If the effective configuration already matches the selected best-practice profile, the wizard can report **Your setup looks good!** and offer **Close**. Some builds present this as **Setup Status** with provider status, reference models, and any dismissed recommendations. It confirms the recommendation check; it does not prove that an external client is installed or connected. Setup Wizard reporting no recommendations, with provider status and the best-model reference Use the [MCP Server popover](https://repoprompt.com/docs/mcp-server/mcp-settings/) to verify window access and connections, and [Setup Guide](https://repoprompt.com/docs/mcp-server/mcp-setup/) to install the client integration. --- ## Workflow Commands RepoPrompt's workflow instructions guide an external coding agent through a process: understanding a task, finding relevant code, planning, delegating, implementing, or reviewing. Commands such as `/rp-build` select those instructions; they are not additional MCP tools or server-enforced execution pipelines. Depending on the installation target, the instructions are packaged as on-disk skills or prompt files. A **skill** is the discoverable package; the **workflow instructions** are the procedure it contains. The MCP connection supplies the tools that the procedure can request. Install these separately from the MCP server configuration through **Quick Setup → Skills**. Then use your client's skill or slash-command picker to find commands such as `/rp-orchestrate`, `/rp-deep-plan`, and `/rp-build`. The picker and invocation syntax depend on the client; `/repo` is not a universal command that every integration provides. Quick Setup Skills menu entry beside client installation and copy configuration ### Installing workflow instructions The **Skills** menu offers shared global or per-project `.agents/skills`, Claude Code integration, and RepoPrompt's isolated Codex prompts. Select the **MCP** variant when the agent uses native MCP tools, or the **CLI** variant when it calls `rpce-cli`. CLI variants use the corresponding `-cli` skill names (such as `/rp-orchestrate-cli` or `/rp-deep-plan-cli`). Install the CLI executable as well when choosing that variant. | Menu Group and Option | Scope and Destination | Variant and Invocation | | ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Shared (.agents/skills) → Global** | `~/.agents/skills//SKILL.md` | Shared convention for Codex CLI and compatible agents across all projects. | | **Shared (.agents/skills) → Per-project** | `/.agents/skills//SKILL.md` | Installs in each loaded workspace folder for project-isolated workflows. | | **Claude Code (.claude/commands) → Per-project** | `/.claude/skills//SKILL.md` | Installs modern Claude Code skills in each loaded root and migrates legacy flat command files. | | **RepoPrompt Codex (isolated prompts) → Global** | `~/.repoprompt/codex/prompts/.md` | Installs workflow prompts in RepoPrompt's isolated Codex environment. | Each destination submenu offers **MCP skills**, **rpce-cli skills** (or the running build's CLI name), and **Uninstall**. The MCP variant instructs an agent to call RepoPrompt tools directly. The CLI variant instructs it to use the installed terminal command (`rpce-cli`). Choose the variant that matches how your client accesses RepoPrompt. :::note[Skills and Agent Mode Workflows] Installed workflow instructions, Agent Mode's workflow templates, and Copy/Chat Workflow Presets are distinct configuration surfaces. The server connection alone does not install the external instruction files. Use [Agent Workflows](https://repoprompt.com/docs/settings/agent-workflows/) for the in-app Workflow picker and [Workflow Presets](https://repoprompt.com/docs/settings/workflow-presets/) for copy and built-in chat packaging. ::: ### How Workflow Commands Work The installed implementation, planning, review, and investigation workflow templates instruct the coding agent to use repository discovery, explore-agent delegation, and the appropriate Context Builder/Oracle calls. Their templates direct workflows such as `/rp-build` and `/rp-orchestrate` through steps like these: 1. **Workspace verification** — The agent verifies that the target repository is bound and loaded before initiating any planning or tool execution. 2. **Surface mapping & reconnaissance** — The agent contextualizes the prompt into actual codebase nouns, optionally fanning out parallel read-only `explore` agents for targeted reconnaissance. 3. **Context curation via Context Builder** — A specialized research model explores the codebase, selecting files within a token budget using full content for key files and codemaps for reference files. 4. **Analysis & specification** — An advanced analysis model receives the curated context and produces an architectural plan, review, or investigation report. 5. **Delegated execution or implementation** — The agent acts on the result: either directly implementing changes with `apply_edits` or orchestrating specialized sub-agents (`pair`, `engineer`, `design`) with clean context boundaries. The intended separation keeps the coordinator focused while sub-agents or Context Builder handle the heavy reading. These are workflow instructions, not an MCP-enforced execution order: the host application and its coding agent control whether and in what order tools are invoked, subject to available tools and permissions. ### Available Commands RepoPrompt installs a comprehensive suite of workflow commands. External agents discover these as slash commands matching their installed variant (`/rp-` for MCP, `/rp--cli` for terminal CLI): #### 1. Orchestrate (`/rp-orchestrate`) **Plan, decompose, and delegate complex tasks across multiple agents.** ```text /rp-orchestrate ``` - **Arguments:** `task` (required) — Description of the complex task to plan, decompose, and delegate. - **Primary Roles:** Orchestrator (coordination), `pair` (default for complex multi-file work), `engineer` (clear/well-scoped items), `design` (UI, layout, polish, text), `explore` (narrow reconnaissance). - **Core Philosophy:** The orchestrator coordinates, plans, and verifies; it does **not** implement code directly or perform deep reading itself. Sub-agents execute each work item in fresh context windows to prevent context exhaustion and hallucination. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms the target codebase is loaded and identified before planning. - **Phase 1: Contextualize the Task** — Translates user instructions into concrete codebase nouns (modules, filenames, patterns). Dispatches a narrow `explore` agent if ambiguous, then calls `context_builder` with `response_type: "plan"` and `export_response: true` to generate an architectural plan file. - **Phase 2: Decompose into Work Items** — Breaks the plan into up to 5 discrete, ordered work items with explicit "done when" criteria, file boundaries, dependencies, and verification steps. - **Phase 3: Dispatch (Verify-then-Dispatch Loop)** — Dispatches fresh sub-agents for each work item. Sub-agents read the exported plan file via `read_file` as read-only context. Alternatively, tightly coupled items can steer an existing agent. The orchestrator updates the plan file via `apply_edits` as items are completed. - **Phase 4: Monitor and Verify** — Verifies each completed item against its acceptance criteria, runs tests, and produces a final rollup of completed work and known follow-ups. --- #### 2. Deep Plan (`/rp-deep-plan`) **Deep planning workflow that produces a polished, ready-to-execute plan document without implementation.** ```text /rp-deep-plan ``` - **Arguments:** `topic` (required) — Description of what to plan (feature, refactor, migration, redesign). - **Sole Deliverable:** A polished, executable specification document at `docs/plans/-.md`. - **Core Philosophy:** Strictly planning only. Explore agents map seams and external research; Context Builder generates the implementation specification baseline; a design agent performs an independent critique; the orchestrator retains authorial ownership, ensuring lossless consolidation and verified references. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms workspace readiness. - **Phase 1: User Involvement Decision (Required First Interactive Action)** — Uses `ask_user` to prompt the user for their preferred involvement level: - **Up front** — Grounded interview before broad exploration begins (pauses in Phase 1.5). - **Mid-flow** — Review the draft before the design agent critique (pauses in Phase 5). - **Hands-off** — Complete the full plan autonomously, then refine interactively (pauses in Phase 7). _(Note: If Up front or Mid-flow is chosen, a subsequent timeout on `ask_user` halts the run rather than guessing.)_ - **Phase 1.5: Grounded Interview** _(only if Up front)_ — Dispatches 1–2 narrow ambiguity scouts, then asks 2–4 code-grounded questions before proceeding. - **Phase 2: Map the Seams** — Fans out parallel explore agents across three distinct lanes: in-workspace seams (always), external research (APIs/libraries/RFCs), and prior art (`docs/plans/`, commit history). - **Phase 3: Scaffold the Plan File** — Creates `docs/plans/-.md` seeded with Goal, Background (distilled evidence), Open Questions, and References. - **Phase 4: Context Builder Plan Pass** — Calls `context_builder` with `response_type: "plan"` and `export_response: true`. Builds a coverage ledger of all implementation-bearing facts, interfaces, error cases, and verification requirements. - **Phase 5: Mid-flow Check-in** _(only if Mid-flow)_ — Pauses to ask 2–4 targeted draft ambiguity questions via `ask_user`. - **Phase 6: Bounded Completeness and Design Critique** — Dispatches a `design` agent to evaluate the draft against the codebase and original Context Builder export, writing a focused review under `docs/reviews/`. - **Phase 7: Fidelity-Preserving Editorial Polish** — Integrates critique findings, verifies every symbol/link/line reference, removes transcript narration, and ensures the document is directly executable. - **Phase 7.5: Final Fidelity Check & Cleanup** — Walks the coverage ledger to confirm no supported detail was dropped, then safely deletes the temporary export file. --- #### 3. Optimize (`/rp-optimize`) **Iterative performance optimization loop run as a delegation-first orchestration.** ```text /rp-optimize ``` - **Arguments:** `target` (required) — Metric, scope, and stop criterion (e.g., `"reduce p95 latency of PathMatcher.match under PathMatchingTests"`). - **Core Philosophy:** Performance work only improves what can be measured. Gathers evidence outward from callers, inputs, and shared infrastructure; gates all instrumentation behind debug flags; preserves causality with one attributed change per serial loop; and records all runs in a persistent scoreboard. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms the target repo is loaded. - **Phase 1: Surface Mapping & Bottleneck Scouting** — Fans out parallel `explore` agents across five areas: bottleneck candidates around target callers and inputs, target & call graph, prior perf work (benchmarks/traces), conventions (sanctioned test/bench commands in AGENTS.md), and scope boundaries. - **Phase 2: Plan Setup with Context Builder** — Runs `context_builder` (`response_type: "plan"`, `export_response: true`) to define the metric, debug-gated instrumentation strategy in a secondary support file, baseline procedure, ranked first-pass candidates, and the scoreboard scaffold. - **Phase 3: Land Instrumentation & Baseline** — Dispatches a `pair` agent to land debug-only instrumentation, verify release builds strip it, take 3–5 baseline samples, and initialize `prompt-exports/optimize--runs.md`. - **Phase 4: The Optimization Loop (Serial)**: - **4a. Plan next optimization** — Uses Context Builder with the scoreboard in selection to plan one single change. - **4b. Dispatch optimize-and-harden** — Dispatches one `pair` agent to implement the change, run tests, re-measure, and append a new row to the scoreboard. - **4c. Verify via scoreboard** — Compares results against the variance band and confirms test passage. - **4d. Consult Oracle on next step** — Prompts the Oracle (`oracle_send` or `ask_oracle`) with the updated scoreboard to decide whether to continue or stop. - **Termination:** Exits when the Oracle signals diminishing returns, the target metric is met, or the hard 5-iteration cap is reached. - **Phase 5: Final Rollup** — Summarizes starting vs. final metric deltas, landed optimizations, reverted attempts, and state of instrumentation. --- #### 4. Review (`/rp-review`) **AI-powered code review combining Git diffs and branch comparisons with architectural codebase understanding.** ```text /rp-review [scope] ``` - **Arguments:** `scope` (optional) — Comparison scope: `'uncommitted'` (default), `'staged'`, `'back:N'` (last N commits), or a branch/commit range like `'main...HEAD'`. - **Core Philosophy:** Surface-level reviews catch typos; deep reviews catch subtle architectural regressions, security oversights, broken error paths, and API contract violations. Combines Git diff inspection with RepoPrompt's semantic context. **Workflow Steps:** - **Step 0: Verify Workspace** — Confirms the target repository window. - **Step 1: Survey Changes** — Runs `git op="status"`, `git op="log"`, and `git op="diff" detail="files"` to inspect modified files and commit history. - **Step 2: Determine Scope** — Infers or confirms the comparison target (e.g. comparing current branch against `main` or merge-base). - **Step 3: Deep Review via Context Builder** — Calls `context_builder` with `response_type: "review"`, supplying diff files and comparison scope. Context Builder gathers relevant surrounding types and architecture, invoking the review model to evaluate correctness, security, breaking changes, and edge cases. - **Step 4: Clarify Findings** — Optionally continues the conversation via `oracle_send` (or `ask_oracle`) in the returned chat session to explore remediation steps or investigate specific findings. --- #### 5. Refactor (`/rp-refactor`) **Refactoring assistant that analyzes code organization, identifies duplication and complexity, and safely implements improvements.** ```text /rp-refactor [target] ``` - **Arguments:** `target` (optional) — Files, directory, or module to analyze (e.g., `'Sources/Auth'`, `'the networking layer'`). - **Core Philosophy:** Strictly preserves external behavior while improving readability, cohesion, and testability. Uses explore agents to scout before planning, and verifies tests after every individual change. **Workflow Steps:** - **Step 0: Verify Workspace** — Confirms repository binding. - **Step 1: Scope & Analyze** — Dispatches parallel `explore` agents to map types, dependencies, and duplication across the target area, then runs `context_builder` with `response_type: "review"` informed by those findings. - **Step 2: Plan** — Runs `context_builder` with `response_type: "plan"` and `export_response: true` to generate an incremental, risk-assessed refactoring plan. - **Step 3: Decompose & Dispatch** — Breaks the refactoring plan into discrete work items and dispatches `pair` or `engineer` sub-agents to implement changes step by step. - **Step 4: Verify** — Runs project tests after each step, spot-checks diffs for semantic preservation, and confirms that public API contracts remain unchanged. --- #### 6. Plan & Build (`/rp-build`) **End-to-end implementation workflow for new features, bug fixes, and significant codebase additions.** ```text /rp-build ``` - **Arguments:** `task` (required) — Description of the feature or task to implement. - **Core Philosophy:** Avoids shallow implementations by requiring orientation and deep context gathering before touching code. Context Builder generates the architectural blueprint; the agent then executes changes directly using RepoPrompt's editing tools. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms workspace context. - **Phase 1: Quick Scan** — Runs lightweight directory tree (`get_file_tree`) and targeted searches (`file_search`, `get_code_structure`) to map user instructions to exact codebase components. - **Phase 2: Context Builder** — Calls `context_builder` with `response_type: "plan"` using the reformulated prompt. Context Builder curates full files and codemaps into context, returning an actionable implementation plan. - **Phase 3: Consult Oracle (Optional)** — If the plan leaves concrete ambiguities, consults the Oracle (`oracle_send`) to resolve specific questions before editing. - **Phase 4: Implement Directly** — Applies changes iteratively using `apply_edits` (single search/replace, edits array, or full rewrite) and `file_actions`, verifying results against diff previews and running relevant unit tests. --- #### 7. Investigate (`/rp-investigate`) **Systematic, hypothesis-driven bug and root-cause investigation.** ```text /rp-investigate ``` - **Arguments:** `issue` (required) — Description of the bug, crash, regression, or research topic. - **Core Philosophy:** Read-only source inspection, with findings, traces, and hypotheses written to an investigation report. The current template explicitly prohibits source-code changes; it gathers concrete evidence before forming conclusions and separates external fact-finding from workspace context. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms workspace readiness. - **Phase 1: Initial Assessment & Triage** — Reads error logs, crash reports, or issue descriptions, forms initial hypotheses, and creates `docs/investigations/-.md`. - **Phase 1.5: External Fact-Gathering** _(conditional)_ — Dispatches parallel `explore` agents for facts outside the workspace (git history/blame archaeology, web searches, external documentation), recording results in `## Background / Prior Research`. - **Phase 2: Broad Context Gathering** — Runs `context_builder` with instructions referencing the investigation report to discover relevant source files and populate context. - **Phase 3: Deep Investigation** — Dispatches a `pair` investigator to trace code paths, test hypotheses, and record concrete findings under `## Investigator Findings`. - **Phase 4: Selection Curation & Oracle Synthesis** — Curates the file selection to include newly surfaced files and line slices, then calls Oracle (`oracle_send` or `ask_oracle`) to synthesize cross-component insights. - **Phase 5: Final Report Synthesis** — Finalizes the report with confirmed root causes, supporting line-level evidence, and proposed remediation steps. --- #### 8. ChatGPT Export (`/rp-oracle-export`) **Builds optimized codebase context and exports a self-contained, ChatGPT-ready prompt file.** ```text /rp-oracle-export ``` - **Arguments:** `problem` (required) — Description of the question, plan, or review to export. - **Core Philosophy:** Extracts the real underlying task, selects the optimal files within token limits, and exports a clean markdown prompt to `prompt-exports/` ready to be copied into ChatGPT or other external models for a second opinion. **Workflow Steps:** - **Step 0: Workspace Verification** — Confirms repository context. - **Step 1: Determine Intent & Scope** — Classifies the prompt intent into **Question** (specific bounded query), **Plan** (architectural/design problem without diffs), or **Review** (git diff / branch comparison). - **Step 2: Choose Context Path** — - _Fast Path_: Used only when the scope is already tiny, concrete, and file-local. - _Deep Path (Default)_: Uses `context_builder` with `response_type: "clarify"` to curate optimal full files, slices, and codemaps within token budgets. - **Step 3: Review and Export** — Verifies prompt text and token counts with `workspace_context`, then exports a unique markdown prompt file under `prompt-exports/-export.md`. --- #### Utility & Helper Commands ##### Tools Reminder (`/rp-reminder`) A token-efficient prompt (available as `/rp-reminder` or `/rp-reminder-cli`) that reminds agents to use RepoPrompt's specialized MCP tools (`file_search`, `read_file`, `get_file_tree`, `get_code_structure`, `apply_edits`, `file_actions`, `git`, `manage_selection`, `workspace_context`, `context_builder`, `oracle_send`, `ask_user`, `agent_run`, `agent_manage`) instead of generic shell commands like `grep`, `cat`, `sed`, `find`, or `ls`. | Task | Recommended MCP Tool | Avoid Shell Alternatives | | ---------------------------- | -------------------- | -------------------------------- | | Search paths/content | `file_search` | `grep`, `find`, `Glob` | | Read file (whole or sliced) | `read_file` | `cat`, `head`, `tail` | | Project directory tree | `get_file_tree` | `tree`, `ls -R` | | Code signatures & structure | `get_code_structure` | Reading entire source files | | Edit file contents | `apply_edits` | `sed`, custom rewrite scripts | | Create / move / delete files | `file_actions` | `touch`, `mv`, `rm` | | Git status / diff / blame | `git` | Shelling out to raw git commands | --- ### Context Builder Response Types The workflow commands above leverage the `context_builder` MCP tool. You can also invoke Context Builder directly with different response types: - **`clarify`** _(default)_ — Builds curated file context only. Returns selected files, slices, and codemaps without running follow-up analysis. - **`plan`** — Generates a comprehensive architectural and implementation plan grounded in actual codebase patterns. - **`question`** — Answers complex architectural or code questions using deep contextual understanding. - **`review`** — Generates an in-depth code review evaluated against Git diffs and surrounding system architecture. Use `export_response: true` on any analysis response type (`plan`, `question`, `review`) to write the generated response to a shareable markdown file. The returned `oracle_export_path` and `oracle_export_instruction` allow seamless hand-off to child agents or persistent project records. ### Git Integration The `git` tool provides safe, token-efficient git operations for MCP agents: `status`, `diff`, `log`, `show`, `blame`, and snapshot diff artifacts. It also natively supports Jujutsu (`jj`) repositories. For complete tool arguments, comparison specs, and worktree options, see the [Git reference](https://repoprompt.com/docs/mcp-server/mcp-tools/#git). ### Custom Skills Beyond the supplied workflow commands, you can write your own workflow instructions and package them as skills for a compatible external host to discover. The instructions can describe specialized testing, migrations, or project-specific procedures; the host determines how they are invoked and followed. Learn how to create and install custom skills in [Skills & Slash Commands](https://repoprompt.com/docs/agent-mode/skills/). :::tip[Getting Started] After setting up the MCP connection, open your client’s skill or slash-command picker to discover the installed commands. For more detail on each workflow and the Context Builder pipeline, see [Agent Mode Workflow Commands](https://repoprompt.com/docs/agent-mode/workflow-templates/). ::: --- ## Best Practices An overseer works best when it has a clear goal, a small set of independently useful tasks, and explicit rules for bringing the results together. Give it enough authority to coordinate the work you intend, and keep the review points visible in the conversation. ### Divide work by deliverable Choose lanes with distinct outcomes: an investigation report, an implementation in a specified checkout, a focused regression review, or documentation of a completed change. Give each a completion criterion and identify dependencies. Ask the overseer to summarize who owns each task before overlapping implementation starts. Use [execution locations](https://repoprompt.com/docs/agent-mode/execution-location/) and worktrees to separate simultaneous edits. Conversation isolation does not prevent two agents from changing the same file in a shared checkout. Tell the overseer how results should be compared or integrated and who should resolve conflicting changes. Start with a small group. More lanes add usage, coordination work, and possible conflicting assumptions. Use a short read-only exploration task when you need one narrow answer rather than a durable session. ### Choose how updates wake the overseer Status updates are attached to the overseer's next turn even when routine automatic waking is disabled. The wake controls decide whether updates can also start additional model turns: Overseer wake controls and their effects Control | Use and limitation Auto-wake on all updates | Enables routine follow-up turns for selected linked sessions. It is on by default and saved for the overseer session. Lane Auto-wake | Selects an individual lane for routine wake behavior. Snooze status Auto-wake… | Temporarily defers that lane's routine status wakes. Routine wake-ups no more often than | Sets a minimum interval across routine oversight wakes. Deferred updates remain queued. Wake when idle for | Adds a wake after the chosen idle interval while overseeing another session, even without an update. Each wake uses a model turn. Wake now | Processes pending updates immediately when the overseer is able to accept a turn. An explicit attention request from an exactly linked session can bypass the routine master switch, lane selection, snooze, and routine interval without changing those settings. **Wake now** also bypasses the routine interval. Use **Unlink** to end the relationship when you need to prevent further purposeful attention through that link. Automatic turns can generate more updates, so even one relationship can sustain repeated activity. Sessions that oversee each other can keep waking one another. Prefer a clear coordination direction and enable periodic waking only for work that needs it. A busy overseer finishes its current and already-accepted work before taking eligible update-driven follow-up work. #### Keep routine check-ins quiet For supported Codex and Claude Code sessions, RepoPrompt can recognize a routine automatic check-in that has nothing actionable to report and suppress its routine transcript noise. This reduces repeated coordination chatter; it does not eliminate the model turn or its usage. A meaningful result, failure, or request for input still deserves review. Quiet display does not erase the saved conversation or exported history, and it is separate from turning Auto-wake off. Use the wake interval and snooze controls above to reduce unnecessary turns. Give the overseer an explicit instruction such as “Notify me when a result is ready, work fails, or you need a decision; keep unchanged routine checks quiet.” ### Review results and approvals An **Idle** row means the session is not working; it does not prove the task met its acceptance criteria. Ask the overseer to identify evidence, remaining risks, and unfinished work. Open the lane's transcript and inspect key diffs or tool results before accepting a consequential conclusion. Oversight can handle eligible one-time approvals, but session-wide permission grants, secret inputs, hook trust, and merge reviews remain with you. The optional **Auto-approve read-only commands** switch is off by default and applies only to a restricted set of simple commands on managed lanes. It does not approve arbitrary shell work, setup scripts, or all Git operations. ### Finish and recover deliberately For scoped administration, preview bulk changes before applying them. RepoPrompt can present a batch confirmation card with the affected sessions; retirement and worktree release require that confirmation unless covered by the full-access setting. Reversible organization operations can return an undo action. Under ordinary scopes, session deletion remains a user action. **Overseer full access** allows session deletion without confirmation cards, subject to the remaining target and run-state checks; verify the intended sessions before requesting deletion. Physically removing worktrees remains a separate user action. When delegated coordination is finished, release the scope as well as ending unneeded links. Releasing a parent scope also revokes its nested scopes. A permission refusal can mean an expired grant, missing capability, or a reached limit; inspect that reason before requesting broader access. Retire completed lanes only after their work is inactive and reviewed. Retirement stashes the session without deleting it or integrating its changes. Unlink independently created sessions when their coordination purpose ends. If a row is unavailable or a saving warning appears, inspect the session and resolve the displayed condition. Use **Retry saving** where offered. Avoid asking the overseer to allocate another lane just because a previous response was incomplete; first determine whether the earlier session exists and has begun work. For setup and relationship direction, revisit [Overview](https://repoprompt.com/docs/overseer/), [Lanes](https://repoprompt.com/docs/overseer/lanes/), and [Linking Sessions](https://repoprompt.com/docs/overseer/linking-sessions/). --- ## Lanes A **lane** is a separate top-level Agent session created by an overseer for a defined piece of work. It has its own conversation, provider/model selection, and task state, and is linked to its creator so the overseer can coordinate it. Use lanes for work you want to inspect and continue as ordinary sessions rather than treating every task as a short-lived probe. ### Create lanes from the coordinating session Start an eligible session, open its oversight control, and choose **Enable overseer mode**. Then ask the agent to create lanes with names and clear responsibilities. You can describe the roles in ordinary language: > Create an implementation lane for the cancellation fix and a review lane to inspect it independently. Give each a clear completion criterion. Confirm their execution locations before editing shared files. The agent can choose an available role mapping—**Explore**, **Engineer**, **Pair**, or **Design**—or an explicit supported model. Role mappings come from [Agent Models](https://repoprompt.com/docs/settings/agent-models/); they are model choices for lane creation, not blanket approval to use every tool. A lane can be created without starting work, or with an initial task and optional workflow. A session with an eligible existing oversight relationship can already create lanes through that relationship. The separate **Enable overseer mode** activation is useful when starting without links; you do not need to unlink working relationships just to create lanes. The current lane limit is **12 per overseer**. Availability, workspace admission, and applicable delegation limits can reduce what can be created. A refusal does not mean another lane should be allocated blindly; inspect existing sessions and any saving warning first. ### Give every lane an independent job Define its deliverable, scope, and stopping point. “Investigate why cancellation leaves a stale row and report evidence” is a useful investigation. “Fix everything” makes ownership and completion harder to assess. Specify the intended workspace when work spans projects. Lane creation needs an unambiguous open workspace destination. A created lane is a top-level session, so do not assume it inherits the safety profile of an MCP sub-agent or a separate checkout. Inspect its permissions and [execution location](https://repoprompt.com/docs/agent-mode/execution-location/). Use worktrees for concurrent edits that may overlap. A lane does not inherit its creator's authority. A coordinator with the required delegation scope can explicitly grant a narrower scope to a member session for nested coordination. Keep the overall plan in the parent conversation, define the nested coordinator's task, and review the [delegation boundaries](https://repoprompt.com/docs/overseer/#nested-delegation). ### Follow progress and continue work The oversight popover shows the lane's state, identity, location information, and recent activity. Open it directly to inspect messages or tool cards. The overseer can read progress, send more instructions, handle eligible pending interactions, and stop a run within the granted relationship. For an idle managed lane, the overseer can adjust an available model within the same provider for the next turn. This does not change the model in the middle of an active task or switch it silently to another provider. Ask for a fresh session when a different execution environment is required. ### Retire a finished lane Ask the overseer to retire a lane it created after its work and relevant descendants are inactive. Retirement unlinks and stashes the lane; it does not delete the conversation or merge its changes. Inspect the result, record remaining follow-ups, and integrate the repository work separately. **Unlink** can end oversight without retiring the session. **Delete** in session management is a separate, permanent action. If lane creation or retirement reports an incomplete save, use the existing session identity and resolve the saving condition before asking for a replacement. See [Linking Sessions](https://repoprompt.com/docs/overseer/linking-sessions/) to coordinate conversations that were created independently of the overseer. --- ## Linking Sessions Link existing sessions when work is already underway and you want one agent to coordinate it. The direction matters: an **overseer** receives authority over an **overseen session**. Linking A to oversee B does not automatically make B an overseer of A. ### Link from the composer 1. Open the intended overseer's session and its oversight popover. Start a first message if the session is still an empty composer. 2. In the target session's sidebar controls, copy its **Session ID**. 3. Return to the overseer and enter that ID under **Oversee a session**, or choose **Paste from Clipboard**. 4. Inspect the target preview. Choose **Retry** if the session has just loaded and availability needs refreshing. 5. Choose **Oversee session**, read the confirmation naming both conversations, and choose **Allow oversight** only for the intended relationship. Oversight popover with Session ID, Paste from Clipboard, Retry, and Oversee session The sidebar also offers **Oversee** and **Link overseer** entry points. **Oversee** chooses which session the current row will oversee; **Link overseer** chooses who will oversee that row. Session-ID sheets support selecting a session that is not convenient to find in the visible list. ### Understand the confirmation The confirmation explains that the overseer can read the target's status and conversation, send instructions, steer or stop its run, answer questions and eligible one-time approval requests, compact context, and receive updates. This is active coordination, so link conversations whose work you intend the overseer to direct. **Don't ask again** suppresses repeated confirmation dialogs after an accepted choice. It does not expand the relationship to every session or bypass runtime eligibility. Session-wide approvals, hook trust, merge reviews, and secret inputs remain your responsibility. Not every session is eligible. An unavailable candidate can be loading, closing, controlled by another agent, or otherwise unsuitable for the requested role. Follow the displayed reason. **Sessions changed. Please choose again.** means the selection is stale; choose the target again rather than assuming the old preview is still valid. ### Read relationship marks The sidebar uses a filled eye for an overseer, an outline eye for an overseen session, and a combined mark when a session has both roles. Tooltips name the relationships: **Overseeing**, **Overseen by**, and, for lanes, **Created by**. The popover also lists outbound and inbound relationships so you can inspect who controls whom. Saved relationship information can be restored when the relevant sessions are available, but the live dashboard determines what can currently be used. Check **Unavailable** rows, saving warnings, and recovery notices after reopening workspaces or restarting the app. ### Unlink and recover Use **Unlink** from either end to revoke the relationship. Unlinking does not delete the conversation, roll back file changes, or automatically cancel a turn already in progress. Inspect any running task separately if it should stop. The popover can offer a short-lived **Undo** for the most recent unlink. Read its result: the original relationship must still be eligible. Closing the popover or another unlink can end that recovery opportunity. Turning off routine Auto-wake does not revoke access or block every explicit attention request. Unlink when the purpose of the relationship has ended. See [Best Practices](https://repoprompt.com/docs/overseer/best-practices/) for wake behavior and coordination limits. --- ## Overseer Mode Overseer Mode lets one Agent session coordinate other sessions. The overseer can follow their progress, read their conversations, give follow-up instructions, and help resolve questions within the authority you granted. You can keep working from one coordinating conversation while specialist sessions handle separate parts of a larger task. ### Why use this if you are new to RepoPrompt? An ordinary RepoPrompt session works with a coding agent on a task. When a project grows beyond one focused conversation, you may want an investigation in one session, implementation in another, and an independent review in a third. Without coordination, you have to carry status and instructions between them yourself. An overseer provides a coordinating conversation for that work. You describe the goal and boundaries, let it assign or follow separate tasks, then review its conclusions. You can still open every session and inspect its messages and tool activity. Start with one or two clearly separated tasks; you do not need a large group of agents to benefit. If you are learning the composer first, see [Agent Mode](https://repoprompt.com/docs/agent-mode/overview/). In particular, choose [execution locations](https://repoprompt.com/docs/agent-mode/execution-location/) deliberately: separate conversations can still share the same checkout. ### Open the oversight control The composer toolbar includes an oversight control between **Workflow** and **Interview**. Open it to enable Overseer mode, add an existing session, inspect relationships in both directions, and manage wake behavior. The captured control uses a branching symbol; newer interfaces identify oversight roles with eye marks and counts. Oversight popover with session-scoped activation and controls for adding an existing session by ID Use a loaded, user-owned top-level Agent session. If the composer has never sent a message, send an initial coordinating request first. For example: “Help coordinate an implementation and independent review. First establish the tasks and checkouts with me.” An unavailable control explains whether the session is still loading or is ineligible. ### Choose how to begin **Create managed lanes.** Choose **Enable overseer mode**, then ask the coordinating agent to create named lanes for defined tasks. A lane is a separate top-level Agent session created for this overseer and linked to it. Activation alone grants no access to your existing conversations. See [Lanes](https://repoprompt.com/docs/overseer/lanes/). **Link existing sessions.** Choose a session through the sidebar oversight menus or paste its session ID into **Oversee a session**. Review the confirmation naming the overseer and target. This is useful when several conversations already contain work you want coordinated. See [Linking Sessions](https://repoprompt.com/docs/overseer/linking-sessions/). The explicit **Enable overseer mode** activation lasts for that session until its binding or ownership changes or the app restarts. Linking and saved relationship recovery have their own lifecycle; check the current popover rather than assuming an earlier activation grants access after a restart. ### What the overseer can do For a properly linked target, the confirmation describes access to status and conversation, instructions, steering, stopping the current run, applicable questions and one-time approvals, context compaction, and updates that can wake the overseer. Session-wide approvals, hook trust, merge reviews, and secret inputs stay with you. An overseer can coordinate work across RepoPrompt windows, but it does not combine every session into a single conversation or automatically merge their file changes. Review results and integration decisions in the target checkout. ### Organize sessions with delegated permissions An overseer can also administer sessions through a **delegation scope**. A scope defines the sessions it covers, permitted actions, and limits. It is separate from an oversight link, which carries conversation updates and coordination between a pair of sessions. Ask for the outcome and boundaries in ordinary language, for example: > Organize this workspace's completed investigations into groups, pin the active implementation, and archive finished sessions. Leave running work alone. When the request needs authority the overseer does not already hold, RepoPrompt presents a scope approval card. Review its coverage, capabilities, and limits; you can narrow the proposed grant. Existing standing consent can cover a later request. The optional **Overseer full access** setting grants broader authority and can avoid these scope cards; enabling Overseer mode alone does not grant that access. | Capability | What it permits within the scope | | --- | --- | | Observe | List, search, and inspect sessions and progress. | | Organize | Rename, pin, reorder, group, archive, and unarchive sessions. | | Control | Send or steer work, answer eligible prompts, stop runs, compact context, and change available model or effort choices. | | Restructure | Manage links and session organization, release sessions, and retire eligible work. | | Spawn | Create or fork sessions and delegate to nested overseers. | | Worktree | Create and manage session worktree bindings, prepare merge previews, and request a merge review. | Scopes can cover one exact session, a session tree, a workspace, or all sessions. An ordinary all-sessions scope supports observation, organization, and restructuring; it does not by itself grant control over every running task. Session deletion remains a user action under ordinary scopes; **Overseer full access** allows session deletion without confirmation cards, subject to the remaining target and run-state checks. Removing or pruning worktrees, changing provider permission modes, approving MCP clients, and changing app settings remain user actions. Oversight can manage eligible approvals within a task without granting permission to change those underlying controls. #### Nested delegation An overseer with the required scope can give a member session a narrower scope to coordinate part of the work. The nested scope cannot expand its parent's capabilities, membership, or limits. Session, depth, and worktree limits apply across the delegated tree; a nested overseer does not receive a fresh unrestricted budget. Releasing a scope revokes its nested scopes too. Moving a session in the sidebar or linking it to another session does not grant new scope membership. Use explicit tasks and review the scope status when a nested coordinator cannot perform an operation. #### Worktrees on behalf of linked agents With the required authority, ask the overseer to create or bind a worktree for a target session, inspect its worktrees, or prepare integration. RepoPrompt resolves the repository from the **target session**; when it has several worktree bindings, specify which repository or worktree you mean. A bind can be deferred until the target reaches an idle boundary. Releasing a worktree unbinds it and marks it for user cleanup; it does not delete the checkout. Merge application still uses the target session's user review. See [Worktrees](https://repoprompt.com/docs/worktrees/) for setup and integration. ### Keep coordination visible The dashboard distinguishes **Idle**, **Running**, **Waiting for input**, and **Unavailable**. Open a session to inspect its actual result; an idle state alone does not prove its goal is complete. Pending updates and **New** indicators help you spot changes since the overseer last handled them. Automatic wake controls can start additional model turns, consume usage, and produce further updates. Configure them around the task's needs, and use **Unlink** to end a relationship when coordination is finished. [Best Practices](https://repoprompt.com/docs/overseer/best-practices/) explains work boundaries, wake settings, result review, and recovery. --- ## Getting Started Use RepoPrompt to give a coding agent the context it needs, plan a focused change, and review the result. This four-step guide helps you complete your first task. For more explanation and optional techniques, continue with [Going Deeper](https://repoprompt.com/docs/overview/going-deeper/). ### Before Step 1: Connect the coding runtime and Oracle Open **Settings → Agent Mode → CLI Providers** and connect the coding runtime you want to use. Complete its sign-in and use **Test Connection** to check it. [Providers & Models](https://repoprompt.com/docs/providers/overview/) explains the available connections. In **Settings → Agent Mode → Agent Models**, choose an available **Context Builder Agent** to find relevant files and an **Oracle** to help analyze them. The [Setup Wizard](https://repoprompt.com/docs/mcp-server/setup-wizard/) can help with these choices. ### Step 1: Describe the task Choose **File → New Workspace Window** to create a workspace for your project. Enter a **Workspace name**, choose **Add Folders** to select your project folder, then choose **Create Workspace**. In a new Agent Mode session, choose **Work locally → Workspace checkout**, then select the **Plan & Build** workflow. Write what you want changed, any limits, and how you will know it works. You do not need to select every relevant file yourself. For example: “Fix the sign-in error so an expired session returns me to the login screen. Keep the existing design and check that signing in again works. Show me the plan and wait for my approval before editing.” ### Step 2: Prepare context and a plan Send the message. Let the agent investigate the project, gather relevant code with Context Builder, and prepare a plan with Oracle. Answer any questions and review the proposed approach. If something is missing or outside your request, say so before implementation continues. You do not need to run discovery and planning separately or repeat the original request. ### Step 3: Implement and guide When the plan is ready, tell the agent to proceed. Follow its progress in the conversation and respond to questions or approval requests after reading what they authorize. If the work heads in the wrong direction, send a correction or stop the run. ### Step 4: Verify and finish Ask the agent to review the changes against your request and run the project's appropriate checks. Inspect the diff and try the changed behavior yourself. If a check fails or the result is incomplete, ask for a targeted fix and check again. Once you are satisfied, ask the agent to commit the change if you want a Git checkpoint. If you used a worktree, [review and merge its changes](https://repoprompt.com/docs/worktrees/review-and-merge/) into your intended branch. A completed agent turn alone does not mean the work is verified or merged. Read [Going Deeper](https://repoprompt.com/docs/overview/going-deeper/) for a multi-step walkthrough with more options and practices behind these four steps, or [Agent Mode Overview](https://repoprompt.com/docs/agent-mode/overview/) to find your way around the interface. --- ## Going Deeper [Getting Started](https://repoprompt.com/docs/overview/getting-started/) gives you a four-step path through your first task. This guide expands that path into ten steps for work that needs more investigation, more coordination, or more careful review. Use the parts that help your task; a small fix does not need several agents, a formal plan document, and multiple Oracle consultations. Complete the [connection setup in Getting Started](https://repoprompt.com/docs/overview/getting-started/#before-step-1-connect-the-coding-runtime-and-oracle) first. For the location of a screen control, use [Agent Mode Overview](https://repoprompt.com/docs/agent-mode/overview/). | Getting Started | Going Deeper | | --- | --- | | [Step 1: Describe the task](https://repoprompt.com/docs/overview/getting-started/#step-1-describe-the-task) | Steps 1–4: establish the workspace, choose access, write the brief, and select your approach. | | [Step 2: Prepare context and a plan](https://repoprompt.com/docs/overview/getting-started/#step-2-prepare-context-and-a-plan) | Steps 5–6: curate the evidence and review the plan. | | [Step 3: Implement and guide](https://repoprompt.com/docs/overview/getting-started/#step-3-implement-and-guide) | Steps 7–8: assign work, follow progress, and correct direction. | | [Step 4: Verify and finish](https://repoprompt.com/docs/overview/getting-started/#step-4-verify-and-finish) | Steps 9–10: verify the combined result, integrate it, and preserve a useful handoff. | ### Step 1: Establish the workspace and starting point Before describing a change, make sure the agent will investigate the right project. Choose **File → New Workspace Window**, enter a **Workspace name**, use **Add Folders** to select your project folder, then choose **Create Workspace**. Inspect the loaded workspace. If several repository roots are available, identify which one owns the task and which others are references. A phrase such as “the web app” can be ambiguous when the workspace contains several applications. Ask the agent to establish a baseline: the active repository and branch, existing local edits, relevant project instructions, and the checks normally used for this part of the code. This makes it easier to distinguish the task's changes from work that was already present. Do not ask it to discard, reset, or commit unrelated edits just to obtain a clean starting point. For a bug, supply a reproducible observation before asking for a fix. Include what you did, what happened, and what you expected. For a feature, identify the user-facing outcome and any existing behavior that must remain. If the agent cannot reproduce a problem, have it state what it could verify rather than treating an explanation as a confirmed cause. :::tip[Try a short orientation request] For an unfamiliar repository, start with: “Identify the code that owns this behavior, read the relevant project instructions, and report existing local changes. Do not edit yet.” Review the answer, then give the implementation task in the same session. ::: :::tip[Connect an external agent to the same workspace] An external MCP client can use `bind_context` with `op="list"` to discover contexts, then bind using the intended workspace roots or returned context ID. Check its binding before asking it to work; the RepoPrompt tab you can see is not proof of what that connection targets. See [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/#context-binding). ::: Continue when you and the agent agree on the project, the starting state, and the behavior being changed. ### Step 2: Choose the checkout, tools, and permissions Open **Work locally** before the first message and decide where the changes belong. **Workspace checkout** uses the checkout already open. **New worktree** prepares a separate Git checkout for the task. **Existing worktrees** lets you continue work in an available checkout. Inspect the location indicator and any creation error after sending; selecting a worktree is not evidence that creation succeeded. Use the workspace checkout for a focused task when its changes can safely coexist with your current work. A separate worktree is useful for an experiment, an alternative implementation, or concurrent agents that might edit overlapping files. Separate conversations alone do not isolate edits. For a workspace with several repositories, identify the relevant repository rather than assuming one worktree covers all of them. Check **Tools** and **Permissions** for the selected provider. Available controls differ by integration, and MCP-launched sub-agents have a separate policy. Give the agent the capabilities the task requires; a model choice or workflow template does not grant tool access. Read approval requests in the context of the actual action and checkout. :::tip[Use a worktree for an experiment] Try a separate worktree when you want to compare two approaches without mixing their edits. Give each session a clear purpose and review the resulting diffs before choosing what to integrate. See [Execution Location](https://repoprompt.com/docs/agent-mode/execution-location/) and [Create and Use a Worktree](https://repoprompt.com/docs/worktrees/create-and-use/). ::: :::tip[Investigate before granting write access] For diagnosis or code review, consider the provider's read-only options where available. A worktree isolates repository files but does not isolate credentials, databases, or external services. Check [Tools](https://repoprompt.com/docs/agent-mode/tools/) and [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/) for the actual controls and their limits. ::: Avoid changing an established session's execution location casually. It restarts the provider context and can require stopping an active run. Finish or stop the current work deliberately, then review the location change before continuing. ### Step 3: Write a brief you can verify This is the request-writing part of [Getting Started, Step 1](https://repoprompt.com/docs/overview/getting-started/#step-1-describe-the-task). Describe the result rather than trying to predict every implementation detail. Give known files, symbols, screenshots, or error messages as starting points, and distinguish confirmed facts from suspected causes. A useful brief covers four things: the observed or desired behavior, the scope, the constraints, and the evidence that will count as success. “Make login better” leaves all four open. “Return an expired session to sign-in, preserve the destination, and prove that signing in resumes navigation” gives the agent something specific to investigate and verify. For example: ```text When a session expires, opening a protected page leaves a blank screen. Return the user to sign-in and preserve the requested destination. Keep the existing page design and support direct links to protected pages. Investigate the current session and navigation code before choosing a fix. Show me the plan and wait for approval before editing. Verify expiration, successful sign-in, and failed sign-in behavior. Report the checks run and anything you could not verify. ``` The request for a planning pause is explicit. Selecting a planning-oriented workflow alone does not guarantee a human checkpoint. Likewise, a list of preferred files does not enforce a filesystem boundary; use the relevant permission controls as well as clear task instructions. :::tip[Add one concrete example] A short reproduction, an input/output example, or a screenshot often resolves ambiguity better than another paragraph of adjectives. Explain what the example demonstrates and which details must be preserved. Attachments are separate from selected repository context; see [Image Support](https://repoprompt.com/docs/agent-mode/image-support/). ::: :::tip[Separate requirements from suggestions] Write “The public API must stay compatible” for a requirement and “The cache may be involved; please investigate” for a hypothesis. This lets the agent examine alternatives without accidentally treating your first guess as the required solution. ::: ### Step 4: Choose the workflow and optional assistance Choose a **What are we building?** card or use the **Workflow** selector above the editor. Match the method to the task. **Plan & Build** combines research and implementation; **Deep Plan** produces a plan without implementation; **Investigate** focuses on diagnosis; **Review** examines changes; **Orchestrate** coordinates work across agents. The [Workflow Templates guide](https://repoprompt.com/docs/agent-mode/workflow-templates/) explains the full catalog. The workflow wraps the message you submit. Its selection clears after submission, so choose it again when a later message needs that procedure. A normal follow-up can simply refer to the current task without restarting its entire workflow. Choose the execution model and effort from the options offered by your connected provider. Oracle and Context Builder have separate model selections. Use [Providers & Models](https://repoprompt.com/docs/providers/models/) to understand those roles and availability rather than copying a model name from a screenshot. :::tip[Try Re-prompt on a rough draft] [Re-prompt](https://repoprompt.com/docs/agent-mode/re-prompter/) can turn notes into a clearer brief before the execution agent receives them. In review mode, inspect the rewrite for changed constraints or invented requirements before sending. It does not inspect the contents of your attachments, so describe their purpose in the message. ::: :::tip[Use Interview when a decision is still open] Turn on [Interviewer](https://repoprompt.com/docs/agent-mode/interviewer/) before the first task if the agent should ask a few questions about scope or tradeoffs. Re-prompt helps prepare the draft; Interview asks the execution agent to clarify it after submission. You do not need both for a request that is already clear. ::: :::tip[Try automatic decisions separately] [Agent Decisions](https://repoprompt.com/docs/agent-mode/model-router/) can route eligible new tasks, while [Auto Effort](https://repoprompt.com/docs/agent-mode/auto-effort/) adjusts effort for eligible turns on an explicitly selected model. Try one feature at a time so you can judge its effect on your work. Review the chosen service's setup and data-sharing details first; automatic selection is not a guarantee of lower cost or a better result. ::: ### Step 5: Discover and curate the relevant context This expands the discovery part of [Getting Started, Step 2](https://repoprompt.com/docs/overview/getting-started/#step-2-prepare-context-and-a-plan). Give Context Builder a task to investigate, not merely a request to gather many files. Useful context explains the behavior, the surrounding contracts, and the checks that protect them. An agent-driven workflow can call Context Builder for you. To inspect or run it yourself, open the context drawer and choose **Context Builder**. Review the discovery model, enter the **Task Description**, inspect the **Budget**, and choose **Run**. Use the **Selections** tab to inspect the resulting files and Code Maps. The **Prompt** tab holds receiving-model instructions, which are distinct from the discovery task. Context Builder uses repository search and code-structure information to build a selection. Different representations serve different purposes: | Representation | Useful when | | --- | --- | | Full file | The implementation, nearby logic, and local conventions matter together. | | Line slice | A particular section of a large file is relevant and its boundaries are understood. | | Code Map | The receiving model needs surrounding types, signatures, and relationships without every implementation body. | Inspect the selection for missing callers, related tests, configuration, and error paths. If a result is incomplete, explain which relationship is missing and why it matters. Adding the entire repository can hide the important material without resolving that gap. :::tip[Ask for the path through the code] Try: “Find the entry point, the session-expiration decision, the navigation result, and the tests covering that path.” A concrete relationship gives discovery a better target than “find everything about authentication.” ::: :::tip[Adjust the budget after inspecting the package] Try a smaller budget when the selection contains much unrelated code. If essential implementation was reduced to signatures or omitted, refine the task or increase the budget. A budget is a selection target, not an output limit or proof that all required evidence fits. See [Context Builder settings](https://repoprompt.com/docs/settings/context-builder/). ::: :::tip[Preserve a carefully written prompt] If you want Context Builder to change the selection while retaining your receiving-model instructions, consider **Prompt Enhancement → Preserve**. **Augment** keeps the instructions and appends context; **Rewrite** allows rewriting. This setting is separate from the composer's Re-prompt feature. ::: ### Step 6: Review an Oracle-backed plan The planning half of [Getting Started, Step 2](https://repoprompt.com/docs/overview/getting-started/#step-2-prepare-context-and-a-plan) turns the evidence into a proposed change. Oracle analyzes the context it receives; the coding agent remains responsible for implementation. Ask the plan to identify the existing behavior, the proposed change, affected components, important edge cases, and how the result will be checked. Discovery and planning can happen in one Context Builder request. For MCP-driven work, `response_type: "plan"` requests the planning follow-up, and `export_response: true` requests an exported response. There is no need to repeat discovery solely to move from those two stages. In the interface, inspect **Analysis follow-up** and the selected response type. See [Context Builder](https://repoprompt.com/docs/agent-mode/context-builder/) for the controls and [the tool reference](https://repoprompt.com/docs/mcp-server/mcp-tools/#context_builder) for MCP arguments. Review the plan against your original brief. Does it explain why the proposed change addresses the observed problem? Does it preserve the required behavior? Are tests tied to the changed paths? Which assumptions still need confirmation? Resolve those questions before authorizing implementation when you requested a pause. For multi-agent work, keep the accepted plan in a shared Markdown document and have workers read it. Use the actual returned export path or an explicitly saved plan rather than assuming a file named `Plan.md` exists. Update the plan when the agreed approach changes so later workers do not implement an obsolete version. :::tip[Use another Oracle for a consequential tradeoff] You can configure additional Oracles in [Agent Models](https://repoprompt.com/docs/settings/agent-models/#oracle-models). Ask for independent analysis of a specific risk, then compare the evidence behind disagreements. More responses are not votes, and grouped consultations consume usage across the participating models. ::: :::tip[Export a focused second-opinion package] The **ChatGPT Export** workflow or [Prepare and Copy Context](https://repoprompt.com/docs/agent-mode/context-composer/) can help you take the question and selected code to another model. Review the package before sharing it, then bring useful conclusions back to the coding session with the assumptions and evidence attached. ::: ### Step 7: Divide the work into clear assignments For a small change, the current agent can implement the whole plan. For a larger task, this step prepares the coordinated version of [Getting Started, Step 3](https://repoprompt.com/docs/overview/getting-started/#step-3-implement-and-guide). Divide work by deliverable and dependency, not simply by the number of agents available. Give each assignment a purpose, the files or components it may change, reference material, dependencies, and a concrete completion condition. Define shared interfaces before two workers implement opposite sides of them. If workers need to modify the same central file, sequence their work or give one worker ownership of that integration point. For example, after agreeing on the session-expiration behavior: ```text Assignment: Add coverage for expired-session navigation. Read: the accepted plan and the existing navigation test helpers. Change: the navigation tests; do not change production behavior. Coordinate: tell the implementation worker if the tests reveal a missing case. Done when: expiration, return destination, and failed sign-in are covered. Report: changed files, checks run, and any unresolved assumptions. ``` Use the configured **Explore**, **Engineer**, **Pair**, and **Design** roles according to the assignment, not as substitutes for its scope. Their model mappings live in [Agent Models](https://repoprompt.com/docs/settings/agent-models/#sub-agent-role-defaults). Inspect execution locations and permissions separately: MCP-launched sub-agents and user-created top-level sessions do not necessarily use the same policy. :::tip[Parallelize discovery before parallelizing edits] Try one read-only investigation of implementation paths and another of relevant tests. Compare their findings before assigning writes. This can reveal shared files or conflicting assumptions while changes are still easy to coordinate. ::: :::tip[Add an overseer when coordination becomes the task] [Overseer](https://repoprompt.com/docs/overseer/) can follow linked sessions, help direct work, and organize results within the authority you grant. Start with a few clear assignments. Review delegation scope when prompted; enabling oversight alone does not grant unrestricted access to existing sessions. ::: Before launching workers, make sure someone owns the combined result, including changes that cross assignment boundaries. ### Step 8: Run the work and steer deliberately Once the approach is accepted, tell the agent to proceed. Follow the conversation and open tool cards when you need to understand a read, command, or edit. Respond to questions and approval requests in their active cards. A message in the composer is useful for direction, but does not replace an answer to a pending interaction. Keep tightly dependent work sequential. For example, establish the expiration decision first, update navigation to use it, then verify the whole sign-in path. Continuing with the same worker can retain useful context; launch a separate worker when the next assignment benefits from an independent investigation or a clearly separate scope. Run independent work concurrently only when its file ownership and dependencies are clear. An orchestrating agent can collect worker session IDs and monitor them together. In MCP-driven coordination, a multi-session `agent_run` wait returns when the first session reaches an interesting state; it does not mean all workers are finished. Handle that result or question, then keep monitoring the remaining sessions. See [agent_run](https://repoprompt.com/docs/mcp-server/mcp-tools/#agent_run) for the request and result format. :::tip[Steer with a precise correction] Try: “Keep the current sign-in form unchanged. Limit the fix to the expired-session redirect and its tests.” State what should continue as well as what should change. For MCP-controlled workers, use `agent_run` steering to direct work and `respond` to answer a pending interaction. ::: :::tip[Reduce repeated status checking] Use the orchestrator's wait operation or an overseer's wake controls instead of repeatedly asking every worker for status. You can also configure [Notifications](https://repoprompt.com/docs/settings/notifications/) for approvals, questions, or completion. Automatic wake-ups can consume model usage; choose them for work that needs active supervision. ::: If the task changes materially, stop and revise the accepted plan and assignments. A late instruction in one worker's chat does not automatically update every other worker. If a run fails or is interrupted, inspect its last tool result, current files, and Git state before retrying; some work may already have been applied. ### Step 9: Review and verify the combined result This is the evidence-gathering part of [Getting Started, Step 4](https://repoprompt.com/docs/overview/getting-started/#step-4-verify-and-finish). An idle session, a successful tool call, or a worker's “done” message is not enough to establish that the requested behavior works. Start with the complete diff against the intended baseline. Look for unrelated changes, missing files, altered public behavior, and mismatches with the accepted plan. In a shared checkout, distinguish the task's edits from changes that belonged to someone else. For parallel work, review interactions between contributions as well as each contribution individually. Run the repository's appropriate checks in the checkout containing the combined result. Ask the agent to report what it actually ran, whether it passed, and what was unavailable. Reproduce the original problem and test the intended replacement behavior where possible. For a UI change, inspect the rendered result and relevant keyboard interactions; a type check alone cannot show whether the screen is usable. :::tip[Give review a defined comparison] The **Review** workflow can inspect uncommitted changes or a specified Git comparison. Tell the reviewer which branch or commits define the task and what risks deserve attention. “Review the expired-session fix for lost destinations and redirect loops” is more useful than an unspecified request to review everything. ::: :::tip[Ask for evidence by requirement] Try: “For each acceptance criterion, point to the implementation and the check that verifies it. Mark anything unverified.” This makes gaps visible without requiring a long transcript of every command. ::: Fix a failed check or incomplete requirement with a bounded follow-up. Repeat the checks affected by that fix and verify the combined state again. Update the plan's completion status from those results, not just from worker activity. ### Step 10: Integrate, record, and close the task Finish the delivery part of [Getting Started, Step 4](https://repoprompt.com/docs/overview/getting-started/#step-4-verify-and-finish) in the checkout that should retain the work. Review what will be committed and keep unrelated edits out. Ask for a useful commit message explaining the resulting behavior and, for a substantial change, the reason behind it. If the task ran in a worktree, a commit there does not put the change into your main workspace. Review and commit the intended source edits, identify the target checkout, and request a merge preview. RepoPrompt's merge flow checks the source and target and presents a review before application. If either checkout changes after preview, request a fresh preview rather than assuming the earlier result still applies. Resolve merge conflicts in the **target checkout** named by the conflict card. After integration, inspect the target's history and run the relevant checks there. Keep the source worktree until you have verified the integrated result. Follow [Review and Merge](https://repoprompt.com/docs/worktrees/review-and-merge/) for the exact controls; committing, merging, pushing, and deploying are separate actions. :::tip[Leave a handoff that supports the next task] Ask for a short summary of the outcome, relevant commits, checks, open questions, and anything deliberately deferred. Use **Handoff** where available to prepare context for another session, then review its destination and contents. It does not guarantee that every detail of a long conversation will fit in the next model's context. ::: :::tip[Keep useful work without keeping it active] Use [Session History](https://repoprompt.com/docs/agent-mode/session-history/) to return to completed conversations. Stash or archive work you may revisit; unlink coordination relationships and release delegated scopes when their purpose ends. Review worktree cleanup separately after integration. Closing a conversation is not proof that its file changes were committed or merged. ::: The task is ready to close when the requested outcome is verified, the intended checkout contains the result, and remaining limitations or follow-up work are explicit. For the next small task, return to the [four-step Getting Started guide](https://repoprompt.com/docs/overview/getting-started/); use this longer path when its extra decisions will help. --- ## How It (Really) Works In [How It Works](https://repoprompt.com/docs/overview/how-it-works/), we introduced the three-stage **Explore → Curate → Handoff** pipeline, and in [Why RepoPrompt](https://repoprompt.com/docs/why-repoprompt/), we outlined the top failure modes of standard coding agents. This page goes under the hood of the RepoPrompt source code to explain *why* standard AI coding workflows break down on real production repositories — and the exact mechanisms RepoPrompt implements to solve those failure modes. Here's our "Secret Sauce" with a deep, deep dive into why senior software engineers are using RepoPrompt. --- ### 1. Reliable, Useful Results ("Context Over Convenience") Context Builder creates a boundary between discovery and analysis. The discovery run searches the repository and builds a selection; the receiving model works from the resulting package. The implementation decisions at that boundary are the token budget, the discovery instructions, and the material included in the handoff. #### The "Agent Orientation" Problem & Effective Context Windows Frontier models advertise massive context windows (200,000 to 1,000,000+ tokens), but empirical research and production benchmarks show a sharp gap between an **advertised context window** and an **effective context window**: - **The 64k–128k Sweet Spot:** As of the fall of 2026, most frontier models reason quite reliably inside the **64,000 to 128,000 token** range for agentic coding. Beyond that threshold, reasoning quality degrades proportionally to context length — a phenomenon known as **context rot**. Providers train LLMs with exceptionally long context windows that help various applications, but coding is not one of them. - **Attention Dilution & "Lost in the Middle":** Transformer attention follows a U-shaped curve. Models attend strongly to tokens at the very beginning and very end of the prompt, while accuracy drops significantly (often by 30% or more) for constraints and code buried in the middle. - **Burning the Budget on Orientation:** When an unguided agent starts a task, its context window is already loaded with harness system prompts, tool JSON schemas, and project rules (`AGENTS.md` / `CLAUDE.md`). It then spends 20 to 40 turns running `grep` and reading unrelated files just to orient itself. By the time the agent finishes **orientation**, its context window is already past the effective reasoning sweet spot — forcing it to design and implement the solution with degraded intelligence. #### How RepoPrompt Solves It in Code RepoPrompt enforces a **Context Over Convenience** architecture: 1. **Strict Token Budgeting (`ContextBuilderSettingsValues.swift`):** Context Builder enforces configurable token targets (`analysisTokenBudget = 120,000` tokens by default when generating a plan, review, or answer; `contextTokenBudget = 160,000` tokens for context-only packaging, adjustable across `40,000...200,000` tokens) and automatically reserves `1,500` tokens for wrapper metadata (`adjustedBudget = max(0, runBehavior.tokenBudget - 1500)`). Most complex problems in large repositories fit cleanly inside ~120k tokens when properly curated. 2. **Non-Opinionated Discovery (`SystemPromptService.discoverPrompt`):** If a discovery agent forms an opinion about _how_ to solve the bug while searching, it will only select files that support its first guess. RepoPrompt's discovery system prompt explicitly instructs the discovery agent to remain factual and non-opinionated: > _"Don't assume a solution: Select context that enables different approaches, not just your imagined solution."_ 3. **100% Reasoning on the First Turn:** By delegating orientation to the Discovery Agent and handing only the curated result to the Oracle or implementation agent, the reasoning model spends 100% of its effective attention budget solving the problem rather than hunting for files. --- ### 2. Advanced Context Engineering Once discovery has selected the relevant files, `PromptPackagingService.swift` determines how to represent them and `PromptAssemblyBuilder.swift` places them alongside diffs and instructions. These are separate decisions: a file can contribute a structural summary, selected lines, or its full contents without changing the ordering of the surrounding prompt sections. #### Multi-Resolution Code Representation Through `PromptPackagingService.generatePartitionedFileBlocks`, RepoPrompt partitions selected workspace files into two structural zones — `` and `` — using three levels of granularity: | Representation | How RepoPrompt Renders It | Token Engineering Purpose | | :------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | | **Directory Tree + Code Maps** (``) | `combinedFileMapContent` merges the ASCII file tree (`+` marks files with Code Maps) with Tree-sitter structural extractions (`CodeMapService`) showing types, method signatures, and `uses`/`used_by` relationships. | Gives the model a bird's-eye architectural map of the subsystem at roughly 5–10% of the token cost of full source files. | | **Auto-Codemap Dependency Graph** (`WorkspaceCodemapSelectionGraph`) | When you or an agent select files in `full` or `slices` mode, `WorkspaceCodemapBindingEngine` automatically attaches Code Maps for referenced dependency files. | Prevents hallucinated function calls or parameter mismatches on neighboring modules without manual selection. | | **Line Slices & Full Files** (``) | `SliceAssemblyBuilder` and `renderSliceFileBlock` extract specific line ranges (with `Lines start-end (description)` headers and `...` separators), while core edit targets are included in full. | Eliminates hundreds of lines of irrelevant boilerplate from large files while preserving exact line numbers for `apply_edits`. | #### Instruction Sandwiching (`PromptAssemblyBuilder.swift`) To counter the U-shaped **"Lost in the Middle"** attention curve across 60k–160k token prompts, `PromptAssemblyBuilder` orders sections deterministically: 1. **File Tree & Code Maps** (`.fileMap`) 2. **File Contents & Slices** (`.fileContents`) 3. **Git Diffs** (`.gitDiff`) 4. **Meta Prompts** (`.metaPrompts`) 5. **User Instructions** (`.userInstructions`) When **Duplicate User Instructions at Top** (`prompt_packaging.duplicate_user_instructions_at_top`) is enabled, `PromptAssemblyBuilder.build()` emits `` at the **very beginning** of the assembled payload _and_ again at the **very end**. Even when 100,000 tokens of source code sit in the middle, both peaks of the transformer's attention curve remain anchored to your exact requirements. #### Structured Prompt Enhancement & Load-Bearing Clarification Before handoff, Context Builder can transform rough prompts via `PromptEnhancementMode` (`SystemPromptService.promptSection`): - **`Rewrite` (`.fullRewrite`, default):** Replaces vague instructions with a structured specification containing ``, ``, ``, ``, and ``, plus a `` tag used to automatically title the Compose tab. - **`Augment` (`.augment`):** Preserves your original wording verbatim and appends a `` block mapping selected files, relationships, patterns, and open ambiguities. - **`Preserve` (`.preserve`):** Modifies only the file selection and leaves the prompt text untouched. Similarly, in the Agent Mode composer, the built-in **Re-prompter** (`AgentRepromptGuidance.swift` and `AgentRepromptStreamParser.swift`) structures rough notes into `Objective`, `Requirements & Constraints`, `Relevant Context`, and `Validation / Done Criteria` without inventing unverified repository facts — and if a critical product decision is missing, it surfaces **at most one load-bearing question** (`<<>>`) before execution begins. --- ### 3. Model Context vs. Tool Context A critical distinction in modern agent engineering is the separation between **Model Context** and **Tool Context**: - **Model Context** is the curated working memory of the problem: system instructions, architectural plans, relevant source files, type signatures, and diffs. - **Tool Context** is the operational residue of tool use: MCP JSON schemas injected into the system prompt (**schema bloat**) and the raw stdout/stderr logs, search hits, and file dumps returned by dozens of tool calls (**response bloat**). When Tool Context and Model Context share the same buffer, every failed search and 500-line file inspection permanently pollutes the model's reasoning space and invalidates prompt caches. #### How RepoPrompt Separates Them 1. **Selection Is the Single Source of Truth for the Oracle:** When an agent consults the Oracle (`ask_oracle` or `oracle_send`), the Oracle **never** receives the coding agent's messy tool-call transcript. It receives _only_ the curated workspace selection (`manage_selection`) and the Oracle conversation history. 2. **Fast-Lane Auto-Selection (`MCPReadFileAutoSelectionCoordinator.swift`):** In Agent Mode, whenever the coding agent calls `read_file` or `file_search`, `MCPReadFileAutoSelectionCoordinator` records a lightweight selection intent (`.full` or `.slices`) on a non-blocking fast lane. The moment an explicit consumer (`ask_oracle`, `workspace_context`, or `manage_selection`) runs, RepoPrompt drains the high-water mark (`drainThroughGeneration`) so the Oracle's Model Context automatically includes every file and slice the agent inspected — without carrying over the agent's intermediate search commands. 3. **Suppressing Redundant Native CLI Tools (`ClaudeCompatibleToolPolicy` & `CLIPathInstaller.swift`):** - The `claude-rpce` wrapper (`CLIPathInstaller.swift`) launches Claude Code with `--strict-mcp-config` and `--disallowedTools Read,Write,Edit,Glob,Grep`, forcing all file navigation and editing through RepoPrompt's token-efficient MCP tools. - Inside integrated Agent Mode (`ClaudeCodeIntegrationConfiguration.swift`), RepoPrompt disallows native `Write`, `Edit`, `Glob`, `Grep`, `Agent`, `Task`, `EnterWorktree`, and related native tools. Native `Read` is retained in Agent Mode **strictly for non-text binary assets** (images, screenshots, PDFs), while all text and source code reads are routed through `RepoPrompt__read_file`. - During Context Builder discovery (`discoverDisallowedTools`), `Bash` and native `Read` are also disallowed so the discovery agent stays strictly inside read-only RepoPrompt MCP primitives. 4. **Preloaded Tools vs. Lazy Tool Loading (`ClaudeAgentToolPreferences.swift`):** By default, RepoPrompt preloads its compact 21-tool catalog (`claudeCodeToolSearchEnabled = false`, setting `ENABLE_TOOL_SEARCH="false"`) so agents do not burn extra turns discovering tools; users who connect many third-party MCP servers can toggle **Lazy Tool Loading** on in Settings to defer schema loading. 5. **Configurable System Prompt Delivery (`ClaudeCodePromptDelivery.swift`):** Because different models and tasks respond differently to system-level vs. user-level framing, Claude Code CLI settings expose **Sys Prompt Packaging** (`Replace System Prompt`, `User Message (Keep Native)` wrapped in ``, or `User Message (No Native)`). --- ### 4. Agents Operating Over Multiple Turns and Longer Time Horizons Single-session coding agents degrade over long time horizons (30+ turns) because errors compound: a slight misunderstanding in turn 5 becomes a broken interface in turn 20 and a failing test suite in turn 35. RepoPrompt enables multi-hour, long-horizon engineering through **delegation-first orchestration** and a **cross-session oversight control plane**. #### Coordinator vs. Worker Separation (`/rp-orchestrate`) In `WorkflowPrompt+Orchestrate.swift` and `docs/architecture/agent-orchestration-guidance.md`, the orchestrator is strictly a **Coordinator**: - **Focused Sub-Agent Work Items:** The orchestrator delegates implementation through `agent_run op="start"`, splitting the plan into coherent tasks with explicit acceptance criteria and dependency order. Delegation follows the workflow's coordinator role, not a fixed line-count or file-count threshold. - **Fresh Context Per Work Item:** Each worker sub-agent starts with a clean context window, reads the exported architectural plan (`Plan.md`), completes its scoped files, and returns a concise summary. When the worker finishes, its 30 turns of implementation tool calls are discarded rather than polluting the orchestrator. - **The Phase Gate Invariant:** Parallel sub-agents are instructed **not** to run full-repository builds or test suites concurrently (which causes build-lock contention and noisy failures). Instead, workers complete their scoped edits, and the orchestrator runs the build and test gate **once at the phase boundary**. - **Anti-Interference Rule:** While a delegated sub-agent is running, the orchestrator is forbidden from calling `steer` to hurry it or editing overlapping files in the same scope. #### Capability-Scoped Control Plane (`AgentModeMCPToolPolicy.swift`) To prevent runaway recursive agent spawning, `AgentModeMCPToolPolicy` enforces strict hierarchy boundaries: - Top-level sessions can spawn sub-agents (`agent_run`) and read-only reconnaissance scouts (`agent_explore`) and monitor them in parallel with `session_ids` **multi-wait**. - Nested sub-agents have `agent_run`, `agent_manage`, `agent_session_link`, `session_admin`, and `become_overseer` withheld by default. - For cross-window and multi-session administration, a session can request promotion via `become_overseer` or a user-approved **Delegation Scope** (`DomainDelegationScopeAuthority` / `session_admin`), where every authority check verifies live consent, generation counters, and provenance-based membership proofs (`DelegationMembershipProjector`) before allowing an overseer to inspect, steer, bind worktrees, or retire sibling sessions. #### Event-Driven Auto-Wake & Snooze (`AgentModeViewModel+OversightAutoWake.swift`) When an overseer monitors long-running target sessions via `agent_session_link`, it does not need to burn tokens polling in a loop. RepoPrompt implements an event-driven **Auto-Wake** subsystem divided across four disjoint state owners: 1. **Link Authority (`DomainAgentSessionLinkAuthority`):** Manages user-granted directional links, leases, and cursors. 2. **Passive Reducer (`AgentSessionLinkPassiveStatusNotices`):** Coalesces target status transitions and non-lossy attention requests. 3. **Claim / Receipt Context (`AgentSessionLinkPromptContext`):** Freezes the exact `` XML batch delivered to the provider. 4. **Wake Coordinator (`AgentModeViewModel+SessionLinkAutoWake`):** Determines whether an idle overseer tab may start an automatic follow-up turn right now. Two subtle concurrency invariants in the source code keep long-horizon oversight reliable: - **Snooze Suppresses Admission, Never Delivery:** While an overseer is actively blocked inside an `agent_session_link(op="wait")` call, RepoPrompt records a snooze for those `(overseer, target)` pairs so the wait return itself delivers the update without triggering a duplicate auto-wake turn. However, any notice _already admitted_ to the queue is never filtered out at drain time — ensuring no child completion or question is ever silently stranded. - **The `.cancelledBeforeDispatch` Tombstone Fence:** If you send a manual chat message to the overseer while an asynchronous auto-wake `Task` is already scheduled, your message synchronously drains the queued oversight updates and attaches them inline. RepoPrompt writes a `.cancelledBeforeDispatch(generation)` tombstone into `pendingDispatchByOverseer` so the already-scheduled background task wakes up, sees the tombstone, and exits cleanly without firing a duplicate turn. --- ### 5. Compaction (and Preventing "Compaction Amnesia") As a multi-turn session approaches its context limit, coding agents use **compaction** — summarizing the conversation history so the session can continue. #### Why Naive Compaction Fails In standard coding agents, compaction triggers automatically when a token buffer hits an arbitrary threshold (often right in the middle of debugging a failing test). Standard summarizers suffer from two well-documented failure modes: 1. **Loss of Side Constraints:** Summarizers focus on _what was done_ and frequently drop negative constraints given earlier (such as _"do not modify the public auth signature"_ or _"keep backwards compatibility with v1"_), causing post-compaction agents to immediately violate project rules. 2. **Loss of File & Architectural Detail:** Compaction strips raw file contents and earlier Oracle design discussions from the transcript, forcing the agent to re-read files or guess at architectural decisions it made 40 turns ago. #### RepoPrompt's Four-Part Compaction Architecture RepoPrompt replaces blind threshold truncation with four coordinated mechanisms implemented under `Sources/RepoPrompt/Features/AgentMode/Runtime/SelfCompact/` and `MCPOracleToolService.swift`: ##### 1. Agent-Initiated Self-Compaction (`self_compact` / `agent_self`) Instead of compacting mid-thought, an Agent Mode session can call `self_compact`: - `op="context"` inspects its own current context load and compaction state. - `op="compact"` schedules native compaction at a clean task boundary and records a structured continuation `note` (capped at **10% of the session's context window** in tokens × 4 UTF-8 bytes/token, or **65,536 bytes**, with a SHA digest integrity check). - Calling `op="compact"` returns `scheduled` immediately (`AgentSelfCompactInstantReturn.swift`) and instructs the agent to finish its current turn cleanly. Compaction runs **only** after the active turn settles with `.completed` (never after `.failed`), supervised by a **300-second monotonic deadline** (`AgentSelfCompactNativeCompletionCoordinator.swift`). ##### 2. Dedicated Continuation-Note Turn (`AgentSelfCompactNoteEnvelope.swift`) Once the underlying provider finishes its native compaction (`/compact` in Claude Code or `thread/compact/start` in Codex), RepoPrompt does not inject the saved note as a system log (which many providers ignore) or a normal user prompt (which the model would misinterpret as a new command from you). Instead, `AgentSelfCompactNoteEnvelope` dispatches a dedicated continuation turn that bypasses workflow wrappers and prompt augmentation: ```xml This is your own continuation note, recorded before this session was compacted. It is not a new instruction from the user. {agent's saved architectural state, side constraints, and next steps} ``` If the session closes before the note turn can be delivered, `AgentSelfCompactParkedPrefix.reparkUnattemptedDedicatedNote` re-parks and persists the note so it is never lost. ##### 3. Post-Compaction Oracle Recovery (`oracle_chat_log`) Because the Oracle conversation lives in RepoPrompt's workspace state outside the coding agent's compacted transcript, `SystemPromptService.agentModePrompt` equips the agent with `oracle_chat_log` (reading 1–50 recent Oracle messages without sending a new turn): > _"After compaction: Call `oracle_chat_log` with `limit:1` to read the Oracle's most recent message, then continue with `ask_oracle` (`new_chat:false`) to pick up where you left off."_ ##### 4. Session Handoff Extraction (`agent_manage op="extract_handoff"`) When a session has completed a major phase and you want to start fresh in a new tab or provider without carrying _any_ compacted residue, `extract_handoff` (`AgentHandoffOutputFile.swift` and `AgentProviderContextBuilder.swift`) exports a structured `` XML package containing curated instructions (up to 20,000 characters), bounded transcript items, and the active file selection (or a token-capped ``). --- ### 6. Variations and Limitations of Large Language Models (LLMs) The workflow separates repository exploration and editing from Oracle consultation. A model suited to iterative tool use may serve a different purpose from one selected to reason over a prepared context package. Compare the capabilities needed by each stage rather than assigning permanent rankings to named model releases. Use the shared [Models reference](https://repoprompt.com/docs/providers/models/) for availability, identifiers, reasoning effort, speed tiers, and choosing models for different tasks. The [provider directory](https://repoprompt.com/docs/providers/overview/) owns connection requirements and official catalog references. #### Role-Based Model Specialization Role labels resolve through the effective Agent Models profile rather than a fixed list of model releases. See [Model roles](https://repoprompt.com/docs/providers/models/#model-roles) for their responsibilities and [Agent Models settings](https://repoprompt.com/docs/settings/agent-models/#sub-agent-role-defaults) for configuring mappings and workspace overrides. Model choice and permission policy remain separate decisions. #### Multi-Oracle Rosters & Reconciliation (`SystemPromptService.multiOracleGuidanceBlock`) Even the strongest single reasoning model has blind spots. In **Settings → Agent Mode → Agent Models**, you can configure **1 Primary Oracle** plus up to **4 Additional Oracles** (`OracleGroupStore`). When an agent calls `ask_oracle` or `oracle_send`, RepoPrompt queries every model in the roster in parallel and returns the primary answer alongside ``. RepoPrompt injects explicit reconciliation rules (`multiOracleGuidanceBlock`) into the calling agent: - Where perspectives **agree**, proceed with higher confidence. - Where perspectives **diverge**, evaluate the trade-offs against the actual codebase rather than blindly following either model. - If a secondary Oracle surfaces a **risk or edge case** the primary model missed, investigate it in the code before proceeding. #### Adaptive Routing, Auto Effort, & Local Usage Balancing Through [Agent Decisions](https://repoprompt.com/docs/settings/agent-decisions/), RepoPrompt can dynamically select the base model and reasoning effort per task (using **Jev by TypeSafe** or **Decisions by OpenAI**, both with a five-second deadline and no automatic retries), while **Usage Balancing** stays 100% local on your Mac to shift eligible new tasks across your connected Claude and Codex subscriptions (`Only near limits`, `Even pace`, or `Use expiring quota first`) so you don't burn through one provider's weekly quota prematurely. --- ### 7. Code Reviews: Diff-Only vs. Codebase-Context Reviews Most AI pull-request reviewers operate in **Diff-Only Mode**: they send your `git diff` patch to an LLM and ask _"Find bugs in this diff."_ #### Why Diff-Only Reviews Fail A raw diff shows _what lines changed_, but hides _how the rest of the repository interacts with those lines_: - **False Negatives (Missed Breakage):** If a commit changes a function's return behavior or deletes a fallback branch, a diff-only reviewer cannot see the five callers in other modules that depended on the old contract. - **False Positives (Hallucinated Bugs):** Diff-only reviewers frequently complain about "missing null checks" or "unvalidated inputs" that are already guaranteed by an upstream caller one hop outside the diff. #### How RepoPrompt Implements Codebase-Context Reviews RepoPrompt's review pipeline (`WorkflowPrompt+Review.swift`, `SystemPromptService.reviewPrompt`, and `GitDiffPrimaryArtifacts.swift`) grounds every code review in the surrounding architecture: 1. **Worktree-Aware Git Inspection (`git` tool):** Supports `status`, `diff`, `log`, `show`, and `blame` across uncommitted changes, staged changes, commit ranges (`back:N`), and merge-base branch comparisons (`main`, `trunk`, `@main:`) with native Git worktree and Jujutsu (`jj`) support. 2. **Materialized Selectable Diff Artifacts (`GitDiffPrimaryArtifacts.swift`):** When `git(op="diff", artifacts=true)` runs (automatically triggered by `context_builder(response_type="review")`), `GitDiffSnapshotStore` writes structured diff artifacts into `_git_data//`: - `MAP.txt` — A summary map of all modified files and line-change counts. - `all.patch` — The combined patch artifact. - `diff/per-file/NNN-.patch` — Individual per-file patches exposed as selectable workspace paths. 3. **Outside-Diff Impact Curation (`reviewDiscoveryGuidanceBlock`):** The discovery agent selects the relevant `.patch` artifacts via `manage_selection` **alongside** the full files, line slices, and Code Maps of the modified files, their upstream callers, downstream callees, and test suites. 4. **Prioritized Contract Evaluation (`SystemPromptService.reviewPrompt`):** The Oracle receives both the exact diff hunks and the surrounding codebase contracts, evaluating **Correctness, Security, API/Contract Breakage, Consistency, and Test Coverage**, and organizing findings into actionable tiers: **Must Fix**, **Should Fix**, **Consider**, and **Positive Notes**. --- ### 8. When RepoPrompt Would Not Be Helpful Context Builder discovery, Oracle consultation, and multi-agent orchestration take time and tokens. Choose a workflow for the work you need, and follow its required stages. A small task does not automatically bypass a selected workflow's rules. Here is when full RepoPrompt workflows or Context Builder pipelines are **not** helpful — and what to do instead: #### 1. Localized, Obvious Edits If the target and change are already clear, an ordinary Agent Mode request can be enough. The agent can inspect the relevant files and make the requested edit without selecting a larger workflow. There is no fixed file-count or line-count threshold for that choice. - **Build:** `/rp-build` requires Context Builder to gather context and produce a plan before implementation. A further Oracle consultation is optional when the plan is clear; the builder stage is not. - **Investigate:** `/rp-investigate` is read-only with respect to source code. It requires Context Builder and produces an investigation report rather than applying a fix. Its conditional shortcuts can reduce follow-up investigation, not turn it into an editing workflow. #### 2. Tasks That Do Not Need Delegation Delegation adds coordination, task briefs, and verification. For work you want one agent to implement directly, use an ordinary request or the Build workflow. - **Orchestrate:** `/rp-orchestrate` plans, decomposes, and delegates implementation to sub-agents. The coordinator monitors and verifies their work. A named file can shorten orientation, and an existing plan can skip plan generation, but neither changes the coordinator into the implementer. #### 3. Routine Turn-by-Turn Agent Exploration (Skip Automatic `context_builder`) If you are already in the middle of an interactive coding session and ask a quick follow-up question about a file you are looking at, launching a full two-stage `context_builder` discovery sub-agent is overkill. - **How RepoPrompt handles this:** Ordinary Agent Mode turns can use direct tools such as `get_file_tree`, `file_search`, `get_code_structure`, and `read_file`. Context Builder is used when explicitly requested or required by the selected workflow. A routine follow-up does not by itself require another full discovery pass. #### 4. Standalone Scripts, LeetCode-Style Puzzles, or Zero-Context Tasks RepoPrompt is an architectural context engine for multi-file repositories. If you are writing a self-contained script from scratch, solving an isolated algorithm puzzle, or drafting prose with no codebase dependencies, there may be no cross-file contracts, call graphs, or Code Maps to curate. A direct model conversation may be sufficient. --- ### Summary Matrix: Problem vs. RepoPrompt Architecture | Failure Mode in Standard Agents | Root Cause | RepoPrompt Architectural Solution | | :---------------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Context Rot & Hallucinations** | Agent burns 40+ turns of its 64k–128k effective context window on `grep` and dead-end file reads. | **Non-opinionated Discovery Agent** curates a 120k-token budgeted selection before the reasoning model starts (`ContextBuilderSettingsValues.swift`). | | **"Lost in the Middle" Forgetting** | Transformer attention drops in the middle of long prompts, losing user constraints. | **Instruction Sandwiching** (`PromptAssemblyBuilder.swift`) duplicates `` at the top and bottom of the packaged prompt, paired with Tree-sitter **Code Maps** and **Line Slices**. | | **MCP & Tool Context Bloat** | Verbose tool schemas and raw stdout logs permanently clutter the model's working memory. | **Model vs. Tool Context Separation**: Oracle sees only `manage_selection`; `MCPReadFileAutoSelectionCoordinator` syncs reads asynchronously; `ClaudeCompatibleToolPolicy` blocks redundant native CLI tools. | | **Multi-Turn Drift on Large Tasks** | A single session accumulates conflicting edits and test noise over dozens of turns. | **Coordinator / Worker Split** (`/rp-orchestrate`), **Phase Gate Invariant**, capability-scoped sub-agents (`AgentModeMCPToolPolicy`), and event-driven **Oversight Auto-Wake**. | | **Compaction Amnesia** | Automatic mid-task truncation drops negative side constraints and architectural context. | **Intentional `self_compact`** at turn boundaries, dedicated `` delivery, `oracle_chat_log` recovery, and `` handoffs. | | **Single-Model Blind Spots** | Forcing think-then-act models to edit mid-thought, or relying on one model for every task. | **Tool-less Oracle** paired with tool-native agents, **4 Agent Roles** (`explore`, `engineer`, `pair`, `design`), **Multi-Oracle Rosters** (up to 5 models in parallel), and local **Usage Balancing**. | | **Diff-Only Review Blindness** | Reviewing a git patch in isolation misses broken upstream callers and downstream contracts. | **Selectable Diff Artifacts** (`_git_data/.../MAP.txt`, `all.patch`, per-file patches) combined with curated caller/callee context in `context_builder(response_type="review")`. | | **Unnecessary Workflow Overhead** | Selecting a planning or delegation workflow when a direct, well-scoped request would suffice. | Use ordinary Agent Mode for direct work. Build requires Context Builder; Investigate remains read-only; Orchestrate delegates implementation. Choose by task needs, not fixed file or line counts. | --- ## How It Works If you are a software engineer using RepoPrompt for the first time, the most important concept to understand is **Context Builder Workflows**. Whether you run agents inside RepoPrompt's **Agent Mode** or trigger slash commands (like `/rp-orchestrate` or `/rp-review`) from an external MCP client, Context Builder is the engine that prevents AI coding agents from getting lost in your repository. --- ### Why Standard Coding Agents Get Confused To understand what RepoPrompt does, imagine onboarding to a new engineering team and being assigned a ticket to update user authentication. If a senior teammate helps you, they do not print out all 54 files in the repository and hand you a 10,000-line stack of paper. Instead, they point you to the 5 or 9 files that actually matter — showing you the specific lines in `auth.ts` and `api.ts` where tokens are validated, and giving you a quick summary of the helper functions in `useAuth.ts`, `Header.tsx`, and `Sidebar.tsx`. When you use a standard AI coding agent *without* RepoPrompt, it has no senior teammate: 1. The agent starts with an empty **context window** (its working memory, measured in **tokens**). 2. To orient itself, it runs shell commands like `grep` and `find` and reads whole files one by one. 3. Most of the files it reads turn out to be dead ends, but **every search result and unrelated file stays in its context window**. 4. Even if a model advertises a 200k+ token window, its *effective* reasoning quality drops sharply once its working memory fills past 64k–128k tokens of noisy tool logs. By the time the agent finds the right code, it has very little "thinking budget" left to write a clean solution. RepoPrompt solves this by separating **finding the right code (Discovery)** from **solving the problem (Analysis & Implementation)**. --- ### The Three-Stage Context Builder Pipeline Whenever a Context Builder workflow runs (via the UI or the `context_builder` MCP tool), RepoPrompt executes a three-stage pipeline behind the scenes: **01 Explore → 02 Curate → 03 Handoff**. #### Stage 01: Explore — Agent Navigates the Codebase First, RepoPrompt launches a fast, specialized **Discovery Agent** whose only job is to map the codebase around your task. - **How it navigates:** Rather than using raw shell `grep` or `cat`, the discovery agent uses RepoPrompt's gitignore-aware repository tools: - `get_file_tree` to inspect the directory hierarchy (where files with available Code Maps are marked with `+`). - `file_search` to search file paths, contents, or both using regular expressions and directory filters. - `get_code_structure` to inspect **Code Maps** — root-local structural summaries showing classes, structs, function signatures, and dependency edges (`uses` and `used_by`). - **Neutral fact-gathering:** In RepoPrompt's architecture, the discovery agent is deliberately instructed to be **non-opinionated**. It does not try to design your feature or guess a fix prematurely; it gathers facts, traces callers and callees, and identifies every candidate file across the project. #### Stage 02: Curate — Select Within a Token Budget Suppose your project or subsystem has **54 files**, and the discovery agent's exploration touches 14 of them. Loading every file in full would waste tokens on boilerplate. In Stage 02, the agent narrows and shapes the selection (`manage_selection`) to fit strictly inside RepoPrompt's configured **Token Budget** (for example, curating **9 of 54 files** within the default **120,000-token Analysis Budget** or **160,000-token Context Budget**): - **Full Content (`mode="full"`):** Selected for the primary files where logic needs to be understood line-by-line or edited directly. - **Line Slices (`mode="slices"`):** Selected when a file is large (say, 1,200 lines) but only one function or component matters. The agent selects exact line ranges (such as `auth.ts` lines `5–89` or `api.ts` lines `22–58`) and omits the rest. - **Code Maps Only (`mode="codemap_only"`):** Selected for supporting files and dependencies. In fact, RepoPrompt includes **Auto-Codemap** behavior: when full files or slices are added, related dependency files automatically receive Code Maps so the reasoning model sees their exact API signatures without paying for their implementation bodies. #### Stage 03: Handoff — Structured Prompt for Analysis Once the selection is curated, RepoPrompt assembles a clean, deterministic context package (`workspace_context`). For example, a curated handoff for an authentication task might look like this: | Selected File | Representation / Line Range | Why It Is Included | | :--- | :--- | :--- | | `auth.ts` | `L5–89` (Slice) | Core authentication token logic being modified | | `api.ts` | `L22–58` (Slice) | API request interceptor that consumes auth state | | `useAuth.ts` | `L1–41` (Full / Slice) | React hook exposing session state to components | | `Header.tsx` | `L12–67` (Slice) | UI component rendering the sign-in/sign-out controls | | `Sidebar.tsx` | `L1–34` (Full / Slice) | Navigation gating based on authenticated user role | Depending on the `response_type` requested by the workflow, RepoPrompt also enhances your prompt (rewriting or augmenting vague terms into exact file and symbol names) and performs the handoff: - **`clarify` (Context-Only Handoff):** Returns the curated selection and clarified prompt directly to your agent (or exports a prompt file) so it can begin working immediately. - **`plan`, `review`, or `question` (Oracle Analysis Handoff):** Passes the structured prompt to the **Oracle** — a high-capability reasoning model (or a configured **Multi-Oracle Roster** evaluating up to 5 models in parallel) — which starts with a fresh context window containing zero search noise and returns an architectural plan, code review, or deep answer. Multi-Oracle rosters include automated reconciliation guidance so agents can weigh differing perspectives. --- ### Core Context Builder Workflows RepoPrompt ships included slash commands that wrap this three-stage pipeline into repeatable engineering workflows. You can run these from the **Workflow** dropdown in Agent Mode or type them as slash commands in any connected MCP client: #### 1. Orchestrate (`/rp-orchestrate`) **When to use it:** Large features, multi-file changes, or cross-cutting tasks that are too big for a single agent session. - Runs Context Builder (`response_type: "plan"`, `export_response: true`) to produce a shared architectural plan file. - Decomposes the plan into up to 5 scoped work items with explicit file boundaries. - Dispatches specialized sub-agents (`pair`, `engineer`, `design`, `explore`) across your connected providers in sequence or in parallel, then verifies every change against the plan and test suite. #### 2. Code Reviews (`/rp-review`) **When to use it:** Before opening a pull request, merging a branch, or committing staged changes. - Surveys your repository state using RepoPrompt's read-only `git` tool (`status`, `log`, `diff` against `uncommitted`, `staged`, or a branch merge-base like `main`). - Calls Context Builder (`response_type: "review"`), which publishes your Git diffs **alongside** curated codebase context (callers, interfaces, and related modules outside the diff). - Because the Oracle sees how the rest of the codebase interacts with your diff, it catches subtle breaking changes, missing error handling, and security bugs that diff-only tools cannot see. #### 3. Refactor Code (`/rp-refactor`) **When to use it:** Cleaning up technical debt, splitting a monolithic module, or eliminating duplicated logic without changing how the app behaves. - **Pass 1 (Analyze):** Scouts the target folder with read-only `explore` agents and runs Context Builder in `review` mode to identify structural opportunities and hidden coupling. - **Pass 2 (Plan & Implement):** Runs Context Builder in `plan` mode to design safe, incremental refactoring steps that preserve existing behavior, then dispatches sub-agents to apply edits (`apply_edits`) and run tests after each step. #### 4. Investigate Issues (`/rp-investigate`) **When to use it:** Debugging a tricky crash, tracing a regression, or understanding how an unfamiliar subsystem works. - Follows a hypothesis-driven workflow that writes an investigation report to `docs/investigations/-.md` without changing source code. - Uses `explore` scouts for git blame archaeology and Context Builder to gather cross-file evidence, then consults the Oracle (`oracle_send` / `ask_oracle`) to test hypotheses until the root cause is proven with exact file and line citations. :::tip[Additional Specialized Workflows] RepoPrompt also includes **Deep Plan** (`/rp-deep-plan` for producing standalone specification docs under `docs/plans/` with an interactive interview and `design` critique), **Optimize** (`/rp-optimize` for metric-driven performance loops with a persistent scoreboard), **Plan & Build** (`/rp-build` for single-session feature implementation), and **ChatGPT Export** (`/rp-oracle-export` for exporting self-contained prompts to `prompt-exports/`). ::: --- ### Summary for New Users | Concept | What It Means in RepoPrompt | | :--- | :--- | | **Discovery Agent** | The fast agent in Stage 01 that searches your repo and selects files without writing code. | | **Code Map** | A token-efficient summary of a file's types and function signatures (`get_code_structure`). | | **Line Slice** | A specific range of lines from a file (`manage_selection mode="slices"`), skipping unrelated lines. | | **Oracle** | The deep reasoning model in Stage 03 that receives the curated context to generate plans, reviews, or answers. | | **Sub-Agent Roles** | Task-specific agent profiles: `pair` (default for complex work), `engineer` (scoped coding), `explore` (read-only scouting), and `design` (architecture/UI specs). | ### Next Steps - Read [How It (Really) Works](https://repoprompt.com/docs/overview/how-it-really-works/) for an under-the-hood architectural deep dive into compaction, Model Context vs. Tool Context, LLM limitations, and when *not* to use Context Builder. - Follow the step-by-step [Starting Workflow in Getting Started](https://repoprompt.com/docs/overview/getting-started/). - Explore the full [Agent Workflow Commands](https://repoprompt.com/docs/agent-mode/workflow-templates/) and [MCP Workflow Commands](https://repoprompt.com/docs/mcp-server/workflow-commands/) guides. - Learn how to adjust token budgets in [Context Builder Settings](https://repoprompt.com/docs/settings/context-builder/). --- ## Installation ### Manual Download and Installation 1. RepoPrompt is a native macOS application available for [download via our repository](https://github.com/repoprompt/repoprompt-ce/releases). Grab the latest `.dmg` file there. 2. Open the downloaded file 3. Drag the RepoPrompt app to your Applications folder 4. Eject the disk image 5. Open RepoPrompt from Applications or Spotlight ### Homebrew Installation You can install the pre-built RepoPrompt macOS binaries via Homebrew: ```bash brew tap repoprompt/repoprompt-ce brew trust --tap repoprompt/repoprompt-ce brew install --cask repoprompt-ce ``` ### Now That It's Installed... Try your first coding task with [Getting Started](https://repoprompt.com/docs/overview/getting-started/): describe a change, prepare a plan, implement, and verify the result. Ready to explore more? [Going Deeper](https://repoprompt.com/docs/overview/going-deeper/) walks you through choosing context, guiding agents, and reviewing your work. ### Updates When automatic checks are enabled and the updater is configured, RepoPrompt checks for updates in the background. You can also check manually through **Settings → General → Updates**. See [Software Updates](https://repoprompt.com/docs/settings/updates/). ### Platform Availability The documented RepoPrompt desktop app is macOS-only. Open-source portability work does not itself establish an official release for another platform. See [Does RepoPrompt Run on Windows or Linux?](https://repoprompt.com/docs/faq/windows-linux/). ### Installing Tip Build Tip Builds are official signed and notarized builds from the latest successful protected `main` commit. They offer development changes before the next Stable release. To install one, open RepoPrompt and go to **Settings → General → Updates**. Set **Update Channel** to **Tip Builds**, choose **Check for Updates**, and follow the updater's installation prompts when an eligible build is offered. If you have not installed RepoPrompt yet, install and launch the current Stable app using the instructions above, then select the Tip Builds channel. The selected channel controls which updates the app offers. To return to Stable, change **Update Channel** back to **Stable**. This may require waiting for a newer Stable release; to return immediately, reinstall the Stable application. See [Software Updates](https://repoprompt.com/docs/settings/updates/) for more about update checks and channel behavior. For the tradeoff between channels, see [What Is the Tip Version and Should I Use It?](https://repoprompt.com/docs/faq/tip-version/). If you want to compile the development source yourself, see [Build Tip code with Xcode](https://repoprompt.com/docs/faq/how-to-build/#build-tip-code-with-xcode). A local Xcode build uses the contributor workflow and is separate from the official signed Tip distribution. --- ## Anthropic API Anthropic API provides direct model requests for supported RepoPrompt features such as Oracle and built-in Chat. It is separate from the [Claude Code CLI](https://repoprompt.com/docs/providers/claude-code-cli/) coding-agent integration. ### Connect Use the Anthropic entry in [API Providers settings](https://repoprompt.com/docs/settings/api-providers/#anthropic). Supply an API credential with access to the intended models and validate it. The custom-model field accepts an exact compatible Anthropic identifier; it does not turn an arbitrary label into a supported model. ### Models and availability Use the provider's supported IDs and the choices available through this connection. Model capabilities, context limits, and support status vary. Review [Anthropic's model lifecycle documentation](https://docs.anthropic.com/en/docs/about-claude/model-deprecations) before retaining a saved custom identifier across model retirements. [Models](https://repoprompt.com/docs/providers/models/) explains shared selection concepts. For RepoPrompt's per-model overrides, see [Model Config](https://repoprompt.com/docs/settings/model-config/); those controls cannot add capabilities absent from the endpoint. ### Account and billing Requests use the Anthropic API account associated with the saved key. A Claude subscription or an authenticated Claude Code runtime does not automatically pay for direct API requests or configure this credential. Check API access and billing on the account that owns the key. --- ## Azure OpenAI Azure OpenAI is a direct model connection to your Azure resource. It requires resource-specific configuration and is distinct from the standard [OpenAI API](https://repoprompt.com/docs/providers/openai-api/) connection and [Codex CLI](https://repoprompt.com/docs/providers/codex-cli/) account login. ### Configure the resource In [API Providers → Azure OpenAI](https://repoprompt.com/docs/settings/api-providers/#azure-openai), provide the resource **Base URL**, supported **API Version**, and **API Key**, then validate. Use a version appropriate to that resource and requested functionality; a version shown in a settings screenshot is illustrative. When discovery offers deployments, select the intended deployment or use the supported custom-deployment control. A deployment name belongs to the Azure resource and need not equal a public model ID used by another API. ### Availability and lifecycle Models must be available for your Azure resource, region, and deployment type. Check Microsoft's [model lifecycle and availability guidance](https://learn.microsoft.com/en-us/azure/foundry/openai/concepts/model-retirements) when a deployment changes or stops serving requests. [Models](https://repoprompt.com/docs/providers/models/) explains deployment identities and the relationship between model capabilities and RepoPrompt controls. Selecting a public model name does not provision an Azure deployment. ### Account and billing Your Azure subscription, resource, deployment, and service terms determine usage and charges. A separate OpenAI API balance or ChatGPT subscription does not automatically pay for calls to this resource. Review billing and quota at the Azure resource used by the connection. --- ## Claude Code Compatible Backend: CC Custom CC Custom directs the installed Claude Code runtime to an Anthropic-compatible endpoint you configure. It is distinct from [Custom API](https://repoprompt.com/docs/providers/custom-api/), which connects to an OpenAI-compatible direct model API. ### Configure the route In [CC Custom settings](https://repoprompt.com/docs/settings/cli-providers/#cc-custom), enable the backend and set its display name, base URL, authentication mode, and credential. Choose the authentication variable expected by the endpoint, save the credential, and use **Test Backend**. The installed Claude executable is required. The endpoint operator determines whether the chosen protocol, authentication, model, and tool behavior are compatible. A saved URL and key are not evidence of a successful request; test the actual route. ### Choose model behavior **No model flag** leaves the model choice to the endpoint and omits Claude model and effort selection. **Claude slot mappings** maps the **Haiku**, **Sonnet**, and **Opus** slots to backend model IDs; all three mappings must be filled before launch in that mode. Use identifiers from the endpoint's own catalog or documentation. See [Models](https://repoprompt.com/docs/providers/models/) for shared identifier and selection concepts. Changing the endpoint or mappings does not make an incompatible model support the Claude runtime's requests. ### Capabilities and billing The route uses the Claude Code integration, but the endpoint's implementation determines the model capabilities and response behavior. Switching between compatible backends and standard Claude Code starts a fresh provider context. The endpoint operator controls billing, privacy, and retention. Use a credential intended for that destination and review its terms. Neither an Anthropic subscription nor an unrelated API account automatically pays for this custom route. --- ## Claude Code Compatible Backend: CC Moonshot CC Moonshot uses the installed Claude Code executable with the Kimi coding endpoint and its own credential. It is a separate route from the standard Claude login and from other Claude-compatible backends. ### Configure and test Open [CC Moonshot settings](https://repoprompt.com/docs/settings/cli-providers/#cc-moonshot), save the Kimi credential, and choose **Test Backend**. The preset base URL is `https://api.kimi.com/coding/`. Advanced controls can change the display name, endpoint, and authentication-variable choice. The Claude executable must be available, but an Anthropic account login is not required for this endpoint route. The credential information control opens the provider's account console. Use the backend test after changing its connection settings. ### Backend-managed models Kimi chooses the model. RepoPrompt supplies neither a `--model` flag nor a Claude Code effort level for this backend. It can therefore appear as one backend choice rather than an exhaustive list of named models. Do not add a model ID copied from the Claude or OpenAI catalog to force a choice this route does not expose. See [Models](https://repoprompt.com/docs/providers/models/) for the distinction between a model identifier, an alias, and backend-managed selection. ### Account and capability boundary The Claude integration supplies its session and tool framework; the compatible endpoint determines actual model behavior and support. Changing between Claude routes starts a fresh provider context so the endpoint and authentication are applied cleanly. Kimi's coding-service account and terms govern access, allowance, billing, and retention. Use the account links in the settings card or the [Moonshot platform](https://platform.moonshot.ai) to inspect the relevant service; an Anthropic subscription does not cover this backend automatically. --- ## Claude Code Compatible Backend: CC Zai CC Zai reuses the installed Claude Code executable with Z.ai's Anthropic-compatible endpoint. It needs the Claude executable and a Z.ai credential, but does not require an Anthropic account login for this backend route. The app's default display name is **CC Zai**; a saved custom display name can replace it. ### Configure the backend Open [CC Zai settings](https://repoprompt.com/docs/settings/cli-providers/#cc-zai), save the credential, inspect the model-slot mappings, and choose **Test Backend**. The test uses the backend's configured endpoint and authentication overrides rather than the standard Claude login. The credential is shared with [Z.AI API](https://repoprompt.com/docs/providers/zai-api/). Changing or deleting it in either settings location affects that saved secret. Endpoint and model configuration remain specific to the relevant integration. ### Model-slot mappings The Claude **Haiku**, **Sonnet**, and **Opus** slots map to backend model IDs. Fill all three slots for mapped-model operation. The slot label alone does not identify the actual model requested from Z.ai. **Reset to GLM defaults** restores the app's preset mappings. Inspect the current fields for their exact IDs rather than relying on a fixed list in documentation. See [Z.ai documentation](https://docs.z.ai/) for model availability and endpoint support, and [Models](https://repoprompt.com/docs/providers/models/) for slot and identifier concepts. ### Capabilities and account boundary The backend uses the Claude Code integration's tool and permission machinery while its endpoint supplies model behavior and usage terms. Test changes to endpoint, authentication mode, or mappings. Switching between standard Claude Code and compatible backends starts a fresh provider context. Z.ai's account or coding-plan terms apply. An Anthropic subscription does not pay for this route, and a shared API credential does not make every Z.ai product's billing or limits identical. --- ## Claude Code CLI Claude Code CLI runs coding sessions through the installed `claude` executable. The app may label this provider **Claude Code**. Its integration supports agent conversations, tool activity, context compaction, and RepoPrompt MCP tools. ### Connect and authenticate Install and authenticate Claude Code using its supported login flow. When login is needed, run `claude login` in your terminal, then open [Claude Code CLI settings](https://repoprompt.com/docs/settings/cli-providers/#claude-code-cli) and choose **Connect**. **Test Connection** rechecks the integration. RepoPrompt's **Sign Out** clears its recorded Claude connection state. Manage the standalone CLI's authentication separately when you need to change that login. This integration is distinct from the [Anthropic API](https://repoprompt.com/docs/providers/anthropic-api/) key configured for direct model requests. ### Models and capabilities The connected runtime supplies model and effort choices. See [Models](https://repoprompt.com/docs/providers/models/) for selection concepts; a label in a captured screenshot is not a permanent default. Claude's permission mode, Bash access, strict MCP scope, and lazy tool loading are configured in its settings. Advanced prompt packaging controls how RepoPrompt delivers Agent Mode instructions. Refer to the [settings controls](https://repoprompt.com/docs/settings/cli-providers/#claude-tools) for their exact effects and when changes apply. ### Compatible backends and accounts [CC Zai](https://repoprompt.com/docs/providers/cc-zai/), [CC Moonshot](https://repoprompt.com/docs/providers/cc-moonshot/), and [CC Custom](https://repoprompt.com/docs/providers/cc-custom/) reuse the Claude executable with different endpoints and credentials. They are separate routes from the standard Anthropic-backed login. Switching between those routes starts a fresh provider context so the endpoint and authentication are applied cleanly. The authentication route determines account usage and billing. A Claude subscription does not automatically cover direct Anthropic API requests or requests billed by a compatible backend operator. --- ## Codex CLI Codex CLI is a coding-agent integration with native session control, streaming, compaction, provider tools, and reasoning effort. It runs the agent that performs work in your selected checkout. It is separate from [OpenAI API](https://repoprompt.com/docs/providers/openai-api/) access. ### Connect and authenticate RepoPrompt includes a managed Codex runtime and maintains its sign-in separately from the ordinary standalone Codex home. In [Codex CLI settings](https://repoprompt.com/docs/settings/cli-providers/#codex-cli), choose **Connect**, then complete **Login with ChatGPT** or the device-code flow. Use **Test Connection** to recheck the integration. Advanced settings can select a custom executable. Runtime selection takes effect on the next app launch, when model availability is refreshed. A version check does not guarantee a custom runtime's compatibility. The settings guide explains executable selection, restoring the included runtime, and signing out. ### Models and capabilities Select from the models and reasoning levels advertised by the active runtime. Available choices depend on the runtime, account, and feature. [Models](https://repoprompt.com/docs/providers/models/) explains identifiers, aliases, effort, and Fast tiers without assuming a fixed release catalog. Codex tool controls cover Bash, Search, Goals, Reasoning Summaries, Local Memories, and configured MCP servers. [Tools](https://repoprompt.com/docs/agent-mode/tools/) explains the composer controls; [Codex settings](https://repoprompt.com/docs/settings/cli-providers/#core-tools-and-runtime-features) documents the individual switches. Eligible direct sessions can also use [Computer Use](https://repoprompt.com/docs/agent-mode/computer-use/) when its companion and local permission requirements are met. ### Account and usage The account signed into RepoPrompt's managed runtime determines access and allowance. It need not be the account used by a separate terminal installation. CLI access does not save an OpenAI API key or pay for direct API requests. Check the connected account's plan and usage for the route being used. --- ## Cursor CLI Cursor CLI connects the installed `cursor-agent` runtime through ACP. RepoPrompt discovers its models and parameters and supplies its MCP integration to the session. ### Connect and authenticate Install the Cursor agent runtime and complete its supported authentication. Open [Cursor CLI settings](https://repoprompt.com/docs/settings/cli-providers/#cursor-cli) and choose **Connect**. The runtime can request login or use supported credentials such as `CURSOR_API_KEY` or `CURSOR_AUTH_TOKEN`. Use **Test Connection** to recheck access and **Refresh Models** to request the current catalog. **Sign Out** disconnects Cursor in RepoPrompt and clears cached model availability. ### Models and capabilities Select from the model, effort, and speed parameters returned by the connected runtime. Cursor's **Auto** option delegates model selection to Cursor; it is distinct from automatic routing in RepoPrompt's Agent Decisions. See [Models](https://repoprompt.com/docs/providers/models/) for shared selection concepts. Model, effort, and speed controls are locked while an active Cursor run is using them. Its ACP approval controls are documented in [CLI Providers settings](https://repoprompt.com/docs/settings/cli-providers/#cursor-cli). Available capabilities depend on the runtime and selected model; a connection does not establish unrestricted access to every tool. ### Account and usage Cursor authentication and its account terms determine access and allowance. Connecting this runtime does not configure the same model through a separate API provider or transfer Cursor account entitlement to that API. Check the account and selected runtime route when assessing usage. --- ## Custom API Custom API connects a separate OpenAI-compatible model endpoint to supported RepoPrompt features. It is distinct from [CC Custom](https://repoprompt.com/docs/providers/cc-custom/), which routes the Claude Code coding runtime through an Anthropic-compatible endpoint. ### Configure the connection Open [Custom API settings](https://repoprompt.com/docs/settings/custom-api/) and enter the provider URL, including its API version path where required, and the credential expected by that endpoint. An endpoint that requires no authentication can use an empty key. Leave **Preferred Model ID** blank to discover models. If the endpoint cannot list models, supply its exact compatible model ID instead. Validation with a preferred model sends a short test completion request, so it contacts the provider rather than merely checking the field format. The settings reference describes output-token limits, model enablement, the Content-Type option, credential handling, and removal. Validate changes before relying on the route. ### Models and compatibility The endpoint operator determines available models and protocol behavior. OpenAI compatibility does not guarantee support for every streaming, tool, image, or reasoning feature. Follow the endpoint's documentation and [Models](https://repoprompt.com/docs/providers/models/) when choosing an identifier and capabilities. Per-model overrides in [Model Config](https://repoprompt.com/docs/settings/model-config/) can adapt supported request behavior; they cannot implement missing endpoint functionality. ### Account and billing The endpoint's operator controls billing, quotas, privacy, and retention. A credential or subscription for another service does not establish entitlement here. Confirm the destination before saving credentials; the app can request consent before sending them to a non-HTTPS endpoint. --- ## DeepSeek DeepSeek provides direct API access for supported RepoPrompt model features. Configure the credential through [API Providers → DeepSeek](https://repoprompt.com/docs/settings/api-providers/#deepseek), validate it, and select an available model or supported custom identifier. ### Models and availability Use the [DeepSeek model-list documentation](https://api-docs.deepseek.com/api/list-models/) for current API identifiers and the connection's discovered choices for actual availability. A model ID can change its backing release or retire; a name captured in a screenshot is not a permanent default. Check the selected model's capabilities and limits for the feature you intend to use. [Models](https://repoprompt.com/docs/providers/models/) explains how model IDs, context capacity, effort, and output settings differ. A per-model override cannot add functionality the provider does not implement. ### Account and billing Requests are associated with the account owning the DeepSeek credential. Review its current [API pricing](https://api-docs.deepseek.com/quick_start/pricing/) and account usage rather than relying on a price or free quota copied into a guide. RepoPrompt does not add a markup or transfer allowance from another provider. The [settings reference](https://repoprompt.com/docs/settings/api-providers/#deepseek) explains validation, model selection, and credential removal. Removing the key in RepoPrompt does not close the provider account. --- ## Devin CLI Devin CLI runs coding sessions through the installed `devin acp` runtime. Devin manages its authentication and internal tools; RepoPrompt supplies the session interface and supported integration. ### Prepare the runtime Install and authenticate Devin using its own supported tools. Open [Devin CLI settings](https://repoprompt.com/docs/settings/cli-providers/#devin-cli) to inspect runtime availability and request **Refresh Models**. The availability indicator describes installation, not a guarantee that authentication or every model request will succeed. ### Models and permission behavior Choose from the runtime's discovered models. Devin can encode thinking choices in model identifiers rather than exposing a separate native effort level. Follow the returned choices and the [Models guide](https://repoprompt.com/docs/providers/models/), not names copied from another provider's menu. The selected permission mode applies to newly started processes. The settings reference describes **Provider Default**, **Normal**, **Accept Edits**, **Smart**, and **Full Approval**, including which actions can run automatically. This integration does not expose Devin's autonomous mode. A permission mode is specific to the runtime. It does not establish the same sandbox guarantees as similarly named choices on other providers. Inspect the current session's tools, permissions, and execution location before assigning file changes. ### Account and usage Devin's authenticated account and product terms determine allowance and charges. Manage that account through Devin's own authentication tools. Connecting another CLI provider or direct API account in RepoPrompt does not grant Devin access. --- ## Fireworks AI Fireworks AI supplies direct API model access for supported RepoPrompt features. Configure its credential in [API Providers → Fireworks AI](https://repoprompt.com/docs/settings/api-providers/#fireworks-ai), validate it, and inspect the discovered model choices. ### Models and capabilities Use the [Fireworks model library](https://fireworks.ai/models) to investigate available models. Selection in RepoPrompt depends on what the connected API account and serving configuration expose. A published library entry does not automatically establish access through every account or endpoint. Choose a model suitable for the intended feature and confirm its actual limits. [Models](https://repoprompt.com/docs/providers/models/) explains the shared availability and identifier concepts. Keep the exact selection with the connection instead of copying an assumed model default into workflow instructions. ### Account and billing The Fireworks account, selected model, and serving option determine usage charges. Consult [Fireworks pricing](https://fireworks.ai/pricing) and the account's billing controls for current terms. A subscription or credential from another AI provider does not supply allowance for this API route. The settings page owns the field and button descriptions for validation, discovered choices, changing a credential, and deleting it. An empty model list should be investigated through that connection rather than treated as a complete statement of the provider's public catalog. --- ## Gemini API Gemini API connects supported RepoPrompt features directly to Google's model API. It uses the **Gemini** entry in API Providers and is separate from the [Google Antigravity](https://repoprompt.com/docs/providers/google-antigravity/) coding-agent runtime and its ACP authentication. ### Connect and select a model Configure and validate the key in [API Providers → Gemini](https://repoprompt.com/docs/settings/api-providers/#gemini). Use the custom-model field where provided to save a compatible model identifier. The settings reference describes the field and its save control. Google's [Gemini API model catalog](https://ai.google.dev/gemini-api/docs/models) is the reference for current IDs, capabilities, and lifecycle status. Stable, preview, and retired selections can differ, and availability depends on the account and integration. Do not assume a similarly named model in another Google product is exposed through this API route. [Models](https://repoprompt.com/docs/providers/models/) explains identifier and capability selection. A per-model setting cannot grant access to a missing model or add unsupported image, streaming, or reasoning behavior. ### Account and billing The API credential and Google's applicable account terms determine usage limits and charges. A separate Google subscription or Antigravity login does not automatically configure or pay for these API requests. Check the API account's current terms and usage rather than relying on a fixed free-tier claim in documentation. --- ## Google Antigravity Google Antigravity is a coding-agent integration using a managed ACP runtime. It is distinct from saving a [Gemini API](https://repoprompt.com/docs/providers/gemini-api/) key for direct model requests. ### Install and connect Open [Google Antigravity settings](https://repoprompt.com/docs/settings/cli-providers/#google-antigravity) and choose **Install Runtime**. Use **Update Runtime** for an existing installation and **Test Connection** to check support and refresh model discovery. Google authentication is requested through ACP when needed. An installation indicator means the runtime is available; it does not establish that login is complete or that selectable models were returned. Follow the authentication request and inspect the connection result before starting a task. ### Models and capabilities The connected runtime supplies its supported model choices and session capabilities. Use that catalog rather than assuming it matches the direct Gemini API catalog. [Models](https://repoprompt.com/docs/providers/models/) explains the shared availability and parameter concepts. Antigravity uses its ACP session modes and manages its runtime capabilities. Its CLI Providers card has no separate sign-out or inline permission picker. Review the available [Direct Agent permission controls](https://repoprompt.com/docs/settings/agent-permissions/#direct-agents) for the installed runtime instead of applying another provider's permission descriptions to it. ### Account and usage The authenticated Google account and runtime's service terms determine access and allowance. A Gemini API key or a separate Google subscription does not, by itself, establish access through this managed runtime. Check the actual login and runtime state when troubleshooting availability. --- ## Grok Build Grok Build connects the installed `grok` runtime to Agent Mode. It is a coding-agent integration with model discovery and provider-native shell and editing capabilities. Direct [Grok / xAI API](https://repoprompt.com/docs/providers/xai-api/) model access is a separate integration. ### Connect and authenticate Make the Grok runtime available, authenticate with `grok login` or configure the API credential supported by the integration, then open [Grok Build settings](https://repoprompt.com/docs/settings/cli-providers/#grok-build). Choose **Connect** and inspect the model-discovery result. **Test Connection** rechecks access; **Sign Out** disconnects Grok Build in RepoPrompt and clears cached availability. ### Models and permissions Use models discovered from the connected runtime. A model visible in xAI's public API catalog does not automatically identify the same selection in the coding runtime. See [Models](https://repoprompt.com/docs/providers/models/) for discovery and identifier guidance. Grok's launch approval choice applies to newly started processes. Its Full Access option starts the runtime with always-approve behavior for shell and editing tools. The [settings reference](https://repoprompt.com/docs/settings/cli-providers/#grok-build) explains the exact launch controls. Grok's own rules can also affect approval behavior; do not treat its modes as identical to Codex's sandbox levels. ### Account and usage The route used by the runtime determines the account and usage terms. When the integration supplies an xAI API key, requests using that credential are billed to the corresponding API account. Check whether a run is using account login or an API credential before assuming that one account plan covers it. --- ## Groq Groq is a direct API provider configured with its own credential. **Groq** and **Grok (xAI)** are different services and settings entries; credentials and model selections do not transfer between them. ### Connect and select a model Use [API Providers → Groq](https://repoprompt.com/docs/settings/api-providers/#groq), validate the key, and inspect the discovered models. The [Groq model catalog](https://console.groq.com/docs/models) describes the hosted models, while [deprecation notices](https://console.groq.com/docs/deprecations) identify retirement changes. Actual availability depends on the connected account and integration. Use the current returned identifier instead of assuming a model hosted by another service has the same ID or capabilities here. [Models](https://repoprompt.com/docs/providers/models/) explains that distinction and the separate roles of context limits, effort, and output controls. ### Account and billing Requests use the Groq account associated with the saved credential. The provider controls its usage terms, quotas, rate limits, and charges. RepoPrompt cannot guarantee that a particular account or hosted model has free allowance. The [settings reference](https://repoprompt.com/docs/settings/api-providers/#groq) describes credential and discovered-model controls. If the list changes after a refresh, check both connection access and the provider's lifecycle notices before reusing an older saved ID. --- ## Local Models: Ollama and LM Studio The local-model integration connects RepoPrompt to a model server you run, such as Ollama or LM Studio. You install the server and obtain its models separately; saving a URL in RepoPrompt does not install or start either service. ### Prepare and connect Start the model server and make the intended model available there. Open [API Providers → Local Model Settings](https://repoprompt.com/docs/settings/api-providers/#local-model-settings), enter its URL, and choose **Validate & fetch models**. After discovery succeeds, select a model. Common local ports are **11434** for Ollama and **1234** for LM Studio. Use the actual address configured by your server rather than assuming a default port proves the service is running. The settings guide explains refreshing discovery and resetting the saved configuration. ### Models and capabilities Model availability comes from the connected server. Browse [Ollama's model library](https://ollama.com/library) or inspect the models installed in LM Studio, then confirm what the server exposes to RepoPrompt. Capabilities and practical context limits depend on the model, server, and hardware. See [Models](https://repoprompt.com/docs/providers/models/) for selection concepts. A local-server connection does not automatically provide the coding-agent runtime or feature set of a CLI provider. ### Local resources and hosted routes Inference that actually runs locally has no hosted per-token API bill from RepoPrompt, but uses your computer's memory, processing, storage, and electricity. A server configured to call a cloud model or remote endpoint can have separate provider charges and data practices. Check where the chosen request runs before treating it as local. --- ## Models Choose models from the connection you intend to use. RepoPrompt combines built-in catalog information with model discovery where the integration supports it. The connected model picker determines what is selectable in that feature; a provider's public catalog alone does not establish availability in your account or runtime. This guide is the shared reference for model concepts. Use the [provider directory](https://repoprompt.com/docs/providers/overview/) for connection-specific setup and catalog links, [Model and Effort](https://repoprompt.com/docs/agent-mode/model-and-effort/) for the session controls, and [Agent Models settings](https://repoprompt.com/docs/settings/agent-models/) for configured defaults and workspace overrides. ### Availability and discovery A CLI runtime can expose a different model set from the same company's direct API. API access can also depend on region, account permissions, deployment, or the endpoint operator. Refresh or test the relevant connection when a model is missing; changing a model's display label cannot make an unsupported model available. Some integrations discover models. Others accept an exact custom model identifier, a deployment choice, or a backend that chooses its own model. OpenRouter requires registering the fetched models you want to expose. Custom API can use discovered models or a preferred model ID. Follow the individual provider guide for the supported route. #### Model catalog Choose the model and effort exposed by your connection; the [Codex integration](https://repoprompt.com/docs/providers/codex-cli/) and [OpenAI API integration](https://repoprompt.com/docs/providers/openai-api/) have separate runtimes, authentication, and availability. A new-task default does not replace an established session's model. Use [Agent Models settings](https://repoprompt.com/docs/settings/agent-models/) to inspect effective defaults and workspace overrides. ### Names, identifiers, aliases, and presets The human-readable label in a picker can differ from the identifier sent to a runtime or API. Reuse the choice returned by that connection instead of guessing an identifier from a screenshot or another provider's catalog. An **alias** or **Auto** choice delegates some selection to the provider. It may not identify one fixed underlying model and does not necessarily qualify for every automatic-effort feature. A **deployment name** identifies an Azure resource deployment rather than universally naming a public model. An **Oracle Model Preset** is a named configuration. It can contain a primary model, additional Oracles, and a mapped Chat Preset. It is not itself a model identifier. Claude-compatible backends can instead map the Claude **Haiku**, **Sonnet**, and **Opus** slots to endpoint model IDs, or omit the model flag and let the backend decide. ### Reasoning effort Effort chooses among reasoning levels advertised for the selected model. Labels such as **Low**, **Medium**, and **High** are examples, not a universal set or a standardized quantity across providers. Some runtimes expose thinking parameters or encode thinking choices in the model ID; others offer no separate effort control. More effort can increase latency and usage. Compare results on the work you actually need rather than assuming the highest level is always appropriate. Effort, maximum output length, and context capacity are separate controls: raising one does not necessarily raise the others. An effort choice applies to a turn. [Auto Effort](https://repoprompt.com/docs/agent-mode/auto-effort/) can choose before eligible user turns on an explicitly selected supported model. It does not retune effort between tool calls in an active turn. Model routing in [Agent Decisions](https://repoprompt.com/docs/agent-mode/model-router/) chooses a model and initial effort for eligible new tasks. Those guides own the features' eligibility, privacy, and fallback behavior. ### Speed and service tiers A **Fast** variant or API service tier changes the service route or speed/cost behavior where supported. It is separate from reasoning effort and can consume allowance or credits differently. A lightning symbol is not a universal quality rating. Choose tiers supported by the actual connection. OpenAI's API service-tier controls, a CLI runtime's Fast option, and OpenRouter routing are different mechanisms; their settings do not automatically carry across providers. Consult the relevant provider page and account's current terms. ### Model roles RepoPrompt uses model choices in several places: | Choice | Responsibility | | --- | --- | | **Session execution model** | Runs the coding agent and its permitted tools. | | **Oracle roster** | Provides consultations for plans, reviews, or answers using prepared context. | | **Context Builder agent and model** | Explores the repository and assembles relevant context. | | **Re-prompt model** | Rewrites a draft before the execution agent receives it. | | **Agent role defaults** | Map task labels to configured provider/model choices. | For discovery, consider latency, reliable repository-tool use, and the amount of context the agent must inspect. For implementation, consider instruction following and reliable editing and tool use. For Oracle planning or review, consider reasoning over the complete prepared package. These are task requirements, not permanent rankings of named model releases. The **Explore**, **Engineer**, **Pair**, and **Design** role labels resolve through the effective [Agent Models profile](https://repoprompt.com/docs/settings/agent-models/#sub-agent-role-defaults). Explore suits focused investigation, Engineer implementation, Pair interactive work, and Design architectural discussion or critique. A role mapping is not a sandbox policy or a universal guarantee of read-only behavior. Dedicated exploration tools and permission settings impose their own restrictions. ### Recommendations and screenshots Use the app's current Setup Wizard and available-model controls to evaluate recommendations for your connected providers. Available choices and recommendations can change when the runtime, catalog, account, or app version changes. Screenshots capture one interface state. Their model names, selected effort, token capacities, and provider counts are illustrative, not promised defaults. General guides therefore emphasize providers, capabilities, and selection procedures instead of maintaining exhaustive named model lists. For an exact model ID, capability, retirement, or price, use the official catalog linked from the provider's page and verify availability through your connection. When documentation must discuss a particular release, identify the app version or review date and keep that claim with the relevant provider reference. Historical changelogs retain the model names necessary to describe their release. --- ## OpenAI API OpenAI API connects supported RepoPrompt model features directly to an API account. It is separate from the [Codex CLI](https://repoprompt.com/docs/providers/codex-cli/) runtime and RepoPrompt-managed ChatGPT sign-in. ### Connect Validate a credential in [API Providers → OpenAI](https://repoprompt.com/docs/settings/api-providers/#openai) to fetch available models. The settings page documents API service tiers, tier-specific model variants, and the optional custom base URL. For an independently configured OpenAI-compatible service, use [Custom API](https://repoprompt.com/docs/providers/custom-api/). For an Azure resource deployment, use [Azure OpenAI](https://repoprompt.com/docs/providers/azure-openai/). Compatibility with the OpenAI protocol does not establish the same account, model IDs, or service terms. ### Models and capabilities The [OpenAI API model catalog](https://platform.openai.com/docs/models) is the provider reference for model identifiers and capabilities. Actual selection depends on the API account, endpoint, and integration support. A model available through a CLI or subscription product is not necessarily available through this API connection. [Models](https://repoprompt.com/docs/providers/models/) explains effort and service tiers. Use [Model Config](https://repoprompt.com/docs/settings/model-config/) for supported streaming, API-routing, and temperature overrides; these do not grant access to unavailable models. ### Account and billing The API project and credential determine request charges and quotas. A ChatGPT subscription or Codex login does not automatically fund API calls. Inspect the relevant API account and service tier when assessing usage. --- ## OpenCode CLI OpenCode CLI connects coding sessions through Agent Client Protocol (ACP). The app may label it **OpenCode**. Its available models come from the providers configured in OpenCode, which can differ from the direct API connections configured in RepoPrompt. ### Connect and authenticate Make the `opencode` runtime available and configure the intended providers in OpenCode. Authenticate there as needed, for example with `opencode auth login`. Open [OpenCode CLI settings](https://repoprompt.com/docs/settings/cli-providers/#opencode-cli), choose **Connect**, and inspect the discovered-model summary. **Test Connection** rechecks access. Signing out in RepoPrompt clears its connection and cached availability; manage OpenCode's credentials through OpenCode itself. ### Models and capabilities RepoPrompt discovers the runtime's model choices and supported parameters. Use the current picker rather than copying model IDs from another connection. [Models](https://repoprompt.com/docs/providers/models/) explains why provider aliases, effort parameters, and direct API models are not interchangeable. Interactive sessions use ACP and provider tools alongside RepoPrompt's integration. Headless discovery uses a separate managed tool configuration. The provider's [ACP Session Mode controls](https://repoprompt.com/docs/settings/cli-providers/#opencode-cli) govern approval behavior for supported requests; do not assume that another provider's sandbox or MCP switches have identical effects here. ### Account and usage The upstream providers configured in OpenCode determine authentication, model availability, quotas, and charges. Some configurations can offer free access, but RepoPrompt does not establish the terms of that access. Review the provider route selected in OpenCode when comparing usage or troubleshooting a missing model. --- ## OpenRouter OpenRouter is a separate API route for models served through your OpenRouter account. It has its own settings page rather than a row in the direct API-provider pane. A model available through OpenRouter can have a different identifier, route, availability, and price from a direct connection to its originating provider. ### Connect and register models Open [OpenRouter settings](https://repoprompt.com/docs/settings/openrouter/), validate an API key, and fetch the catalog. Search the fetched models and register the choices you want to appear in RepoPrompt. Fetching the catalog does not automatically register every entry. The settings reference owns the descriptions of registered-model removal, catalog refresh, custom headers, and output limits. Removing a registration hides that selection in RepoPrompt; it does not remove the model from the provider's service. ### Model metadata OpenRouter's [model API](https://openrouter.ai/docs/api/api-reference/models/get-models) is the provider reference for IDs, context information, modalities, and pricing metadata. Use the current account-accessible catalog and exact returned identifier. A similarly named model on another route is not necessarily interchangeable. [Models](https://repoprompt.com/docs/providers/models/) explains these naming and capability distinctions. Request settings and headers cannot add a capability the selected model or route lacks. ### Account and billing Your OpenRouter account and selected service route determine charges and allowance. An account or subscription with the model's originating provider does not automatically fund OpenRouter requests. Review the actual route and account when assessing usage, privacy, and retention. --- ## Providers & Models Start here to choose and connect a provider. Each integration's page is the reference for its account requirements, model discovery, capabilities, and limitations. [Models](https://repoprompt.com/docs/providers/models/) explains identifiers, aliases, reasoning effort, speed tiers, and choosing models for different roles. A **provider** supplies an agent runtime or model service. A **model** is a choice available through that connection. The same company can offer separate CLI and API products with different authentication, billing, and capabilities. For example, connecting Codex CLI does not configure OpenAI API access, and signing into Claude Code does not save an Anthropic API key. ### Provider comparison Choose the connection that matches the work and account you intend to use. The summaries below wrap naturally on narrow screens; open an individual guide for setup and limitations. ### Coding agents These ten integrations run coding-agent sessions. Configure their controls in [CLI Providers settings](https://repoprompt.com/docs/settings/cli-providers/). The app can abbreviate **Claude Code CLI** to **Claude Code** and **OpenCode CLI** to **OpenCode**. 1. **[Codex CLI](https://repoprompt.com/docs/providers/codex-cli/)** — included or custom runtime with RepoPrompt-managed ChatGPT sign-in. 2. **[Claude Code CLI](https://repoprompt.com/docs/providers/claude-code-cli/)** — installed Claude runtime with Anthropic authentication. 3. **[OpenCode CLI](https://repoprompt.com/docs/providers/opencode-cli/)** — ACP runtime using providers configured in OpenCode. 4. **[Cursor CLI](https://repoprompt.com/docs/providers/cursor-cli/)** — Cursor runtime with discovered models and provider parameters. 5. **[Grok Build](https://repoprompt.com/docs/providers/grok-build/)** — installed Grok runtime with login or a configured API key. 6. **[Google Antigravity](https://repoprompt.com/docs/providers/google-antigravity/)** — managed ACP runtime with Google authentication. 7. **[Devin CLI](https://repoprompt.com/docs/providers/devin-cli/)** — Devin ACP runtime with its own authentication and permission modes. 8. **[Claude Code Compatible Backend: CC Zai](https://repoprompt.com/docs/providers/cc-zai/)** — Claude runtime routed to Z.ai with model-slot mappings. 9. **[Claude Code Compatible Backend: CC Moonshot](https://repoprompt.com/docs/providers/cc-moonshot/)** — Claude runtime routed to Kimi, which manages the model choice. 10. **[Claude Code Compatible Backend: CC Custom](https://repoprompt.com/docs/providers/cc-custom/)** — Claude runtime routed to an Anthropic-compatible endpoint you configure. ### API and local services Direct model connections primarily serve Oracle, built-in Chat, and other supported model features. They do not by themselves install a coding-agent runtime. The **API Providers** pane contains ten direct API or local configurations: - [Anthropic API](https://repoprompt.com/docs/providers/anthropic-api/) - [OpenAI API](https://repoprompt.com/docs/providers/openai-api/) - [DeepSeek](https://repoprompt.com/docs/providers/deepseek/) - [Fireworks AI](https://repoprompt.com/docs/providers/fireworks-ai/) - [Grok / xAI API](https://repoprompt.com/docs/providers/xai-api/) - [Groq](https://repoprompt.com/docs/providers/groq/) - [Z.AI API](https://repoprompt.com/docs/providers/zai-api/) - [Gemini API](https://repoprompt.com/docs/providers/gemini-api/) - [Azure OpenAI](https://repoprompt.com/docs/providers/azure-openai/) - [Local models: Ollama and LM Studio](https://repoprompt.com/docs/providers/local-models/) [OpenRouter](https://repoprompt.com/docs/providers/openrouter/) and [Custom API](https://repoprompt.com/docs/providers/custom-api/) are additional routes with their own configuration pages. Use [API Providers settings](https://repoprompt.com/docs/settings/api-providers/) for the direct-provider fields and controls. ### Choose and switch providers Connect the intended runtime or service, complete its authentication, and test the connection. Then choose from the models that connection actually offers. A provider's published catalog can be broader than what your account, runtime, region, or deployment exposes. Use [Model and Effort](https://repoprompt.com/docs/agent-mode/model-and-effort/) to operate the session picker. Configure Oracle, Context Builder, and role defaults in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). Those choices serve different purposes and can use different connections; see [Model roles](https://repoprompt.com/docs/providers/models/#model-roles). ### Provider environment filtering If your shell environment contains credentials or endpoint settings for several providers, **Provider environment filtering (opt-in)** can withhold selected ambient variables from new provider processes. In **Settings → Agent Mode → Overview**, enter exact, case-sensitive variable names to withhold, then add per-provider pass-through exceptions for names that connection needs. Enter names only, separated by spaces or commas; values and wildcards are not accepted. Empty lists preserve the existing environment. Choose **Apply**, then start a new provider process to use the saved rules. Filtering also applies to provider probes and headless launches, but does not change already-running processes or your interactive terminal. Explicit app/runtime launch overrides remain available. If authentication or a tool stops working after filtering, check whether it depends on a withheld variable and add a narrow exception for that provider. This is a partial mitigation: it does not isolate credential files, shell profiles, or other resources available to the same macOS user. See [Agent Mode settings](https://repoprompt.com/docs/settings/overview/) for the controls. ### Accounts and billing RepoPrompt is free and does not add a provider markup. The selected account and route determine usage charges and quotas. A CLI subscription does not automatically pay for API calls, and an API credential does not establish access to a separate CLI subscription product. Each provider page explains the relevant distinction and links to its catalog where applicable. For the short billing answer, see [Do I need to pay for AI services?](https://repoprompt.com/docs/faq/pay-for-services/). For changing model catalogs and screenshots, follow the [Models guide](https://repoprompt.com/docs/providers/models/#recommendations-and-screenshots) rather than treating a captured model name as a permanent default. --- ## Grok / xAI API The **Grok (xAI)** entry connects supported RepoPrompt model features directly to the xAI API. It is separate from [Grok Build](https://repoprompt.com/docs/providers/grok-build/), which runs a coding-agent CLI. It is also unrelated to the separately configured [Groq](https://repoprompt.com/docs/providers/groq/) service. ### Connect and choose models Validate the xAI credential in [API Providers → Grok (xAI)](https://repoprompt.com/docs/settings/api-providers/#grok-xai) and inspect the discovered models. Use the provider's [model catalog](https://docs.x.ai/developers/models) and [release notes](https://docs.x.ai/developers/release-notes) for current identifiers and service changes. Available choices depend on API account access and integration support. Do not assume that a Grok Build runtime model name is interchangeable with a direct API ID. See [Models](https://repoprompt.com/docs/providers/models/) for availability and naming concepts. ### Credentials and billing The configured API key can also be used by integrations that support the Grok API-key route, including Grok Build. The presence of that runtime does not change the billing boundary: requests authenticated with the key are associated with its xAI API account. Check which route a task is using before comparing allowance or charges with a separate account-login product. The [settings reference](https://repoprompt.com/docs/settings/api-providers/#grok-xai) describes key validation and model controls; the Grok Build guide covers runtime setup. --- ## Z.AI API Z.AI provides direct API model access for supported RepoPrompt features. It is distinct from [CC Zai](https://repoprompt.com/docs/providers/cc-zai/), which runs the Claude Code runtime through Z.ai's compatible coding endpoint. ### Connect and choose models Use [API Providers → Z.AI](https://repoprompt.com/docs/settings/api-providers/#zai) to save and validate the credential and choose a supported custom model where offered. Refer to [Z.ai's documentation](https://docs.z.ai/) for the current model catalog and API support. Use an identifier available through the actual connection rather than a fixed model release listed in a screenshot. ### Shared credential, distinct routes This saved credential is shared with CC Zai. Changing or deleting it in either settings location affects the same secret. Saving it also makes the compatible backend available when its runtime prerequisites and configuration are satisfied. Direct API model selection and the CC Zai Claude-slot mappings are separate configurations. A shared key does not mean they expose identical models, endpoints, or capabilities. See [Models](https://repoprompt.com/docs/providers/models/) and the CC Zai guide before changing those mappings. ### Account and billing Z.ai's terms for the account, endpoint, and product determine allowance and charges. Check which route is being used rather than assuming that a coding plan and a general API call share the same allowance. RepoPrompt does not add a provider markup. --- ## Settings Reference Open Settings with `⌘+,` or from the gear icon. Use this directory to reach the detailed guide for each settings page. Those guides document the controls and their behavior. Use [Search Settings](https://repoprompt.com/docs/settings/search-settings/) to find an option by name. For supported integrations, account requirements, model availability, and capabilities, use [Providers & Models](https://repoprompt.com/docs/providers/overview/). ### Agent Mode - [Overview](https://repoprompt.com/docs/settings/overview/): general Agent Mode behavior and supervision. - [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/): connect and configure coding runtimes. - [Agent Models](https://repoprompt.com/docs/settings/agent-models/): model choices for agent roles and supporting tasks. - [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/): direct-agent and sub-agent permissions. - [Agent Workflows](https://repoprompt.com/docs/settings/agent-workflows/): workflow behavior and related controls. - [Agent Decisions](https://repoprompt.com/docs/settings/agent-decisions/): automatic routing, effort selection, usage balancing, and decision services. - [Context Builder](https://repoprompt.com/docs/settings/context-builder/): discovery and context-generation settings. ### General Settings - [Appearance](https://repoprompt.com/docs/settings/appearance/): interface appearance and text presentation. - [Updates](https://repoprompt.com/docs/settings/updates/): update checks and release channels. - [Notifications](https://repoprompt.com/docs/settings/notifications/): notification preferences. - [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/): configurable shortcuts. - [Advanced](https://repoprompt.com/docs/settings/advanced/): advanced preferences, including the URL Opener. - [Telemetry](https://repoprompt.com/docs/settings/telemetry/): crash-report and diagnostic controls. ### API Settings The settings category is **Models & Providers**. Start with [Providers & Models](https://repoprompt.com/docs/providers/overview/) for the canonical connection and capability reference, then open the relevant settings guide: - [API Providers](https://repoprompt.com/docs/settings/api-providers/). - [OpenRouter](https://repoprompt.com/docs/settings/openrouter/). - [Custom API](https://repoprompt.com/docs/settings/custom-api/). - [Model Config](https://repoprompt.com/docs/settings/model-config/). ### Chat Settings The settings category is **Prompting**: - [Chat Settings](https://repoprompt.com/docs/settings/chat-settings/): built-in chat behavior. - [Copy Prompt Order](https://repoprompt.com/docs/settings/copy-prompt-order/): ordering and packaging copied context. - [Workflow Presets](https://repoprompt.com/docs/settings/workflow-presets/): preset instructions and workflow definitions. ### MCP Settings - [MCP Server](https://repoprompt.com/docs/settings/mcp-server/): server configuration and connections. - [Workspace Approvals](https://repoprompt.com/docs/settings/workspace-approvals/): workspace access approvals. - [Tools](https://repoprompt.com/docs/settings/tools/): tool availability and configuration. - [Model Presets](https://repoprompt.com/docs/settings/model-presets/): model choices exposed through MCP. ### Workspace Settings - [Manage Workspaces](https://repoprompt.com/docs/settings/manage-workspaces/): workspace and folder management. - [Manage Presets](https://repoprompt.com/docs/settings/manage-presets/): saved workspace selections and presets. ### Scripting settings A subset of preferences is available through MCP and `rpce-cli`. Use the [App Settings Tool](https://repoprompt.com/docs/mcp-server/mcp-app-settings/) for the authoritative allowlist and the [Setup Guide](https://repoprompt.com/docs/mcp-server/mcp-setup/#terminal-access) for terminal access. A control being visible in Settings does not mean it is available through that tool. --- ## Agent Decisions (Agent-mode) Open **Settings → Agent Mode → Agent Decisions**, between **Agent Workflows** and **Context Builder**. Choose how RepoPrompt selects execution models and reasoning effort, balances plan usage, and connects to decision services. These controls have separate responsibilities: | Feature | What it changes | When it applies | | --- | --- | --- | | Model Router | Selects a provider, model, and initial reasoning effort | Eligible new primary sessions and managed sub-agents | | Auto Effort | Selects reasoning effort while keeping your chosen model | Eligible user turns, including follow-ups after a turn finishes | | Usage Balancing | Can substitute a comparable model on another connected plan | Eligible new tasks; usage decisions stay on your Mac | | Decision Services | Supplies the service used by Model Router or Auto Effort | When selected and configured for that feature | The screenshots show the interface with unconfigured services. Captured model names and selections are examples, not recommended defaults. Use [Providers & Models](https://repoprompt.com/docs/providers/overview/) for connection requirements and the [Models reference](https://repoprompt.com/docs/providers/models/) for availability, effort, and service tiers.
View the complete Agent Decisions settings pane Agent Decisions pane with Model Router, Auto Effort, Usage Balancing, and expanded decision-service cards
### Enable Model Router Model Router status, decision-service selector, paid Fast option, routing configuration, custom guidance, and sharing disclosures Select a **Decision service** and choose **Configure** to open its configuration card. Configure the service and connect a supported execution provider before enabling the switch. **OFF — Needs configuration** means the selected service still needs setup. A paused or unavailable state needs attention even if you previously enabled routing. Model Router stays enabled across sessions until you turn it off. It selects a provider, model, and initial reasoning effort for eligible new tasks, even when Auto Effort is off. Existing sessions and explicit MCP model pins retain their targets. If routing cannot return a valid choice, the task uses the current selection or its agent-role default. #### Paid Fast tiers **Allow paid Fast tiers in automatic routing** is off by default. Enable it to include eligible paid Fast variants in automatic selection. They can consume allowance or credits more quickly. This option does not change models you explicitly select yourself. #### Routing configuration Expand **Routing configuration** to inspect **Available models** and edit **Custom guidance**. The available-model chips reflect the current catalog and connected providers. They are not a fixed roster. [Agent Models](https://repoprompt.com/docs/settings/agent-models/) role settings supply reference signals rather than forcing every routing decision to a role's default model. Use guidance for preferences such as “Prefer my connected coding provider for implementation.” The editor accepts **1,000 characters**. **Save Guidance** saves a changed draft within that limit; clear the text and save to remove it. Guidance shapes recommendations among eligible models. It does not add unavailable models or bypass provider restrictions. Usage Balancing can subsequently select a comparable model on another plan. #### What gets shared **What Router shares** explains that the selected service receives a short, best-effort-masked task excerpt, saved guidance, Agent Models role references, and descriptions of candidate providers, models, and effort levels. Attached files, workspace context, file paths, chat history, tool results, and execution-provider credentials are not appended to that request. Text you type into the task or guidance can still contain sensitive information. Masking can miss it. Review the selected service's own privacy disclosure as well. The complete task goes to the selected execution agent separately. ### Auto effort Auto Effort status and independent decision-service selector, with sharing and eligibility explanations Auto Effort has its own **Decision service** selector and **Configure** button. Changing Model Router's service does not change Auto Effort's service. Configure the selected service, then enable Auto Effort when you want automatic reasoning-level selection for a model you explicitly chose. The model must support multiple effort levels. Auto Effort can run when a session starts through MCP or when you send a follow-up after the preceding turn finishes: - Default model selections, model aliases, and custom workflows retain manual effort. - A session already handled by Model Router keeps its routed effort for that start. - Messages sent while a turn is running keep the effort already in use; effort does not change between tool calls. - If the service is unavailable or cannot select a valid option, RepoPrompt uses your manual effort setting. **What Auto Effort shares** describes a message excerpt, the selected model ID, available effort levels, and the category of any selected built-in workflow. Workflow-template bodies, attached files, tool results, and earlier conversation are not included. Masking is best effort; turn Auto Effort off for private tasks. Effort changes can affect provider caching, and savings are not guaranteed. ### Usage balancing Usage Balancing switch, three strategies, critical-usage override, Manage plan usage, and background-refresh controls Connect plan usage through **Manage plan usage…** before relying on readings. Usage-source setup is separate from connecting the coding runtime; see [Plan usage controls](https://repoprompt.com/docs/settings/cli-providers/#plan-usage). Balancing compares each plan's remaining allowance and reset time, not token capacities. Only comparable models are substituted. Existing sessions and explicit MCP model pins keep their targets. Usage readings and balancing decisions stay on your Mac. Usage Balancing is off by default. Its default strategy when enabled is **Even pace**: | Strategy | Behavior | | --- | --- | | **Only near limits** | Keeps the starting model unless its plan is at least 90% used. | | **Even pace** | Favors the plan with more unused weekly allowance relative to time until reset. | | **Use expiring quota first** | Favors spare weekly allowance resetting within a day; otherwise balances weekly pace. | **Override Model Router when usage is critical** is off by default. When enabled with Usage Balancing, it can restrict new tasks to a provider whose plan has at least 25% of its weekly allowance resetting within 48 hours, has 1.75 times the other plan's unused allowance relative to time remaining, or when the other plan is 90% used. Model Router chooses within that provider, or is skipped if only one model qualifies. Primary sessions still require an eligible strong or frontier model; otherwise mixed routing remains in charge. #### Background usage refresh **Refresh Claude usage in the background** requires a connected Claude usage source and consent. Refreshes use Claude Code's usage command and status line without sending a model prompt; Claude may retain normal session bookkeeping. With the app active, task activity can trigger checks at most once per **30 minutes**, with **12 checks per rolling day** for Claude, and at most once per **10 minutes** for Codex. There is no idle polling, and routing does not wait for a refresh. Connected usage also supports a startup check and manual refresh. ### Decision Services Each service card shows supported features, selection badges, and configuration status. Expand a card to review its credential controls and disclosures. Configuring a service does not automatically select it for both features; use each feature's **Decision service** menu. #### Choosing Decisions by OpenAI or Jev Both integrations can select a model for a new task or select effort for an eligible turn. They make a decision from RepoPrompt's supplied choices; they do not execute the coding task. You can choose one service for routing and another for Auto Effort. **Consider Decisions by OpenAI** when your team already manages OpenAI API projects and wants decision usage within that account structure. OpenAI documents typed choices, probabilities, and scores in its [Decisions guide](https://developers.openai.com/api/docs/guides/decisions). Check its [data-control documentation](https://developers.openai.com/api/docs/guides/your-data) against your account's requirements; documented service options do not mean this RepoPrompt integration enables them automatically. **Consider Jev** when you already use TypeSafe or want a separately managed decision service. TypeSafe describes Jev as designed for [typed decisions and calibrated confidence](https://typesafe.ai/). Its [System One API reference](https://docs.typesafe.ai/api/system-one) documents named questions and structured answers. That focus is a reason to evaluate Jev on your tasks, not proof it will choose better models than OpenAI. ##### Account setup - **Jev by TypeSafe:** TypeSafe API key; configure and verify it in the Jev card. - **Decisions by OpenAI:** OpenAI API key; the settings card recommends a dedicated project and project key for attribution. ##### Verification in RepoPrompt - **Jev by TypeSafe:** Checks account/model access without sending a task for evaluation. - **Decisions by OpenAI:** Sends a fixed test decision, which may incur an input-token charge. ##### Provider's API focus - **Jev by TypeSafe:** Named, typed questions over supplied state, with calibrated confidence as a stated design goal. - **Decisions by OpenAI:** Typed classification, choices, and scoring, including probability estimates. ##### Data handling - **Jev by TypeSafe:** TypeSafe's policy says it does not train or fine-tune models on submitted input; retention is governed separately by that policy. - **Decisions by OpenAI:** API input is not used to train models by default unless you opt in. Retention and additional data controls depend on the endpoint and account configuration. ##### What RepoPrompt uses - **Jev by TypeSafe:** The same text-based decision roles; the provider's additional question types are not separate settings here. - **Decisions by OpenAI:** Text-based choices for routing and effort; broader API capabilities do not automatically become app features. ##### Failure behavior - **Jev by TypeSafe:** The same deadline and fallback approach; choosing Jev does not remove RepoPrompt's eligibility checks. - **Decisions by OpenAI:** Five-second deadline without automatic retries; invalid or unavailable decisions fall back to the applicable selection. The account, verification, and app-behavior comparisons describe RepoPrompt's integrations. Provider capabilities come from the guides linked above. For TypeSafe's input-use and retention terms, read its [privacy policy](https://typesafe.ai/legal/privacy-policy); a no-training commitment is not a zero-retention commitment. For either service, compare actual decision quality, response time, and billed usage on representative tasks. Neither provider's general speed claims establish which is faster or cheaper for your workflow. Check current pricing and account terms before enabling automatic decisions. Keep the comparison fair by using the same candidates and guidance; local Usage Balancing can change the final execution choice after the service responds. #### Jev by TypeSafe Jev service card with Model Router and Auto Effort selection badges, API key controls, privacy disclosure, and technical limits Enter a **TypeSafe API key**, then choose **Validate & Save**. **Verify Saved Key** rechecks the stored credential; **Remove Key** removes it. Features depending on that credential need a valid configuration before they can make decisions. Jev chooses a model and initial effort for Model Router, or only effort for Auto Effort. Key verification checks account access without sending a task. Decision requests have a **five-second deadline** and are not retried automatically. Review the card's **Privacy and data sharing** and **Technical limits**, including its links to TypeSafe's privacy policy and API documentation. #### Decisions by OpenAI Decisions by OpenAI card with project-key and validation notices, credential controls, privacy and data controls, pricing, and technical limits Enter the **API key for Decisions by OpenAI** and choose **Validate & Save**. **Verify Saved Key** checks it again; **Remove Key** removes it. Validation sends a fixed test request, may incur a small input-token charge, and confirms access only at that time. The card recommends a dedicated OpenAI project and project key for attribution and project-level spending controls. A separate key is not a hard budget boundary, and organization limits can span projects. Another key can be used if you accept shared accounting. This service credential is separate from choosing the session's execution provider. Read the expanded disclosures before enabling the service: - **Privacy and data controls:** Routing sends limited task and guidance text with candidate descriptions, without appended repository or workspace payloads. Effort selection sends the selected model ID, effort choices, a masked message excerpt, and an applicable built-in workflow category. Leading-slash invocations, attachments, and tagged-file payloads remain ineligible under this service's prompt-workflow rules. Masking is not anonymization. Account and project configuration determine eligibility for regional processing, residency, and other data controls. - **Pricing:** Decisions API charges are set by OpenAI and can vary with context length or processing region. Use the card's current pricing link rather than assuming execution-plan allowance covers these requests. - **Technical limits:** The service uses an implementation-pinned decision model, with a **five-second deadline** and **64 KiB response cap**. Requests are not retried automatically. The model name in the screenshot describes that captured implementation, not a model you must select for coding. The card links to [Decisions documentation](https://developers.openai.com/api/docs/guides/decisions), [OpenAI data controls](https://developers.openai.com/api/docs/guides/your-data), and [API pricing](https://developers.openai.com/api/docs/pricing). Consult the [Models reference](https://repoprompt.com/docs/providers/models/) for the separate execution-model choices. --- ## Agent Models Agent Models workspace scope, recommendations, and Oracle roster; workspace names blurred Choose the Oracle analysis model, the Context Builder agent and model, and model defaults for sub-agent roles such as Pair, Design, Explore, and Engineer. Open **Settings → Agent Mode → Agent Models**. This page chooses the models used by Oracle, Context Builder, and MCP-launched agent roles. The model names and connected providers shown are examples, not fixed defaults. Use the [Models reference](https://repoprompt.com/docs/providers/models/#model-roles) for the meaning of these model roles and shared selection concepts, and the [provider directory](https://repoprompt.com/docs/providers/overview/) for connection requirements. The sections below explain settings scope and controls. ### Global settings and workspace overrides Agent Models scope selector and Copy to Workspace control With a workspace open, choose where edits apply: - **Use global settings**: this workspace inherits the global Agent Models profile, and changes below edit that profile. - **Use workspace overrides**: changes below apply to this workspace's profile. **Copy to Workspace** copies the current global profile and switches this workspace to overrides. When editing overrides, the corresponding **Copy to Global** action overwrites the global profile after confirmation, affecting other workspaces that inherit it. The scope chips at the top show the active profile and workspace. ### Recommended setup Recommended setup available banner and Apply Recommended Setup button Recommendations come from the same engine as the setup wizard. **Apply Recommended Setup** applies the recommended configuration to the scope you are editing. Individual rows can also offer **Apply** when their current choice differs. If everything matches, the page reports that the models are up to date. ### Oracle Models Primary Oracle and additional Oracle model pickers with Add Oracle and removal controls Choose a primary Oracle and up to **four additional models**. **Add Oracle** adds another entry; the minus control removes an additional entry. Grouped requests run each model independently and retain separate results in roster order. Set **Reconciliation guidance** for the calling agent when multiple answers return. The calling agent reconciles those answers; this does not launch another synthesis model. Saved guidance affects future requests, and blank guidance restores the default. The response-lane manifest and end marker remain fixed. For named configurations exposed to MCP clients, see [Oracle Model Presets](https://repoprompt.com/docs/settings/model-presets/). ### Re-prompt Re-prompt model, mode, recent-context option, rewrite guidance, and Save controls Re-prompt turns your draft message into a clearer task brief before sending it to the agent. Its settings follow the global or workspace scope selected at the top of this page. - **Model** selects the model that rewrites the draft. The default uses a fast model from a connected Claude or ChatGPT subscription. See [Providers & Models](https://repoprompt.com/docs/providers/models/) for model availability. - **Effort** is Low unless [Auto Effort](https://repoprompt.com/docs/settings/agent-decisions/#auto-effort) chooses the level. - **Mode → Review before sending** lets you inspect the rewritten draft before sending. **Send automatically** sends the completed rewrite without that review step. - **Include recent chat context** supplies recent conversation context to help interpret the draft. - **Rewrite guidance (advanced)** lets you customize the rewriting instructions. **Restore Default** loads the default guidance into the draft. Choose **Save** to store changes. Guidance must fit within **16 KiB**; an oversized draft is not truncated or saved. If settings or scope change while you edit, use **Reload Current Settings** before saving; this discards your draft. While reviewing a rewrite, press **Return** to send it, **Command+Return** to rewrite again, or **Shift+Command+O** to send the original text. These shortcuts can be changed in [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/#composer). ### Context Builder Agent Context Builder Agent provider and model menu Choose the CLI agent and model that discover files and build context for Oracle, plans, and reviews. If no suitable agent is connected, use **Connect in CLI Providers** first. Token budgets and prompt-enhancement behavior belong on [Context Builder](https://repoprompt.com/docs/settings/context-builder/). ### Sub-Agent Role Defaults MCP model discovery filter and Explore, Engineer, Pair, and Design role mappings These mappings supply models when an MCP client launches an agent using a role label: | Role | Intended work | | --- | --- | | **Explore** | Fast, read-only exploration and codebase mapping. | | **Engineer** | Balanced engineering and implementation work. | | **Pair** | Interactive pair programming with highest-tier models (default when `model_id` is omitted in `agent_run op="start"`). | | **Design** | Architecture, design critique, and creative problem solving (produces Markdown design/review documents under `docs/`). | Choose the provider/model from each row's menu. **Reset All to Recommended** appears when role defaults have overrides. **Hide non-role models from MCP agents** limits model discovery: `agent_manage` still exposes role labels and their mappings but omits the extra per-agent model catalog. Explicit compound model identifiers remain accepted. This is not an access-control boundary. [Model Router](https://repoprompt.com/docs/settings/agent-decisions/) can separately route eligible role-based starts. ### Advanced: synchronize built-in chat Advanced option to keep Built-in Chat Model synced with Oracle Model **Keep Built-in Chat Model synced with Oracle Model** makes choosing an Oracle update the built-in chat model to match. Turn it off to choose the chat model independently. This does not make the chat model the same thing as a sub-agent role mapping. ### Related settings Oracle Model Presets settings link Use [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/) for connections, [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/) for execution permissions, and [Oracle Model Presets](https://repoprompt.com/docs/settings/model-presets/) for named MCP Oracle configurations. --- ## Agent Permissions Direct Agents tab showing connected provider summaries and unavailable providers Configure permissions for agents launched directly from RepoPrompt and the separate policy for sub-agents launched through MCP. Sub-agent policy can use Safe Managed behavior, inherit direct-agent settings, or use custom settings. Open **Settings → Agent Mode → Agent Permissions**. The page has two tabs with separate responsibilities: **Direct Agents** and **Sub-Agents**. Model selection remains in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). Direct Agents and Sub-Agents tab selector ### Direct Agents This tab configures provider-native permissions for agents you launch directly from RepoPrompt. Expand a connected provider row to change its permission level and, where supported, **Tools & Runtime Options**. Connection indicators and summary values describe your current setup. A green indicator means the provider is available; it does not mean it has unrestricted access. #### Codex CLI Codex CLI direct-agent sandbox and third-party MCP summary The row summarizes the sandbox and third-party MCP policy. Expand it for Codex permission levels and runtime tool controls. Third-party MCP servers are controlled individually and are off by default; that control is separate from the RepoPrompt MCP tool list. #### Claude Code Claude Code direct-agent permission mode and third-party MCP summary The summary shows the selected Claude permission mode and MCP scope. Expand it to configure Claude's provider permissions and tool/runtime settings. **Auto-approve Edits** and **RepoPrompt only** are the selections pictured, not a recommendation to enable broader access. #### OpenCode and Google Antigravity OpenCode direct-agent ACP session mode and MCP support summary Google Antigravity direct-agent ACP mode and MCP management summary These rows expose each provider's ACP session mode. The provider's capabilities determine which permission and tool controls are available. The screenshot reports no third-party MCP support for OpenCode and provider-managed MCP for Antigravity; do not assume the same MCP controls apply to both. #### Disconnected providers Disconnected Cursor CLI, Grok Build, and Devin CLI rows and Open CLI Providers button Unavailable providers are listed under **Not connected** and cannot be expanded for editing. **Open CLI Providers** opens connection setup. A provider moves into the connected list when it becomes available. ### Sub-Agents
View the complete Sub-Agents tab Agent Permissions Sub-Agents tab showing policy selection, Safe Managed preview, effective profiles, and related settings
Sub-agent sandbox policy selector with Safe Managed, Inherit Provider, and Custom This policy applies when another agent launches a sub-agent through MCP: | Policy | Behavior | | --- | --- | | **Safe Managed** | Applies RepoPrompt's managed provider profiles instead of the direct-agent settings. | | **Inherit Provider** | Uses the direct-agent provider settings, including permissive modes you enabled there. | | **Custom** | Uses independent per-provider sub-agent permission levels. | Custom mode exposes **Per-provider sub-agent modes**. These affect future sub-agent launches without changing Direct Agents settings. Inherit Provider can pass through Full Access; review direct-agent settings before choosing it. #### Preview Safe Managed profile Expanded Safe Managed policy preview The preview explains the policy and shows an effective profile for each available provider. Safe Managed disables Claude Bash, forces Claude to strict MCP, and suppresses user-enabled third-party MCP servers for Codex. Codex Bash remains enabled under its managed Auto Review workspace sandbox. Grok Build uses its Default mode for MCP launches. Its own rules, including inherited Claude Code permission rules, can allow requests without asking RepoPrompt. Safe Managed therefore does not guarantee an approval prompt for every provider action. #### Effective per-provider profile Safe Managed profiles for connected providers and unavailable-provider indicators Read these summaries for the connected providers. They show the resulting sandbox or permission mode and third-party MCP handling. The rows are a preview of policy, not a second set of editable Direct Agents settings. ### Overseer Overseer full access switch and explanation of its session-wide permissions **Overseer full access (no approvals)** grants an Overseer access to every session without approval or confirmation cards. It can observe, organize, control, restructure, spawn, manage worktrees, retire, and delete sessions. The switch is off by default and appears on both permission tabs. Review its access in **Active delegations**. Turn the switch off to revoke this standing access immediately. This is a separate, app-wide grant; the Direct Agents and Sub-Agents settings above do not limit it. Only you can change this switch in the UI; it is not exposed through the MCP App Settings tool. ### Related settings and storage Links to CLI Providers, Workspace Approvals, MCP Tools, Agent Models, and Agent Mode Overview - [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/) configures connections and other runtime options. - [Workspace Approvals](https://repoprompt.com/docs/settings/workspace-approvals/) controls requests that change RepoPrompt workspace records. - [MCP Tools](https://repoprompt.com/docs/settings/tools/) controls tool availability. - [Agent Mode Overview](https://repoprompt.com/docs/settings/overview/) summarizes the wider setup. Both tabs share secure-permission storage diagnostics. If a degraded-storage banner appears, check it before assuming a permission change was saved; failed writes can return to the effective stored value. --- ## Agent Workflows Agent Workflows settings with cleanup guidance, featured workflows, built-in visibility, and custom workflow controls Manage the built-in workflows shown in Agent Mode, featured workflows, custom Markdown workflows, and cleanup guidance included with workflows. Open **Settings → Agent Mode → Agent Workflows**. These are Agent Mode prompt templates, separate from [Copy/Chat Workflow Presets](https://repoprompt.com/docs/settings/workflow-presets/). Select a workflow in Agent Mode before sending a task. ### Prompt Behavior Include Session Cleanup Guidance switch **Include Session Cleanup Guidance** controls housekeeping instructions appended to built-in workflow templates, reminding the coding agent to dismiss completed sessions. Turn it off if that text conflicts with your session-management process. It does not change custom workflow templates or separately installed external workflow instructions, and it does not immediately dismiss sessions itself. ### Featured Workflows Featured workflow list with Add Featured Workflow, ordering arrows, and Remove Up to **four** workflows appear first in Agent Mode. **Add Featured Workflow** chooses from eligible workflows; it is disabled when the list is full or there are no more available choices. Use the up and down arrows to reorder this list. **Remove** removes a workflow from the featured list without deleting the workflow. The full visible catalog remains available in the workflow picker. ### Built-in Workflows Built-in workflow rows with Visible, Feature, and Clone controls The built-in catalog includes: | Workflow | Purpose | | --- | --- | | **Orchestrate** | Break work into smaller tasks, delegate, and check results. | | **Deep Plan** | Research the code and produce an implementation plan. | | **Optimize** | Measure, add metrics, and iterate on improvements. | | **Plan & Build** | Plan and implement a change step by step. | | **Review** | Look for bugs, regressions, risks, and missed cases. | | **Refactor** | Improve structure while preserving behavior. | | **Investigate** | Investigate problems or research questions and report evidence. | | **ChatGPT Export** | Prepare code and context for a prompt to use in ChatGPT. | **Visible** shows or hides a built-in workflow in the picker. Hiding it also removes it from Featured Workflows. **Feature** adds a visible workflow to the featured list, subject to the four-item limit. **Clone** creates an editable custom Markdown copy; it does not modify the shipped template. ### Custom Workflows Custom Workflows section with New, Reload, and Open Folder controls Choose **New**, enter a name, and select **Create** to create a Markdown workflow. Alternatively, clone a built-in and edit the resulting file. **Open Folder** opens the Workflows folder. You can add `.md` files there directly; **Reload** refreshes the catalog after external changes. Files can include optional frontmatter for a name, icon, accent color, tooltip, or description; otherwise the filename supplies the display name. Custom rows provide their own management actions. Deleting a custom workflow asks for confirmation and removes its file from the Workflows folder; it cannot be undone from RepoPrompt. --- ## CLI Providers CLI Providers overview showing runtime and compatible-backend cards Connect coding-agent runtimes and configure their authentication, permissions, tools, and compatible backends. Open **Settings → Agent Mode → CLI Providers**. Expand a provider’s row to see its available controls. The information button opens the provider’s website or documentation. Controls change with runtime availability and connection state. Screenshots illustrate the controls; the selections shown are examples rather than recommended defaults. ### Connection and setup controls **Connect** checks whether RepoPrompt can use a provider. For providers with an established connection, **Test Connection** checks it again. Errors appear in the provider card or a result dialog. Where available, **Save Trace to Downloads** exports a diagnostic trace after a failed test. Status badges distinguish connection or installation availability from backend configuration. Compatible backends may be **Off**, need an **API key**, or be **Ready**; use **Test Backend** to check the configured route rather than treating readiness as a successful request. The **Check Now** banner opens setup recommendations when the app has connected CLI providers. It is separate from the individual connection tests. :::note[Direct agents and sub-agents] The inline **Permissions** or **Permissions & Runtime** controls apply to agents launched directly from RepoPrompt. **Open Agent Permissions** takes you to [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/), where MCP-launched sub-agent policy is configured separately. ::: ### Plan usage **Plan usage** controls appear inside the connected Codex CLI and Claude Code CLI cards. Usage-source setup is separate from connecting the coding runtime. The **Show usage limits when available** preference in [Agent Mode Overview](https://repoprompt.com/docs/settings/overview/) controls visibility; the provider's source must also be enabled or connected before readings are available. Use **Refresh** to request an updated reading. These controls report account usage; [Usage balancing](https://repoprompt.com/docs/settings/agent-decisions/#usage-balancing) separately controls whether it influences model selection. ### Codex CLI Provider reference: [Codex CLI](https://repoprompt.com/docs/providers/codex-cli/). Codex CLI settings panel with runtime, sign-in, permissions, tools, optional features, and MCP server controls; account value removed RepoPrompt uses a managed Codex runtime and a managed sign-in separate from your ordinary `~/.codex` sign-in. #### Runtime and sign-in ChatGPT may require identity verification (KYC) before Codex access is available. - **Included with RepoPrompt** shows the bundled runtime’s version and availability. The active-runtime summary identifies what this app launch is using. - Under **Advanced**, open the runtime menu and select a detected executable, or choose **Choose…** to select a custom Codex executable. RepoPrompt checks its version and reports availability or compatibility problems. - In the same runtime menu, select **Included Codex [version]** to switch the pending choice back to the bundled runtime. - **Connect** checks the selected runtime’s connection. When sign-in is needed, use **Login with ChatGPT** or **Use device code instead**. The device-code flow provides **Copy code** and **Open verification page**; keep the panel open while completing the browser step. - After authentication, the account summary shows account, plan, and authentication information. **Test Connection** checks the integration again. - **Sign Out** requires confirmation to stop Codex sessions and sign out of the managed account. :::note[Runtime changes require relaunch] Runtime selection takes effect on the next RepoPrompt launch, when the model list is refreshed. Saved model choices are preserved. Custom executables are not managed or verified by RepoPrompt and may be incompatible with its integration; the version check does not guarantee full compatibility. ::: #### Permission Level - **Read Only** uses a read-only sandbox with approvals requested when needed. - **Default** allows workspace writes and asks you for approvals when needed. - **Auto Review** allows workspace writes and uses automatic review of tool requests before asking you. - **Full Access** removes the sandbox restriction and runs without approval prompts. #### Core tools and runtime features Each switch enables or disables the named capability: - **Bash** permits Codex shell commands within the selected permission level. - **Search** permits built-in project search while Codex works. - **Goals** enables Codex goal support for tasks that continue between turns. - **Reasoning Summaries** shows Codex reasoning summaries in Agent Mode. It does not change model reasoning effort or Chat/Oracle behavior. - **Local Memories** permits Codex to generate and reuse local memories across Agent Mode chats. Memories are stored under the runtime’s Codex home. Generation can perform background or startup model work and consume Codex quota; applying the change may require a new or restarted session. #### Import user Codex MCP servers Import user Codex MCP servers control with server names blurred RepoPrompt's managed Codex sign-in and configuration are separate from your standalone Codex setup. **Import user Codex MCP servers…** reviews servers from your user Codex configuration for import; they are not shared with Agent Mode automatically. The summary lists servers available to import. Review the requested servers before importing them, then control their availability in **MCP servers**. #### Optional Codex Features Optional Codex features, including Computer Use and connected-app controls - **Computer Use** enables `/computer-use` in direct Codex sessions. It requires the Computer Use companion and an OpenAI-signed Codex executable, plus macOS Screen Recording and Accessibility permissions when requested. A re-signed runtime can fail companion authentication; select a compatible local runtime under **Codex CLI → Advanced** and restart the session if needed. This option is off by default. - **Apps** permits use of connected apps. - **Plugins** permits loading installed plugins. - **MCP Elicitation** permits MCP servers to request additional input during a run. - **Tool Suggestions** permits suggestions to install or enable apps and plugins. Under **MCP servers**, toggle the configured servers that Codex may use. **RepoPromptCE** is required for the integration and cannot be disabled here. This list is read from RepoPrompt’s isolated Codex configuration. ### Claude Code CLI Provider reference: [Claude Code CLI](https://repoprompt.com/docs/providers/claude-code-cli/). Claude Code CLI settings panel with connection buttons, permission level, tool switches, and Advanced disclosure Claude Code uses the installed `claude` command and its login for Anthropic models. Complete its terminal login if necessary, then select **Connect**: ```sh claude login ``` **Test Connection** rechecks access. **Sign Out** clears RepoPrompt’s recorded Claude connection state; it is not a replacement for logging out of the standalone CLI. #### Permission Level - **Require Approval** asks before running tools. - **Auto-approve Edits** automatically approves file edits and common filesystem commands. - **Auto (Preview)** approves tool calls that pass background safety checks. The provider treats this as a preview feature. - **Full Access** runs tools without approval prompts. #### Claude Tools - **Bash** enables or disables Claude’s shell tool. - **RepoPrompt Only (Strict MCP)** restricts the session to RepoPrompt’s MCP server when enabled. When disabled, MCP servers from the Claude configuration may also be loaded. - **Lazy Tool Loading** lets Claude search for tools as needed, reducing context use but adding discovery latency. With it disabled, tools are preloaded into context. Changes to Claude tool settings apply to the next Claude turn. #### Advanced: Sys Prompt Packaging Expand **Advanced** inside the Claude Code CLI card to reveal **Sys Prompt Packaging**. This menu controls where RepoPrompt places its Agent Mode instructions and whether Claude Code keeps its native system prompt. An explanation below the menu updates to describe the selected mode: - **User Message (Keep Native)** puts RepoPrompt instructions in the user message and retains Claude Code’s native system prompt. - **User Message (No Native)** puts RepoPrompt instructions in the user message and removes the native system prompt. - **Replace System Prompt** uses RepoPrompt instructions in place of Claude Code’s native system prompt. The choice is saved when you select it; there is no separate Save button. With no saved preference or legacy override, RepoPrompt uses **Replace System Prompt**. This setting controls instruction delivery, while **Permission Level** and **Claude Tools** control tool access. ### OpenCode CLI Provider reference: [OpenCode CLI](https://repoprompt.com/docs/providers/opencode-cli/). OpenCode CLI panel with connection test, sign-out button, and ACP session mode Authenticate the installed OpenCode CLI, then select **Connect**: ```sh opencode auth login ``` - **Test Connection** rechecks the integration. A summary reports discovered models; discovery can refresh in the background. - **Sign Out** clears the connection and cached model availability in RepoPrompt. Manage the standalone CLI’s credentials through OpenCode. - **ACP Session Mode → Default** asks before running tools that need approval. - **ACP Session Mode → Full Access** runs available tools without approval prompts. Interactive Agent Mode uses OpenCode’s Agent Client Protocol (ACP) runtime. Headless OpenCode runs use a managed mode without native tools. ### Cursor CLI Provider reference: [Cursor CLI](https://repoprompt.com/docs/providers/cursor-cli/). Collapsed Cursor CLI provider card with its expansion control **Connect** checks the installed Cursor runtime. Complete Cursor login when prompted, or provide the credentials supported by that runtime, such as `CURSOR_API_KEY` or `CURSOR_AUTH_TOKEN`. - **Test Connection** rechecks access. - **Refresh Models** requests an updated list from the runtime. - **Sign Out** disconnects Cursor in RepoPrompt and clears its cached model availability. - **ACP Auto-Approve → Default** asks before running tools requiring approval. - **ACP Auto-Approve → Full Access** makes RepoPrompt automatically approve Cursor ACP tool-permission requests. RepoPrompt supplies its MCP integration through the ACP session. The provider’s **Auto** model option lets Cursor choose the model. ### Grok Build Provider reference: [Grok Build](https://repoprompt.com/docs/providers/grok-build/). Collapsed Grok Build provider card with its expansion control **Connect** checks the installed Grok runtime. Authenticate with `grok login` or configure a Grok API key in API Providers. ```sh grok login ``` - **Test Connection** rechecks access and reports discovered models. - **Sign Out** disconnects Grok Build in RepoPrompt and clears cached model availability. - **Always-Approve Launch → Default** leaves Grok’s approval prompts enabled. - **Always-Approve Launch → Full Access** launches Grok with `--always-approve`, allowing its shell and editing tools to run without per-request confirmation. The launch setting applies to newly started Grok processes. ### Google Antigravity Provider reference: [Google Antigravity](https://repoprompt.com/docs/providers/google-antigravity/). Google Antigravity panel with Update Runtime and Test Connection buttons - **Install Runtime** installs RepoPrompt’s managed Antigravity ACP runtime. - **Update Runtime** updates an installed runtime. - **Test Connection** checks runtime support and refreshes model discovery. It is available after installation. Google authentication is requested through ACP when needed. The card’s availability indicator reflects runtime installation; it does not by itself establish that Google login is complete or that selectable models were returned. This card does not include its own sign-out or inline permission picker. ### Devin CLI Provider reference: [Devin CLI](https://repoprompt.com/docs/providers/devin-cli/). Collapsed Devin CLI provider card with its expansion control Install and authenticate Devin so the `devin acp` runtime is available. Devin manages its own authentication and internal tools. The card’s availability indicator reflects whether the runtime is installed. **Refresh Models** requests the model list. **Permission Mode** controls newly started Devin processes: - **Provider Default** passes no permission flag and uses Devin’s own configured default. - **Normal** automatically approves read-only tools and asks before actions requiring approval (`auto`). - **Accept Edits** also automatically accepts workspace edits (`accept-edits`). - **Smart** additionally runs actions judged safe by a fast model (`smart`). - **Full Approval** runs tools without approval prompts (`dangerous`). This integration does not offer Devin’s autonomous mode. Use Devin’s own authentication tools to manage its login. ### Claude Code–Compatible Backends These backends reuse the installed `claude` executable with their own endpoint and credentials. They do not require an Anthropic Claude account login. The prerequisite row explains whether the Claude executable is available and offers a connection or installation action when needed. **Test Backend** sends a minimal message using the same backend environment overrides as Agent Mode. Enable and configure the backend, save a credential, and make sure the Claude executable is available before testing. The result appears in the card. Saving display, endpoint, authentication-mode, or model-mapping changes updates the backend configuration; credential fields use their separate **Save** or **Change** action. #### CC Zai Provider reference: [CC Zai](https://repoprompt.com/docs/providers/cc-zai/). CC Zai backend panel with credential controls, model-slot mappings, backend test, and Advanced disclosure; saved key field cleared CC Zai routes Claude Code through Z.ai’s Anthropic-compatible endpoint. - **Z.ai API Key** accepts the backend credential. **Save** or **Change** stores it; **Delete** removes it. - **Claude slot → Backend model ID** maps the **Haiku**, **Sonnet**, and **Opus** slots to backend model identifiers. Fill all three slots. RepoPrompt passes the selected slot to Claude and supplies the mappings through environment variables. - **Reset to GLM defaults** restores the backend preset, including its standard slot mappings. - **View Z.ai plans** opens the provider’s coding-plan information. :::note[Shared Z.ai credential] This field uses the same saved secret as Z.AI in [API Providers](https://repoprompt.com/docs/settings/api-providers/). Changing or deleting it here also changes that API-provider credential. ::: ##### Advanced Expand **Advanced** inside the CC Zai card to edit the preset’s connection settings: - **Display name** changes the backend’s label in RepoPrompt, including its card title. A blank name falls back to **CC Zai**. - **Base URL** sets the Anthropic-compatible endpoint. The preset is `https://api.z.ai/api/anthropic`. The address must include an `http` or `https` scheme and a host to be valid. - **Auth header** chooses how the saved credential is supplied to Claude Code: **ANTHROPIC_API_KEY** or **ANTHROPIC_AUTH_TOKEN**. CC Zai defaults to **ANTHROPIC_AUTH_TOKEN**. Choose the option expected by the endpoint; this menu does not enter or replace the saved key. - **Reset to defaults** restores the entire CC Zai preset, including its display name, endpoint, authentication choice, enabled state, and model-slot mappings. Inspect the restored fields for the exact model IDs supplied by your app version; see [model-slot mappings](https://repoprompt.com/docs/providers/cc-zai/#model-slot-mappings) for their meaning. Name, URL, and authentication changes are saved as you edit them. They clear the previous backend test result; use **Test Backend** to check the new configuration. Resetting keeps the saved Z.ai credential. Use the credential’s **Delete** button to remove it. #### CC Moonshot Provider reference: [CC Moonshot](https://repoprompt.com/docs/providers/cc-moonshot/). CC Moonshot backend panel with API key controls, model behavior, backend test, and Advanced disclosure CC Moonshot routes Claude Code through Kimi’s coding backend. - **API Key** accepts the Kimi credential. **Save** or **Change** stores it; **Delete** removes it. The key information button opens the Kimi Code console. - **View Kimi plans** opens the provider’s coding-plan information. - **Test Backend** checks the configured Kimi route. Kimi manages model selection. RepoPrompt sends neither a `--model` flag nor a Claude Code effort level for this backend. ##### Advanced Expand **Advanced** inside the CC Moonshot card to edit its connection settings: - **Display name** changes the backend’s label in RepoPrompt, including its card title. A blank name falls back to **CC Moonshot**. - **Base URL** sets the Kimi coding endpoint. The preset is `https://api.kimi.com/coding/`. The address must include an `http` or `https` scheme and a host to be valid. - **Auth header** offers **ANTHROPIC_API_KEY** and **ANTHROPIC_AUTH_TOKEN**, selecting the environment variable through which Claude Code receives the saved credential. CC Moonshot defaults to **ANTHROPIC_API_KEY**. Changing this choice does not replace the saved key. - **Reset to defaults** restores the entire CC Moonshot preset: its name, endpoint, authentication choice, enabled state, and backend-managed model selection with no `--model` flag. Name, URL, and authentication changes are saved as you edit them and clear the previous backend test result. Run **Test Backend** again to check them. Resetting keeps the saved Kimi credential; use the credential’s **Delete** button to remove it. #### CC Custom Provider reference: [CC Custom](https://repoprompt.com/docs/providers/cc-custom/). CC Custom backend panel with enable switch, display name, endpoint, authentication, model behavior, and backend test Use CC Custom for your own Claude-compatible endpoint: Custom backend request timeout and context-window settings - **Enable custom backend** controls whether the configured backend is active. - **Display name** sets its label in the app. - **Base URL** identifies the compatible endpoint. - **Request timeout (milliseconds)** sets the timeout for new launches. The default is **600000 ms (10 minutes)**. Enter milliseconds, not seconds; leave it blank to use the default. - **Context window (tokens)** sets the window for unrecognized model IDs on new launches. The default is **200000 tokens**, shared by all three model slots. IDs with `[1m]`, bare `claude-` names, and recognized Claude models follow Claude Code's own window rules. Leave it blank to use the default. - **Auth header** chooses **ANTHROPIC_API_KEY** or **ANTHROPIC_AUTH_TOKEN**, the environment variable through which the Claude process receives the credential. - **API Key** or **Auth Token** accepts that credential. **Save** or **Change** stores it; **Delete** removes it. - **Model behavior → No model flag** leaves model selection to the backend. RepoPrompt sends no Claude slot or Claude Code effort level. - **Model behavior → Claude slot mappings** exposes **Haiku**, **Sonnet**, and **Opus** model-ID fields. All three must be filled before the backend can launch. **Reset custom backend** restores the custom backend preset. - **Test Backend** checks the enabled, configured endpoint. :::caution[Approval-free modes] Full Access, Grok’s always-approve launch, and Devin’s Full Approval allow actions without individual confirmation. Codex Full Access also permits writes outside the workspace sandbox. Use these modes only where that access is intended. Sub-agent policy remains separately controlled in [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/). ::: --- ## Context Builder (Agent-mode) Context Builder settings showing shared budgets, enhancement, question timeout, and separate UI and MCP run options Configure context and analysis token budgets, prompt enhancement, question timeouts, and clarifying-question behavior. This page also manages custom instructions and distinguishes runs started in the interface from runs requested through MCP. Open **Settings → Agent Mode → Context Builder**. Shared settings apply to context building from the interface and MCP, while each run type has its own clarifying-question switch. Screenshot selections are examples, not all factory defaults. ### Context Builder Agent About Context Builder and the Context Builder Agent settings link The **Context Builder Agent** row shows the current CLI agent and model. Open it to change those choices in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). This page controls context-building behavior rather than model selection. ### Context Budget Context Budget slider and target-size explanation Sets the target size of the selected context package for context-only runs, such as preparing a web export. The slider spans **10,000–200,000 tokens** in **5,000-token steps**; the default is **160,000**. A lower target can produce a smaller package. This is a context-selection budget, not an output-token limit or a guarantee about a model's supported context window. ### Analysis Budget Analysis Budget slider for immediate plan, review, or answer generation Sets the context-package target when Context Builder will immediately produce a plan, review, or answer. The range is **40,000–200,000 tokens**, in **5,000-token steps**. The default is **120,000**, even though this capture shows **200k**. ### Prompt Enhancement Rewrite, Augment, and Preserve prompt-enhancement choices | Mode | Result | | --- | --- | | **Rewrite** | Rewrites the prompt while building context; the default mode. | | **Augment** | Keeps your instructions and appends relevant context. | | **Preserve** | Updates file selection while leaving instructions unchanged. | ### Question Timeout Question Timeout choices of 30 seconds, one minute, two minutes, and five minutes Choose **30 seconds**, **1 minute**, **2 minutes**, or **5 minutes**. This is how long the agent waits for your answer before continuing on its own; it applies to clarifying questions and Agent Mode `ask_user`. It is not the total Context Builder run timeout. ### UI Runs: clarifying questions UI Runs Allow Clarifying Questions switch For runs started with **Run** in the Context Builder panel, **Allow Clarifying Questions** lets the agent ask you for more information. It is on by default. The description reflects the selected Question Timeout. Turning this UI setting off also clears the MCP clarifying-question setting. Re-enabling UI questions does not automatically opt MCP runs back in. ### UI Runs: follow-up analysis Follow-up Analysis switch **Follow-up Analysis** automatically runs the current tab's selected plan, review, or question after context building completes. It is off by default, though it is enabled in the capture. The follow-up type is selected per tab. ### Custom Instructions Custom Instructions manager button and per-tab selection explanation **Add**, or the saved-prompt count, opens the custom-instructions manager. Choose **New**, enter a title and instructions, then **Save**; the same manager edits existing prompts. The settings page previews up to three saved titles. Saving a prompt here does not select it for every run. Select the instructions to use in the Context Builder panel for the current tab. ### MCP Runs MCP Runs Allow Clarifying Questions switch The MCP **Allow Clarifying Questions** switch is separate and off by default. Enable it when you intend to watch RepoPrompt and answer questions from an external client's `context_builder` request. Questions use the shared timeout and remain disabled for inactive target workspaces. MCP callers choose their requested response type through the tool. The UI-only Follow-up Analysis switch does not replace that request. See [MCP Tools](https://repoprompt.com/docs/settings/tools/#context_builder) for the tool overview. --- ## Overview Overview model links, supervision, provider status, usage display, and cleanup controls Configure Agent Mode behavior and find the settings for models, providers, permissions, and context building. Open **Settings → Agent Mode → Overview**. This page combines shortcuts to detailed configuration with a few app-wide behavior controls. Screenshots illustrate the controls; the selections shown are examples rather than recommended defaults. ### Models and context - **Oracle Model** opens [Agent Models](https://repoprompt.com/docs/settings/agent-models/). Oracle analyzes the current file selection and chat history for planning and review, without tools or file edits. Change its model on the linked page. - **Context Builder Agent** also opens [Agent Models](https://repoprompt.com/docs/settings/agent-models/). Choose the agent and model that explore the repository and gather relevant files for Oracle. - **Sub-Agent Role Defaults** opens [Agent Models](https://repoprompt.com/docs/settings/agent-models/). Assign models to orchestration roles: **Pair** for primary work, **Design** for interface and copy work, **Explore** for investigation, and **Engineer** for implementation. The model names shown on Overview summarize your configuration. They are navigation links, not model pickers. ### Sub-Agent Supervision Sub-Agent Supervision panel with the default wait menu and its explanation **Default subagent wait** sets how long an orchestrating agent normally waits for a sub-agent before checking back. The available intervals are **2, 5, 10, 20, 30, and 60 minutes**. Shorter waits allow more frequent progress checks; longer waits reduce routine model calls. Completion, questions, or your steering can end a wait early. An agent can request a different wait for an individual task, so this is a default supervision interval rather than a task time limit. ### CLI Providers CLI Providers summary with provider connection indicators Open [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/) to connect runtimes, manage authentication, test connections, and configure provider controls. Overview summarizes the connection state for Codex CLI, Claude Code, OpenCode, Cursor CLI, Grok Build, Google Antigravity, and Devin CLI. These indicators summarize the connection information already held by the app. Use **Test Connection** on the provider page to check availability again. ### Usage Limits Usage Limits switch and link to provider usage sources **Show usage limits when available** displays provider plan usage in Settings and a compact indicator in Agent Mode. Enable each usage source in [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/). This display is read-only: it does not choose models or enable usage balancing. Configure routing separately in [Agent Decisions](https://repoprompt.com/docs/settings/agent-decisions/). ### Provider Conversation Cleanup Provider Conversation Cleanup panel with Archive and Delete choices **Cleanup action** controls what RepoPrompt requests from a supported provider when you delete an Agent Mode session: - **Archive** requests archiving of the provider conversation. - **Delete** requests deletion of the provider conversation. Local session cleanup continues if the provider does not support conversation cleanup. Selecting an action does not immediately archive or delete existing sessions. :::caution[Provider-side cleanup] Deleting an Agent Mode session can also affect its provider conversation. Choose the cleanup action before removing sessions; support for the requested action depends on the provider. ::: ### Provider environment filtering (opt-in) Environment variable withholding list, provider-specific exceptions, Apply, and Reload Use this section to withhold selected ambient environment variables from newly launched provider processes. Leave both lists empty to preserve the existing authentication and toolchain environment. 1. Enter **variable names** in **Withhold ambient names for all providers**, separated by commas or spaces. Names are exact and case-sensitive; do not enter values or wildcards. 2. Choose a provider under **Pass-through exceptions for** and enter any withheld names that provider still needs. 3. Choose **Apply** to save. **Reload** discards the draft and reads the saved lists again. Apply or reload an edited exception list before switching providers. Filtering applies to new provider processes, including probes and headless launches. It does not alter running sessions or interactive user terminals, and intentional app/runtime overrides remain available. Withholding a required variable can break authentication or tools; add a provider exception when needed. This is a partial mitigation. It does not restrict credential files, shell profiles, installation or provisioning identity checks, or other capabilities available to the same user. If the lists change elsewhere while you edit, reload them before applying. ### Require Codex project-hook approval Codex project-hook approval switch and workspace override menu The app-wide **Require Codex project-hook approval** switch determines whether Codex may begin without approval of the displayed project hooks. When approval is required, **Continue Without Hooks** is unavailable. The first Codex turn remains blocked until those hooks are approved or become trusted externally. Turning off the requirement permits the continue-without-hooks path; it does not itself approve or trust hooks. When a workspace is available, **In this workspace** can override the app-wide setting: - **App default** follows the app-wide switch. - **Always require approval** requires hook approval in this workspace. - **Don't require approval** allows this workspace to use the continue-without-hooks path. ### Handoff Instructions Handoff Instructions editor, character count, Save, and Clear Saved Instructions controls Enter reusable instructions that the titlebar’s **Handoff** action appends to a handoff. The saved text applies across the app. - The editor accepts up to **20,000 characters** and displays a character count. - **Save** stores a changed, valid draft. Text that exceeds the limit must be shortened before saving. - **Clear Saved Instructions** removes the saved text and clears the editor. For example, you could save: ```text Summarize the task, decisions, changed files, and validation results. List the remaining work and any unresolved questions. ``` :::note[Saving and concurrent changes] If the saved instructions change elsewhere while you have an edited draft, the page warns that saving will replace the newer value. If global settings cannot be saved, a separate warning explains that changes are active only for the current launch until persistence is restored. ::: ### Agent Permissions Agent Permissions links for direct agents and sub-agents These links open [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/): - **Direct Agents** configures provider controls for agents you launch directly, such as Claude Bash access, Codex sandbox permissions, ACP session modes, and MCP restrictions. - **Sub-Agents** configures the policy for agents launched through MCP. The displayed policy name summarizes the current setting. Safe Managed applies managed overrides; other policy choices are configured on the linked page. :::note[Two permission scopes] Direct-agent controls and sub-agent policy are separate. Changing a provider control does not mean every MCP-launched sub-agent will use that same setting. ::: ### Context Builder Budgets & Timeouts Context Builder Budgets and Timeouts settings link **Context Builder Budgets & Timeouts** opens [Context Builder](https://repoprompt.com/docs/settings/context-builder/), which owns token budgets, prompt enhancement, question timeouts, and clarifying-question behavior. ### Agent Workflows Agent Workflows settings link and cleanup guidance summary Open [Agent Workflows](https://repoprompt.com/docs/settings/agent-workflows/) to manage built-in workflow visibility, featured workflows, custom Markdown workflows, and cleanup guidance. Overview displays a summary; change the workflow options on their own page. ### Agent Chats Agent Chats panel with Show chats created by MCP tools switch **Show chats created by MCP tools** controls whether the chat list includes Compose tabs created through MCP before an agent has run in them. Enable it to inspect and adjust those tabs’ selections, prompts, and Context Builder runs in Compose. Disable it to omit those not-yet-run chats from this view. The switch changes visibility; it does not delete the chats. --- ## Advanced Full Advanced pane showing filesystem, AI behavior, history, shortcuts, URL opener, and saved prompts Configure workspace folder scanning, ignore rules, symbolic links, Code Maps, prompt packaging, history time tracking, keyboard-shortcut availability, URL opening, and saved-prompt utilities. Open **Settings → General → Advanced**. The screenshot shows example values. These controls combine app-wide preferences with prompt-editor options and one-time utilities. ### Workspace Folder Scanning Folder scanning controls for ignore files, symbolic links, and empty folders Changes refresh open folders and use the same preferences as the `app_settings` MCP tool. | Control | Effect | | --- | --- | | **Respect .repo_ignore rules** | Honors RepoPrompt-specific ignore files. Edit their contents in the Ignore Patterns editor or with file-editing tools. | | **Respect .cursorignore rules** | Honors `.cursorignore` files during scans. | | **Respect nested ignore files** | Reads ignore files in nested directories as well as the workspace root. | | **Follow symbolic links** | Follows symbolic links while scanning directories. | | **Show empty folders** | Includes empty folders in workspace folder listings. | These switches control scanning behavior; they do not edit your ignore files. ### Code Maps Global Code Maps disable switch and non-Git folder scanning option **Disable Code Maps globally** stops Code Map scanning and prompt inclusion, cancels active scans, and temporarily ignores saved workspace Copy and Chat Code Map modes. Those modes are preserved and take effect again when you turn the global disable switch off. **Enable Code Maps in non-Git folders** permits background Code Map scanning for plain folders. It is off by default for existing workspaces. It does not override a global Code Maps disable setting. ### Prompt Packaging Full and Relative file path choices and instruction timestamp checkbox **Full** and **Relative** choose how file paths appear in packaged prompts. **Include datetime in user instructions** adds a timestamp attribute to the user-instruction tags. These controls affect copied prompts and built-in chat instructions; they do not rename files. ### History time tracking Default idle threshold slider for history time tracking **Default idle threshold** controls the `history` MCP tool's active-work calculation. Gaps between agent turns longer than the threshold count as idle rather than active work. The range is **0–60 minutes**, in one-minute steps; the default is **10 minutes**. Lower values count only more tightly spaced work, while higher values include short breaks. A query can override the setting with `idle_threshold_minutes`. This changes the calculation, not the underlying session history. ### Keyboard Shortcuts Keyboard shortcuts master switch and Open Keyboard Shortcuts button **Enable keyboard shortcuts** is the same master switch used on the [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/) page. Turning it off leaves custom bindings saved. **Open Keyboard Shortcuts…** opens the complete binding editor for this window. ### URL Opener URL Opener examples for folders, file selection, ephemeral workspaces, and saved prompts Use the **`repoprompt-ce://`** scheme for links from external tools. The page's **Copy** buttons copy examples so you can replace the sample paths and URL-encode your text. :::tip **Tip:** Use `repoprompt-ce://open//Users/example/Project` to open a project, replacing the example with your folder's absolute path. The examples below show encoded prompts and other parameters. ::: ```text repoprompt-ce://open//Users/example/Project repoprompt-ce://open//Users/example/Project?files=Sources/App.swift,README.md&prompt=Review%20the%20selected%20files repoprompt-ce://open//Users/example/Project?workspace=Review&focus=true&ephemeral=true repoprompt-ce://prompt?title=Review&content=Review%20the%20current%20selection&focus=true ``` The opener supports `workspace`, `files`, `prompt`, `focus`, `ephemeral`, and `persist` parameters. The examples respectively open a folder, select files and seed instructions, focus or create an ephemeral workspace, and create a saved prompt. Copying an example does not execute it. ### Saved Prompts Export Prompts, Import Prompts, and Reset Prompts buttons - **Export Prompts** writes saved prompts to a JSON file you choose, with `SavedPrompts.json` suggested as the filename. - **Import Prompts** reads a JSON file and adds imported prompts, reporting how many were added. - **Reset Prompts** asks for confirmation, removes custom prompts, and restores the defaults. This action cannot be undone through the reset dialog; export first if you want a backup. --- ## Appearance Full Appearance pane showing theme, text size, display options, and text editing Adjust the app’s appearance, theme, and interface text size. Open **Settings → General → Appearance**. Most choices apply app-wide and are saved for later launches. The screenshot shows example selections, not recommended defaults. ### Theme Theme selector with System, Light, and Dark choices Choose **System** to follow macOS appearance, or **Light** or **Dark** to keep a specific color scheme. The selected theme is applied when you change it. ### Text Size Text Size selector with Normal, Large, and Extra Large choices **Normal**, **Large**, and **Extra Large** set the app's global text-size preset. You can also step through these presets with the font-size controls in [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/). Changes normally apply immediately. During a response that freezes text scaling to keep the streaming layout stable, the new size is held until scaling is unfrozen. ### Display Options Display Options with collapse file changes, tooltips, and timestamp date switches - **Always Collapse File Changes** keeps file-change displays collapsed, reducing rendering work for very large generations. - **Show Tooltips** enables the app's hover explanations. - **Show dates in message timestamps** adds labels such as Yesterday, a weekday, or a date to message and tool timestamps. These settings change presentation; collapsing file changes does not undo edits. ### Text Editing Text Editing with spell checking, Compact or Expanded file picker style, and experimental mention menu **Enable Spell Checking in Instructions** checks spelling in the instructions text area. **@ File Picker Style** changes the density of file-mention suggestions: **Compact** or **Expanded**. **Enable @-Mention Menu (Experimental)** enables file suggestions when typing `@` in the Compose prompt editor. Picker style and enabling the experimental menu are separate controls. --- ## Keyboard Shortcuts Keyboard Shortcuts master switch, Application group, and current-session actions Review and customize keyboard shortcuts for RepoPrompt actions, including workspace, Compose, preset, and agent commands. Open **Settings → General → Keyboard Shortcuts**. Click a shortcut recorder and press the desired key combination to change that action's binding. Use its clear button to remove a binding. Bindings are stored per app; menu-bar shortcuts or other apps can conflict with them. The tables below list the implementation defaults. Your current bindings can differ. On a Mac, **Command** is ⌘, **Option** is ⌥, **Control** is ⌃, and **Shift** is ⇧. ### Enable keyboard shortcuts Enable keyboard shortcuts master switch and explanation that custom bindings remain saved Turn off **Enable keyboard shortcuts** to stop these registered shortcuts from running while keeping your custom bindings saved. [Advanced](https://repoprompt.com/docs/settings/advanced/#keyboard-shortcuts) exposes the same master setting. These shortcuts apply while RepoPrompt is active; standard text-editing and dialog keys retain their native behavior. Workspace and session actions need an appropriate focused RepoPrompt window; agent shortcuts need a real workspace. ### Application Application and current-session shortcut recorders | Action | Default | | --- | --- | | New workspace window | Command+N | | Settings | Command+, | | Close window | Shift+Command+W | | Check for updates / install available update | Option+Command+U | Clear or change **New workspace window** before assigning Command+N to a new Agent chat or session tab. ### Current Agent session | Action | Default | | --- | --- | | Stop current run | Command+. | | Focus message composer | Command+L | | Pin / unpin session | Shift+Command+P | | Rename session | Shift+Command+R | | Stash session | Shift+Command+E | | Copy handoff prompt | Shift+Command+H | | Copy session ID | Option+Command+C | | Delete session… | Unassigned | These actions target the current session, matching its titlebar menu. Delete always asks for confirmation. With no run to stop, Command+. keeps its normal cancel behavior. ### Agent & layout Agent and layout shortcuts for new chat, session sidebar, Context Composer, and session search | Action | Default | | --- | --- | | New Agent chat | Option+Command+N | | Toggle session sidebar | Option+Command+B | | Toggle Context Composer | Command+P | | Show Agent Session Switcher | Command+K | | Search all Agent sessions | Shift+Command+K | | Next session needing attention | Shift+Command+A | | Reopen last stashed session | Shift+Command+T | **New Agent chat** follows the titlebar's New Session action. The session switcher navigates sessions in the focused window; searching all sessions includes active and recent sessions across windows. **Next session needing attention** cycles through sessions with unseen completed, failed, or waiting badges in the current window. **Reopen last stashed session** restores the most recently stashed session, including one closed with Command+W. ### Composer Composer shortcuts for rewriting a draft and sending the original message | Action | Default | | --- | --- | | Re-prompt draft again | Command+Return | | Send original (during Re-prompt) | Shift+Command+O | Re-prompt shortcuts apply while the message composer has focus. **Send original** applies while a rewrite is shown and sends your original draft instead. A matching shortcut elsewhere in this settings list takes priority. Configure rewriting in [Agent Models → Re-prompt](https://repoprompt.com/docs/settings/agent-models/#re-prompt). ### Workspace & presets Workspace save actions and numbered preset shortcuts | Action | Default | | --- | --- | | Save workspace | Command+S | | Save workspace and switch to system workspace | Shift+Command+S | | Save current preset, or create one if none exists | Option+Command+S | | Create new preset | Option+Command+P | | Switch to preset 1–9 | Option+Command+1–9 | Preset numbers follow the workspace manager's preset order. Saving the current preset opens the creation flow if the workspace has no presets. See [Manage Presets](https://repoprompt.com/docs/settings/manage-presets/) for preset configuration. ### Agent session tabs Session tab creation, closing, navigation, parent navigation, and numbered tab shortcuts | Action | Default | | --- | --- | | New Agent session tab | Command+T | | Close active Agent session tab | Command+W | | Next Agent session tab | Control+Tab | | Previous Agent session tab | Control+Shift+Tab | | Next parent Agent session | Option+Command+] | | Previous parent Agent session | Option+Command+[ | | Focus Agent session tab 1–9 | Command+1–9 | Numbered session shortcuts follow the Agent session sidebar order. Parent-session navigation cycles only root rows; child sessions stay grouped under their parent. ### Display Increase, decrease, and reset font size shortcut recorders **Command+=** increases text size and **Command+-** decreases it. **Command+0** resets text size. These shortcuts use the same global text-size presets as [Appearance](https://repoprompt.com/docs/settings/appearance/#text-size). --- ## Notifications Full Notifications pane showing delivery controls, Agent Sessions events, response actions, and Chat and Context Builder notifications Choose which events notify you, whether previews include details, and which requests you can answer from a notification. Open **Settings → General → Notifications**. These preferences apply app-wide and also appear in the `notifications` group of the `app_settings` MCP tool. ### Notification delivery and previews Permission status, Open System Settings button, master switch, preview details, active-app delivery, and Dock badge controls **Enable Notifications** is the master switch. Turning it off stops notification posting and disables the event-specific controls below. macOS permission is separate: the status row reports whether delivery is allowed, and **Open System Settings…** opens the macOS notification settings. When macOS permission is denied, RepoPrompt can fall back to bouncing its Dock icon. - **Show Details in Notifications** includes commands, questions, and message previews. Turn it off for generic text; the **Approve** action is then never offered. - **Notify While RepoPrompt Is Active** allows input-needed banners while the app is frontmost, unless the relevant session is already on screen. - **Show Pending Count on Dock Icon** badges the Dock icon with the number of sessions waiting for you. These four switches are on by default. Notification previews can expose task content on screen; choose the details setting accordingly. ### Agent Sessions Agent Sessions controls for approvals, instruction waits, completion, failure, active-app completions, agent-driven sessions, and MCP questions The following event notifications are on by default: | Control | Event | | --- | --- | | **Approvals & Questions** | A session needs approval, an answer, or a review. | | **Waiting for Instruction** | A session is waiting for your next instruction. | | **Turn Complete** | An agent turn finishes while you are elsewhere. | | **Run Failed** | An agent run fails. | Notifications are grouped by session and removed when the request is handled elsewhere. Three additional options are off by default: - **Completions While RepoPrompt Is Active** also allows completion and failure banners while RepoPrompt is frontmost. It is separate from the input-needed banner setting above. - **Include Agent-Driven Sessions** includes sessions controlled by another agent through `agent_run`. Their interactions offer **Open** only, because the orchestrating agent handles the answers. - **Notify Instead of Activating for MCP Questions** posts a notification when an external MCP client asks a question in an Agent Mode tab while RepoPrompt is in the background, instead of bringing the app forward. ### Responding from Notifications Response action switches for approval, answers, and replies to completed turns **Approve from Notifications** is on by default, but only offers approval for short, single-line, low-risk shell commands displayed in full. File changes, permission grants, reviews, and persistent “always allow” decisions open RepoPrompt instead. Showing notification details must also be enabled. **Answer from Notifications** is on by default. Simple questions and instruction waits can offer option buttons, **Skip**, **Decline**, or **Reply**. **Reply from Turn-Complete Notifications** is off by default. Enable it to send typed notification replies as the session's next message. Every action is checked against the live request when pressed. Stale, risky, or complex requests open the app instead of applying an outdated response. ### Chat & Context Builder Chat Complete and Context Builder Complete notification switches **Chat Complete** notifies when a chat response finishes in the background. **Context Builder Complete** does the same when Context Builder finishes. Both are on by default. --- ## Telemetry Full Telemetry pane with build status, three reporting controls, and privacy explanation Control sharing of crash reports and diagnostics, app-hang reports, and performance timing and tracing. Open **Settings → General → Telemetry**. Reporting depends on both your preferences and whether the build includes a configured telemetry service. ### Build status Telemetry status banner showing reporting active for this build The banner explains the effective state. Telemetry can be inactive because the Sentry SDK is absent, no Sentry DSN is configured, reporting is disabled in Settings, or the process was launched with `REPOPROMPT_TELEMETRY_DISABLED=1`. A stored preference alone does not mean data is being sent. The master control is unavailable in builds without the SDK. ### Reporting controls Share crash reports and diagnostics, App hang reports, and Performance timing and tracing controls - **Share crash reports and diagnostics** is the master permission for configured Sentry reporting. - **App hang reports** allows reporting when the SDK detects that the app has been stuck long enough. It requires the master setting. - **Performance timing and tracing** allows a conservative sample of startup traces. The implementation sets a 5% trace sample rate when enabled; manual tool and agent-run metrics are not sent by this build. Turning off the master setting disables the subordinate controls. Automatic release-health session tracking and failed-request capture are disabled. ### Privacy Privacy disclosure listing collected metadata, excluded content, scrubbing, and the process-level disable variable Reported information can include crash diagnostics, enabled hang reports, release/build metadata, OS and app versions, and optional startup timing. RepoPrompt does not intentionally send prompt contents, chat transcripts, selected file contents, tool payloads, API keys, provider tokens, or full local paths through telemetry. Before upload, a scrubber removes request payloads, headers, cookies, query strings, obvious secrets, local home paths, user/location/server identifiers, stable device identifiers, and IP-like values. To disable telemetry for an entire process regardless of Settings, set **`REPOPROMPT_TELEMETRY_DISABLED=1` before launching it**. This telemetry preference does not control information sent to execution providers or to [Model Router](https://repoprompt.com/docs/settings/agent-decisions/) decision services. --- ## Updates Full Software Updates pane showing update status, manual check, channel selection, and automatic checks Manage software-update checks and choose the release channel used for RepoPrompt updates. Open **Settings → General → Updates**. Status and available actions depend on the installed build and its update configuration. ### Check for Updates Update status beside the Check for Updates button Choose **Check for Updates** to request an update check. The status distinguishes **not checked yet**, **checking**, a successful check with no newer eligible version, an available update, and a failed check. “Updates have not been checked yet” does not confirm that your installation is current. If an update is available, the app offers installation or a manual download according to what that build supports. Checking alone is not confirmation that an update was installed. ### Update Channel Update Channel selector with Stable and Tip Builds | Channel | Releases offered | | --- | --- | | **Stable** | Curated releases; the default channel. | | **Tip Builds** | Signed and notarized builds from the latest passing main branch. | Switching from Tip Builds back to Stable takes effect with the next applicable stable release. To return immediately, reinstall Stable. Newer builds can also show Tip build history when that channel is selected. For help choosing a channel, see [What Is the Tip Version and Should I Use It?](https://repoprompt.com/docs/faq/tip-version/). ### Automatic checks Automatically check for updates checkbox **Automatically check for updates** enables passive checks when the updater is configured for this build. The implementation checks on startup and schedules checks at 12-hour intervals. Turning it off stops those passive checks; you can still use the manual button. Passive checks discover releases. Installation remains a separate updater action. --- ## MCP Server MCP Server settings with window status, strict connection approval, Oracle presets, Context Builder, and setup controls Manage RepoPrompt’s Model Context Protocol server, inspect connection status, configure external clients, and access CLI installation and JSON configuration tools. Open **Settings → MCP Server**. The window number identifies the workspace window whose MCP access you are configuring. Connection counts and available tool counts reflect the running app and enabled tools. ### Status and window access MCP status, window access switch, Auto-Start, connection count, Status Dashboard, and Force Stop Listener The main switch enables or disables MCP tools **for this window**. A running listener and enabled window access are different states: the page can report **Active**, **Waiting for listener…**, **Listener active** with tools disabled for the window, or **Inactive**. **Auto-Start** controls automatic MCP server startup when RepoPrompt launches. The connection badge summarizes connected clients. **Status Dashboard** opens diagnostics, and an error indicator, when present, opens error details. **Force Stop Listener** shuts down the shared listener for **every window and client**. Use the window switch when you only intend to disable access to the current window. A **Cancel** button can appear while a tool is running to abort that call. ### Strict connection approval Strict connection approval checkbox and explanation of saved and per-run approvals **Strict connection approval** controls admission of external MCP clients and applies to new connections: - **Off (default):** common client names are approved automatically. **Always allow this client** saves approval by app name. A program using an approved name can also be admitted, so name-based trust does not verify its executable identity. - **On:** saved and built-in approved names are ignored. Each app is asked once per run; reconnects from the same running app do not ask again. These approvals do not survive a RepoPrompt restart. Agents started inside RepoPrompt do not show connection prompts. Connection admission is separate from [workspace-operation approvals](https://repoprompt.com/docs/settings/workspace-approvals/) and [agent permissions](https://repoprompt.com/docs/settings/agent-permissions/). ### Oracle Model Presets Oracle Model Presets switch, Manage button, fallback model picker, and Show presets link **Use Oracle Model Presets for MCP** controls whether MCP exposes configured Oracle presets. **Manage** opens [Model Presets](https://repoprompt.com/docs/settings/model-presets/). When presets are disabled, MCP uses the current Oracle model. If no presets are defined, the page offers a model choice and uses the Oracle fallback. If Setup Wizard temporarily hid presets, **Show presets** restores their visibility. The selected model in the screenshot is an example, not a requirement. ### Context Builder Context Builder model summary linking to Agent Models This row displays the agent and model used by the `context_builder` MCP tool. Open it to change the selection in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). It is separate from Oracle Model Presets. ### Quick Setup Quick Setup with Install MCP, Skills menu, and copy configuration button **Install MCP…** offers setup for supported clients, including Cursor, VS Code, Codex CLI, OpenCode, Claude Desktop, and per-project Claude Code configuration. Choose the client you intend to connect. If it does not discover the integration immediately, restart that client after installation. **Skills** installs or removes integration instructions for supported locations, including shared `.agents/skills`, Claude Code commands, and RepoPrompt's isolated Codex prompts. Choose the MCP or CLI variant for the integration you use. These are separate from installing the MCP client configuration. The copy button copies the generated MCP configuration for manual setup. ### CLI Tools CLI installation status and uninstall actions for rpce-cli and claude-rpce **`rpce-cli`** runs MCP commands from a terminal. **`claude-rpce`** wraps Claude Code so it can use RepoPrompt's MCP tools. Each row reports whether its command is installed and offers **Install**, **Update**, or **Uninstall** as appropriate. Debug builds use their debug command names. Installing a CLI command and enabling a window's MCP access are separate steps. ### JSON Configuration Expanded JSON Configuration with the local command path blurred and app backend arguments visible Expand **JSON Configuration** to inspect and copy the JSON for an external client's MCP configuration. The generated command normally uses a managed link that survives app updates, with a bundled-path fallback. Add the configuration in your client, then connect it to RepoPrompt. If the client cannot find the generated command after moving the app or switching app builds, copy the configuration again from the intended running app and update the client. Use [Tools](https://repoprompt.com/docs/settings/tools/) to control individual tool availability. Tool access also remains subject to the target workspace and applicable approval rules. --- ## Model Presets Configured Default model preset showing one Oracle, its model, description, and All modes Create and manage named model configurations for common tasks and expose model presets through the MCP interface. Open **Settings → MCP Server → Model Presets**, or choose **Manage Presets** from Chat Settings. These are named Oracle configurations, distinct from [workspace presets](https://repoprompt.com/docs/settings/manage-presets/) and [Copy/Chat workflow presets](https://repoprompt.com/docs/settings/workflow-presets/). ### Read a model preset Default preset row with one Oracle and no mode restrictions The pictured row contains: - **Default**: the preset name. - **1 Oracle**: the number of models in its ordered Oracle roster. - The configured model name: the model used by that roster entry. - **Current chat model**: this preset's description. - **All modes**: no Chat, Plan, or Review restriction. The model and description are saved preset values. “Current chat model” does not make the preset a live alias that automatically follows later model-picker changes. ### Create and edit If the list is empty, **Create Default Preset** creates one from the currently selected chat model and opens its editor. Otherwise, use **Add Preset**. Hovering an existing row reveals **Edit** and the delete control; those actions are not visible in this capture. The editor configures the name, ordered Oracle models, optional description, supported modes, and optional Chat Preset mappings. The first model is the **Primary Oracle**; additional entries can be reordered or removed. Save persists the configuration. Deleting a preset removes the named configuration, not the provider account or model itself. ### Expose presets to MCP Enable **Use Oracle Model Presets for MCP** in [MCP Server](https://repoprompt.com/docs/settings/mcp-server/#oracle-model-presets) or [Chat Settings](https://repoprompt.com/docs/settings/chat-settings/#oracle-model-presets). These controls use the same saved setting. When recommendations temporarily hide presets, the **Presets Hidden** banner offers **Show Presets**. The presets remain stored while hidden. Mode restrictions can limit which presets are available for a particular Oracle request. --- ## Tools (Mcp-server) MCP Tools window access switch, enabled count, and tool search Manage window-level MCP access, search the tool catalog, and configure individual tool availability. The sections below show each tool separately so its controls and description remain readable. Open **Settings → MCP Server → Tools**. RepoPrompt defines **31 total domain tools**, of which **21 are advertised** to standard external MCP clients (composed of **3 global tools** — `app_settings`, `bind_context`, and `manage_workspaces` — and **18 window-scoped tools**). The remaining **10 policy-gated and sub-agent internal tools** are reserved for eligible Agent Mode sessions and cross-session oversight. Expand **More…** beneath a tool to inspect its description. For supported arguments, response behavior, and examples, use the [MCP Server Tools Reference](https://repoprompt.com/docs/mcp-server/mcp-tools/); the connected client’s advertised schema is the contract for that connection.
View the MCP Tools settings Complete MCP Tools pane with all 21 tool descriptions expanded
### Access, search, and availability **Enable MCP tools for this window** is the same window-level gate as the switch on [MCP Server](https://repoprompt.com/docs/settings/mcp-server/). Turning it off disables the individual switches in this pane. Individual tool switches are saved in an **app-wide** disabled-tools list shared by windows. They are not separate per-window preferences, despite the captured pane's introductory wording. Changes notify connected clients that the tool list changed. **Search tools…** filters names and descriptions without changing enablement. The count shows how many tools are enabled; with a search, the list also shows how many matching tools are enabled. **More…** expands a long description and **Show less** collapses it. Expanding a description does not run the tool. If the list says **No tools discovered**, start the MCP server and connect a client. Tools restricted to particular agent contexts are omitted from this general settings list. Enabling a tool does not bypass workspace permissions or the tool's own input and approval checks. ### agent_explore Launches short-lived, read-only child agents for narrow repository investigations. Each gets a fresh context and the Explore role. Operations are `start`, `poll`, `wait`, and `cancel`; a batch can start multiple independent probes. See the [`agent_explore` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#agent_explore). Explore children cannot edit files, call Oracle, or spawn more agents. They inherit worktree bindings by default, with an opt-out. When Model Router is enabled, new explore children can be routed across eligible targets. agent\_explore switch and expanded description for read-only exploration agents ### agent_manage Lists agent choices, model and role mappings, sessions, and workflows. It also reads session logs, exports handoffs, creates or resumes sessions, stops sessions, and cleans up eligible MCP-created sessions. `list_agents` supplies the current role mappings and exact model identifiers. `get_log` reads transcript turns; handoff export prepares context for continuing elsewhere. Cleanup targets specified MCP-originated sessions and does not delete user-created sessions. See the [`agent_manage` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#agent_manage). agent\_manage switch and expanded agent catalog, session management, and workflow description ### agent_run Starts and controls Agent Mode runs. `start` creates a new session; `steer` continues an existing one. `poll` checks immediately, `wait` waits for completion or input, `respond` resolves a pending interaction, and `cancel` stops an active run. Use the returned session and interaction identifiers for follow-up calls. Role labels use the configured Agent Models mapping; an exact compound model identifier pins a target. Model Router can choose for eligible starts using a role or omitted model. See the [`agent_run` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#agent_run) and [Model Router](https://repoprompt.com/docs/settings/agent-decisions/). agent\_run switch and expanded start, wait, steering, and interaction description ### app_settings Reads and updates the allowed set of app-wide preferences. `list` discovers settings, `get` reads values, `set` writes one key, and `options` discovers supported choices where available. Only exposed settings can be changed; invalid or out-of-range values are rejected. The current implementation also exposes notification preferences, matching the [Notifications](https://repoprompt.com/docs/settings/notifications/) pane. See the [`app_settings` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#app_settings) and the full [App Settings Tool reference](https://repoprompt.com/docs/mcp-server/mcp-app-settings/). app\_settings switch and expanded allowed preferences and operations ### apply_edits Edits file contents using exactly one mode: replace the whole file with `rewrite`, replace matching text with `search` and `replace`, or apply a list of `edits`. Mixing modes is rejected. Replacements are literal text. A rewrite can opt into creating a missing file with `on_missing`; otherwise a missing file is an error. Enable this tool only when clients should be able to request file-content changes under the applicable permissions. See the [`apply_edits` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#apply_edits). apply\_edits switch and expanded rewrite, replacement, and multiple-edit modes ### bind_context Lists available contexts, reports the connection's current binding, and binds a client to a specific workspace context. Prefer absolute workspace root paths in `working_dirs`, or use a returned `context_id`. The binding is retained for that MCP connection. Switching the visible tab does not redirect an existing binding. This is a global context tool. Its external schema does not accept an app-window selector; discover and bind by workspace roots or context UUID. See the [`bind_context` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#bind_context) and [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/#context-binding). bind\_context switch and expanded context listing and binding description ### context_builder Runs a Context Builder agent to discover relevant code, select files within a token budget, and prepare a clarified prompt. Describe the task and known constraints; exhaustive file selection beforehand is not required. The default or `clarify` response returns context for later use. `question`, `plan`, and `review` request a follow-up answer, implementation plan, or review. Response export can produce a shareable file. See the [`context_builder` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#context_builder). Configure discovery in [Context Builder](https://repoprompt.com/docs/settings/context-builder/) and its model in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). context\_builder switch and expanded discovery, response type, and export description ### file_actions Creates, moves, or deletes files using absolute paths. A created file is automatically selected. Creation rejects existing files unless overwrite is explicitly requested; a move fails when the destination already exists. Deletion moves files or folders to the macOS Trash, where they remain recoverable until Trash is emptied. Moving a file transfers its selection state. See the [`file_actions` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#file_actions). file\_actions switch and expanded create, delete, and move behavior ### file_search Searches file paths, file contents, or both. `auto` selects the mode from the pattern; explicit modes are `path`, `content`, and `both`. Filters can limit extensions and directories or exclude paths. Regex matching is available; set `regex=false` for literal content matching or glob-style path matching. Result and output limits can truncate large searches. For an agent bound to a worktree, filesystem searching uses that worktree even when returned paths retain the canonical workspace form. See the [`file_search` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#file_search). file\_search switch and expanded path, content, matching, and filter options ### get_code_structure Returns root-local committed code structure for supplied files or directories, or the current selection when paths are omitted. It can include signatures and expand relationships through `uses`, `used_by`, or both. Output size and relationship depth limit the response. If a result reports truncation, request a larger size or narrow the seeds. Update-pending information distinguishes a usable committed graph from work still being refreshed. See the [`get_code_structure` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#get_code_structure). get\_code\_structure switch and expanded structure, relationship, signature, and output-size options ### get_file_tree Returns a text directory tree or lists loaded root folders. Tree modes include automatic sizing, full output, folders only, and selected files with their parent directories. Use `path` to focus a subtree and `max_depth` to limit traversal. Selection and Code Map markers describe workspace state. Bound-worktree searches follow the session's worktree. See the [`get_file_tree` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#get_file_tree). get\_file\_tree switch and expanded tree types, modes, depth, and selection markers ### git Provides read-only Git inspection: `status`, `diff`, `log`, `show`, and `blame`. Diff comparison choices include staged, unstaged, uncommitted, branch, and merge-base comparisons. Detail levels range from summary to full patches. Artifact output writes review files and can make them available for later context selection. This tool does not commit or push. Use repository selectors when working with multiple roots; some history operations use the primary repository only. See the [`git` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#git). git switch and expanded read-only status, diff, log, show, blame, and artifact options ### history Queries past Agent Mode sessions across saved workspaces. Operations list sessions, search transcripts and summaries, retrieve a bounded session excerpt, and calculate time spent. These operations are read-only. Use workspace filters when you want a narrower scope; binding the MCP connection to a window does not itself restrict historical searches. Time calculations use the [Advanced idle threshold](https://repoprompt.com/docs/settings/advanced/#history-time-tracking) unless overridden per query. See the [`history` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#history). history switch and expanded cross-workspace session search, transcript, and time analytics ### manage_selection Changes the file context used by tools: get, add, remove, replace, clear, preview, promote, or demote selections. Files can be represented by full content, line slices, or Code Maps. `set` can replace a selection, so use incremental `add` and `remove` when preserving existing context matters. Multi-root paths can use a root-name prefix to disambiguate files. Git artifact paths have stricter matching and representation limits than ordinary workspace files. See the [`manage_selection` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#manage_selection). manage\_selection switch and expanded selection operations, full files, slices, and Code Maps ### manage_workspaces Lists, creates, switches, hides, restores, and deletes workspaces, and manages their folders and Compose tabs. Hiding keeps a workspace recoverable; deleting a saved workspace is permanent. `bind_context` is the canonical tool for connection binding. Legacy tab-listing and tab-selection operations remain compatibility paths. Background tab creation can avoid stealing focus; setting `focus=true` visibly switches the user's tab. See the [`manage_workspaces` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#manage_workspaces) and [Connection Management](https://repoprompt.com/docs/mcp-server/mcp-connections/). manage\_workspaces switch and expanded workspace and Compose-tab lifecycle operations ### manage_worktree Lists, inspects, creates, and binds Git worktrees to Agent sessions. Merge operations use the session's bound source worktree and can preview, apply, inspect status, continue, or abort a merge. Preview does not mutate the repository. Apply uses the returned operation identifier and requires the applicable confirmation; plain MCP callers use `confirm_preview=true`. Worktree binding is session-specific, so identify the intended session and repository when there is ambiguity. See the [`manage_worktree` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#manage_worktree) and [Worktrees](https://repoprompt.com/docs/worktrees/). manage\_worktree switch and expanded Git worktree binding, merge preview, apply, and confirmation behavior ### oracle_send Consults Oracle for questions, planning, or review. Without an explicit chat or new-chat request, it resumes the selected eligible conversation, falling back to the most recent eligible conversation. `new_chat=true` starts fresh. A model override applies only to an explicit new conversation. Exposed Model Presets can select a complete Oracle roster and Chat Preset. Response export writes a shareable file for another agent. Agent Mode can expose `ask_oracle` for the corresponding task. See the [`oracle_send` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#oracle_send). oracle\_send switch and expanded conversation continuation, model selection, and export behavior ### oracle_utils Provides read-only Oracle helpers: discover available model choices and list Oracle/chat sessions. It does not send an Oracle message. Use `oracle_send`, or `ask_oracle` when exposed in Agent Mode, to request a response. oracle\_utils switch and expanded read-only model and session listing See the [`oracle_utils` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#oracle_utils). ### prompt Gets, replaces, appends to, clears, or exports the shared instructions text. It also lists and selects copy presets. Selecting a preset requires an explicitly bound tab context. Export writes the formatted prompt to a file. It does not submit that file to another AI service. A copy-preset override changes the export format. See the [`prompt` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#prompt). prompt switch and expanded prompt editing, export, and preset operations ### read_file Reads a file in full or by line range. Positive `start_line` values are one-based; a negative value reads from the end. With a positive start, `limit` bounds the number of lines. Reuse returned file paths for reliable lookup, adding a root alias when needed. For worktree-bound sessions, reads use the bound worktree. Approved external read paths remain read-only. See the [`read_file` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#read_file). read\_file switch and expanded path and line-range reading options ### workspace_context Returns or exports the current workspace context. The default snapshot includes the prompt, selection, code structure, and token counts. Optional sections can include full file contents or a selected-file tree. Use include options to control the payload, or a copy-preset override to change rendering and token calculation. `export` writes the rendered context to disk; it does not send that context to an external service. See the [`workspace_context` contract](https://repoprompt.com/docs/mcp-server/mcp-tools/#workspace_context). workspace\_context switch and expanded snapshot, export, token, and copy-preset options ### Policy-Gated and Sub-Agent Internal Tools In addition to the 21 advertised tools above, RepoPrompt defines **10 policy-gated and sub-agent internal tools** that are omitted from this general settings pane and dynamically exposed only within eligible Agent Mode sessions and authorized oversight contexts: - **`ask_user`** — Prompts the user with structured questions, optional suggested answers, and configurable timeouts. - **`ask_oracle`** — Consults the configured Oracle model directly from an eligible Agent Mode session. - **`oracle_chat_log`** — Reads recent Oracle conversation history (`limit` 1–50) during an Agent Mode run without sending a new turn. - **`agent_session_link`** — Manages cross-window and cross-session communication links, steering, model targeting, and auto-wake snoozing. - **`session_admin`** — Administers sessions within a user-granted delegation scope, including session tree inspection, organization, worktree binding, and merge coordination. - **`become_overseer`** — Requests promotion of the calling session to an overseer role to coordinate sibling sessions. - **`self_compact`** — Requests self-compaction or context inspection (`op="context"` or `"compact"`) of the agent's own session context. - **`share_thoughts`** — Publishes reasoning thoughts or plan progress to the session timeline. - **`set_status`** — Updates the human-visible status indicator on the session card. - **`wait_for_next_user_instruction`** — Signals that the agent has completed its turn and is waiting for the next user instruction. See [Policy-Gated and Sub-Agent Internal Tools](https://repoprompt.com/docs/mcp-server/mcp-tools/#policy-gated-and-sub-agent-internal-tools) in the Tools Reference for details. --- ## Workspace Approvals Workspace Approvals with global approval, operation permissions, and trusted clients Manage approvals for operations that change RepoPrompt workspaces, such as creating folders or deleting workspaces. Configure global operation approvals and review or revoke trusted-client permissions. Open **Settings → MCP Server → Workspace Approvals**. These controls govern requests to change RepoPrompt workspaces. CLI-agent tool permissions and sub-agent policies are configured separately in [Agent Permissions](https://repoprompt.com/docs/settings/agent-permissions/). ### Global Settings Auto-approve All Operations switch **Auto-approve All Operations** skips workspace-operation approval prompts from every client. It is off by default. When enabled, the individual operation switches below are disabled because the global choice already approves them all. This switch grants future requests approval; it does not itself create, remove, or change a workspace. ### Operation Permissions Create Workspace, Delete Workspace, Add Folder, and Remove Folder approval switches with risk labels Enable a switch to automatically approve that operation globally, without granting every operation. All four are off by default. | Operation | Effect | Displayed risk | | --- | --- | --- | | **Create Workspace** | Creates a workspace record. | Low | | **Delete Workspace** | Deletes an existing workspace. | High | | **Add Folder** | Adds a folder to a workspace. | Medium | | **Remove Folder** | Removes a folder from a workspace. | Medium | Adding or removing a workspace folder changes its membership; it does not mean creating or deleting that project folder on disk. Workspace deletion can remove saved workspace state and history, so review the requested target. ### Trusted Clients Trusted Clients list showing a client, permission count, expansion control, removal control, and Reset All Clients appear here after you choose **Always Allow** for a workspace operation. Each row shows the client identifier, saved permission count, and last-used information. Expand a row to inspect and remove individual operation permissions, or use its removal control to clear all permissions for that client. **Reset All** asks for confirmation before removing every client's saved auto-approvals. It does not turn off the global approval settings above: disable those separately if you want those operations to prompt again. --- ## API Providers API Providers pane with legacy storage repair, provider credentials, Azure configuration, and local model settings Configure direct API-provider credentials and provider-specific connections used by RepoPrompt’s model features. These API connections are separate from the coding-agent runtimes configured in CLI Providers. Open **Settings → Models & Providers → API Providers**. These connections primarily serve the Oracle Model, built-in chat, and legacy integrations. For coding-agent runtimes, use [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/). The masked keys and model selections in the screenshot are examples. ### Credentials and model choices For the difference between a coding-runtime login and an API credential, and how saved keys are used, see [Do I Need an API Key?](https://repoprompt.com/docs/faq/api-keys/). For a provider, enter its key and choose **Validate & Save**. A validated entry displays a checkmark and changes the button label to **Change**. **Delete** removes that stored provider credential. The information button opens the provider's reference page. Where model discovery is supported, validate first to populate **Add Custom Model**. Select a model to add it to RepoPrompt's model choices; **None (Remove custom model)** clears that custom choice. Where the UI instead offers a text field, enter a compatible model identifier and use its save button. Validation contacts the selected provider; it is not an offline format check. ### Legacy secure storage repair Legacy secure storage repair notice and Review button Older official builds may have credentials in a legacy Keychain service. **Review…** opens an explicit review/import flow; no legacy scan runs at startup. Imported values are verified, and legacy values are retained by default for rollback. Deleting a legacy value is a separate action. Follow [Recover Credentials After an Upgrade](https://repoprompt.com/docs/faq/credential-recovery/) for scan results, replacement conflicts, Keychain prompts, and the optional legacy deletion step. Storage verification is separate from validation with the provider's service. ### Anthropic Provider reference: [Anthropic API](https://repoprompt.com/docs/providers/anthropic-api/). Anthropic API key controls and custom model identifier field Configure the direct Anthropic API key here. The custom-model field accepts a compatible Anthropic model identifier. This is separate from signing into Claude Code in CLI Providers. ### OpenAI Provider reference: [OpenAI API](https://repoprompt.com/docs/providers/openai-api/). OpenAI key controls, Service Tier, service-tier variant switch, and custom base URL disclosure Validate the key to fetch available models. **Service Tier** offers **Auto**, **Default**, **Flex**, and **Priority**. Auto follows the API project's settings. The pane describes Flex as a cost-oriented option and Priority as a speed-oriented option; availability depends on the provider and model. **Show service-tier variants in model list** exposes tier-specific model choices. Selecting one overrides the global tier for that request. Expand **Advanced (Custom Base URL)** to configure and validate an alternate OpenAI endpoint. For a separate OpenAI-compatible provider configuration, use [Custom API](https://repoprompt.com/docs/settings/custom-api/). ### DeepSeek Provider reference: [DeepSeek](https://repoprompt.com/docs/providers/deepseek/). DeepSeek validated key and custom model selection Validate the DeepSeek API key, then choose a discovered custom model if needed. The selected model and success message show what has been added to the model list; the pictured model is not a required default. ### Fireworks AI Provider reference: [Fireworks AI](https://repoprompt.com/docs/providers/fireworks-ai/). Fireworks AI key validation and model discovery status Configure a Fireworks AI key. Model choices become available after validation; an empty discovery list is shown with guidance to validate first. ### Grok (xAI) Provider reference: [Grok / xAI API](https://repoprompt.com/docs/providers/xai-api/). Grok xAI key validation and model discovery status Configure direct xAI API access and discover available models. A saved xAI API key is also passed to Grok Build for Agent Mode, Context Builder, Oracle, Chat, and model discovery (including Connect), even when you are signed in with `grok login`. Grok chooses which credential each request uses; requests that use the key are billed to your xAI API account. ### Groq Provider reference: [Groq](https://repoprompt.com/docs/providers/groq/). Groq key validation and model discovery status Configure a Groq API key and validate it before selecting a discovered model. **Groq** and **Grok (xAI)** are different provider entries. ### Z.AI Provider reference: [Z.AI API](https://repoprompt.com/docs/providers/zai-api/). Z.AI key controls and custom model selection Configure the Z.AI key and optional custom model. Unlike most entries on this page, this credential also activates **CC Zai** in Agent Mode. Manage that runtime's configuration in [CLI Providers](https://repoprompt.com/docs/settings/cli-providers/). ### Gemini Provider reference: [Gemini API](https://repoprompt.com/docs/providers/gemini-api/). Gemini key controls and custom model identifier field Configure the Gemini API key for direct model access. Use the custom-model field and its save control for a compatible model identifier. This is not the Google Antigravity CLI setup. ### Azure OpenAI Provider reference: [Azure OpenAI](https://repoprompt.com/docs/providers/azure-openai/). Azure OpenAI Base URL, API Version, key, and validation controls Enter the Azure resource **Base URL**, **API Version**, and **API Key**, then choose **Validate & Save**. The displayed API-version value is an example from the capture, not a recommendation for every Azure deployment. After discovery, the implementation can offer **Add Custom Deployment** to pin a deployment. Clearing that choice returns to the discovered deployment priority. ### Local Model Settings Provider reference: [Local Models](https://repoprompt.com/docs/providers/local-models/). Local model URL, model selector, Validate and fetch models, and Reset to Default Enter the URL of your running local model server, then choose **Validate & fetch models**. Once discovery succeeds, select a model. For an already validated configuration, the button becomes **Refresh models**. The pane identifies common ports: **11434** for Ollama and **1234** for LM Studio. **Reset to Default** restores the local configuration defaults. It does not install or start a model server. --- ## Custom API (Models-and-providers) OpenAI-compatible provider configuration with endpoint, key, preferred model, token limit, and save controls Add and manage custom OpenAI-compatible API endpoints, their authentication, and the models offered through each endpoint. Open **Settings → Models & Providers → Custom API** to configure an OpenAI-compatible endpoint. This is a direct API connection, not a CLI-agent runtime. For endpoint compatibility, model discovery, prerequisites, and account boundaries, see the [Custom API provider reference](https://repoprompt.com/docs/providers/custom-api/). The sections below describe the configuration fields and actions. ### Endpoint, key, and preferred model Custom API provider URL, key, and optional preferred model identifier Enter the **Provider URL**, including the API version path where needed, and the provider's **API Key**. Endpoints that do not require authentication can use an empty key. Current builds may request explicit consent before sending credentials to a non-HTTPS endpoint. Leave **Preferred Model ID** blank to discover models from the endpoint. If the provider cannot list models, enter an exact compatible model identifier instead. ### Default Output Max Tokens Default Output Max Tokens field and save button This caps the requested output length. **0** or an empty saved limit uses the model/provider default. Increase a positive limit when outputs are cut off, subject to the model's actual limits. The displayed **8192** is an example value. The adjacent save button updates the limit on an already validated configuration without another network validation. ### Validate, save, and remove Validate and Save, Delete Provider, and Content-Type header controls **Validate & Save** validates the endpoint and persists the configuration. With no preferred model, it fetches a nonempty model list. With a preferred model, it tests that model with a short completion request rather than relying on model discovery. That validation sends a small test prompt to the provider. **Content-Type header** controls inclusion of that header in the saved custom-provider configuration. **Delete Provider** removes the custom configuration and its stored credential; it does not delete an account at the service. After successful discovery, **Available Models** offers search and per-model enable controls, showing up to 20 matches with enabled models first. Previously enabled models are retained when they still exist in the refreshed catalog. A preferred model is stored separately from that enabled-model set. --- ## Model Config Expanded Model Config controls for diff editing, streaming, and temperature. Configure per-model streaming, API routing, and temperature overrides. These settings are especially useful when a custom endpoint needs behavior different from the app's defaults. Open **Settings → Models & Providers → Model Config**. Available models are grouped by provider and sorted by name. Expand a model to see its controls. If a model is missing, configure its provider and model availability in [API Providers](https://repoprompt.com/docs/settings/api-providers/), [OpenRouter](https://repoprompt.com/docs/settings/openrouter/), or [Custom API](https://repoprompt.com/docs/settings/custom-api/). Changes are saved automatically as app-wide overrides keyed to the model's identifier. There is no separate Save button. Models with saved overrides display a sliders icon and expand automatically when you open the page. For model discovery, identifiers, capabilities, effort, and tiers, use the shared [Models reference](https://repoprompt.com/docs/providers/models/). This page documents the per-model settings controls. ### Allow Diff Editing This switch remains in the interface and saves a per-model preference, but the current implementation treats every model as capable of diff editing. The saved switch does **not** disable diff eligibility or force whole-file responses. To choose **Diff**, **Whole**, or **None** for built-in chat, use [Chat Settings → Advanced Chat Controls](https://repoprompt.com/docs/settings/chat-settings/#advanced-chat-controls-edit-mode). That response-format choice is separate from this legacy capability switch. ### Use Streaming Controls whether a supported provider request streams its response as it arrives or returns the completed response together. Turn it off for a model or endpoint that does not support streaming reliably. The saved override is consulted by provider paths that use the model's streaming capability. It cannot make an endpoint support a streaming protocol it does not implement. Built-in model defaults can differ, so the switch is not a universal guarantee of the request mode used by every provider. ### Use Responses-API This switch appears only for custom-provider models. It controls the model's API-routing flag for the **Responses API**, rather than the usual Chat Completions route. Enable it only when the custom endpoint supports that API. Without a saved override, custom-provider models default to not using the Responses API. Built-in models choose their API route through the app's model definitions and do not show this switch. This setting does not change the provider URL, credentials, or available model list. Configure those on [Custom API](https://repoprompt.com/docs/settings/custom-api/). ### Temperature The per-model slider ranges from **0.0 to 2.0** in **0.1** steps. Moving it creates an explicit temperature override for that model. An explicit **0.0** is still an override; it is not the same as removing the setting. **Reset** removes only the temperature override. The row then displays **Default**, using the model's default temperature when one exists, or the global temperature for its slider display. For provider requests that use the shared temperature settings, precedence is: 1. An explicit per-model temperature override. 2. The request's global temperature, when nonzero. 3. The model's built-in default, or omission of the parameter if no default exists. The displayed fallback and the eventual request value can therefore differ when a nonzero global temperature is set. Provider implementations can also omit temperature for models that do not support it. Temperature is not a reasoning-effort control. ### Token limits and other settings Model Config has no context-window or maximum-output-token control in the current implementation. Set custom-provider output limits on [Custom API](https://repoprompt.com/docs/settings/custom-api/#default-output-max-tokens), or use the provider-specific options in [OpenRouter](https://repoprompt.com/docs/settings/openrouter/#advanced-configuration). **Reset** beside Temperature does not clear streaming, Responses API, or diff preferences. Those switches save explicit on/off values independently. CLI-agent model and reasoning-effort choices are configured in [Agent Models](https://repoprompt.com/docs/settings/agent-models/). --- ## OpenRouter (Models-and-providers) OpenRouter pane showing key controls, advanced configuration, registered models, and fetched models Manage the OpenRouter API key, fetch available models, and choose which models appear in RepoPrompt. Advanced configuration includes token limits and custom headers. Open **Settings → Models & Providers → OpenRouter**. This page controls API access and which OpenRouter models appear in RepoPrompt. Models in the screenshot are examples of a fetched catalog, not fixed defaults. For connection prerequisites, catalog references, capabilities, and account billing, see the [OpenRouter provider reference](https://repoprompt.com/docs/providers/openrouter/). The sections below describe this settings pane's controls. ### API key OpenRouter API key field with Change Key and Refresh and Delete Key controls Enter an OpenRouter key and choose **Validate & Fetch**. Once validated, the button reads **Change Key & Refresh**. **Delete Key** removes the stored credential. A green checkmark reports successful validation. ### Advanced Configuration Collapsed OpenRouter Advanced Configuration section Expand this section for provider settings and custom headers. **Include default OpenRouter models** controls inclusion of the app's default OpenRouter choices. **Use Custom Settings** exposes **Max Tokens**; its reset button restores **8192**. Custom headers are entered as a name/value pair and added with the plus button. Existing headers have individual delete controls. These are request settings, not additional model registrations. ### Registered Models Registered OpenRouter model with a removal button This list contains models you explicitly registered for RepoPrompt's model list. The trash button removes that registration; it does not remove the model from OpenRouter's service. ### Available Models Fetched OpenRouter model search, refresh button, and add controls **Refresh Model List** fetches the provider catalog. **Search fetched models…** filters it by model identifier. The UI displays the first 20 matching models, so use search for identifiers farther down the catalog. Use the plus button to register a model. Registered state changes the row's control so you can remove it again. Fetching a catalog does not automatically register every model in it. --- ## Chat Settings Chat Settings showing the built-in model, Oracle presets, planning prompt, edit mode, and temperature Configure the built-in chat model, the planning prompt, and named Oracle model presets exposed to MCP clients. Built-in chat settings are separate from Agent Mode configuration. Open **Settings → Prompting → Chat Settings**. These controls configure RepoPrompt's built-in chat and MCP Oracle choices. Agent Mode uses its own configuration. ### Recommendations Chat Settings scope explanation and Check Recommendations button **Check Recommendations** opens the recommendations flow for this window. Review the proposed setup there. The model and enabled options pictured on this page are examples, not recommendations for every task. ### Built-in Chat Model Built-in Chat Model picker Choose the model used by built-in chat. Available choices depend on configured providers and models. This picker does not replace your [Agent Models role assignments](https://repoprompt.com/docs/settings/agent-models/#sub-agent-role-defaults). ### Oracle Model Presets Oracle Model Presets enable switch, availability count, and Manage Presets button **Use Oracle Model Presets for MCP** exposes named presets to MCP clients. **Manage Presets** opens [Model Presets](https://repoprompt.com/docs/settings/model-presets/). This is the same enable setting shown on the MCP Server page, so it does not need to be configured twice. If enabled with no presets defined, a fallback model picker is shown. If disabled, MCP uses the current Oracle model. The availability count is your current configuration, not a fixed preset limit. ### Chat Planning Prompt Chat Planning Prompt editor with Save and Reset to Default Edit the instructions used by built-in chat's **Plan** mode, then choose **Save** to persist your draft. **Reset to Default** restores the shipped planning prompt and refreshes the editor. Copy any custom text you want to keep before resetting. The text in the screenshot is the prompt being configured, not an instruction for someone reading this documentation. ### Advanced Chat Controls: edit mode Advanced Chat Controls with Diff, Whole, and None edit format choices Expand **Advanced Chat Controls** to choose the response format used outside Pro Mode: | Format | Behavior | | --- | --- | | **Diff** | Requests only the changes needed. | | **Whole** | Requests complete replacement file contents. | | **None** | Leaves chat unconstrained but does not support direct file editing through this format. | All models are treated as diff-capable, regardless of the saved **Allow Diff Editing** switch in [Model Config](https://repoprompt.com/docs/settings/model-config/#allow-diff-editing). Changing the model does not disable the edit-format picker or automatically switch the format to **Whole**. Choose **Diff**, **Whole**, or **None** explicitly to set the response format. ### Model Temperature Model Temperature slider and current numeric value The slider ranges from **0 to 1** in steps of **0.1**. Lower values request more focused output; higher values request more variation. The actual effect depends on the selected model and provider's support for temperature. --- ## Copy Prompt Order Copy Prompt Order showing section order, reset action, and duplicated instructions option Set the order of sections in copied prompts and built-in chat context, and choose whether user instructions also appear at the top. Agent Mode assembles its own context independently. Open **Settings → Prompting → Copy Prompt Order**. This affects copied prompts and built-in chat packaging. Agent Mode assembles its context separately. ### Section Order Draggable File Tree, File Contents, Git Diff, Meta Prompts, and User Instructions rows Drag the section rows to change their order. The default is: 1. **File Tree** 2. **File Contents** 3. **Git Diff** 4. **Meta Prompts** 5. **User Instructions** The order is saved when changed. Reordering does not enable a disabled content section or create missing content: disabled, empty, or unavailable sections are omitted during packaging. ### Reset to Default Reset to Default button for section order **Reset to Default** restores and saves the five-section order above. It does not change the separate duplicate-instructions setting. ### Duplicate User Instructions Enable duplicate at top checkbox and explanation **Enable duplicate at top** adds user instructions at the start of the prompt as well as at their normal ordered position. The gray **User Instructions (duplicate at top)** row previews this fixed copy and cannot be dragged. Turn the setting off to remove the extra top copy. The regular User Instructions row remains in the order you chose. No extra block is added when the instructions are empty. --- ## Workflow Presets Workflow Presets Copy tab showing Standard, Plan, Review, and Diff Follow-Up presets Manage reusable Copy and Chat presets that bundle prompts with Code Map, file-tree, and Git-diff options. These presets configure copied prompts and built-in chat rather than Agent Mode workflows. Open **Settings → Prompting → Workflow Presets**. **Copy** and **Chat** use separate preset collections. These presets package copied context or configure built-in chat; they do not configure Agent Mode workflows. ### Choose a collection and find a preset Copy and Chat selector, preset search, visibility filter, and Add Preset Switch between **Copy** and **Chat**, search by preset name, and filter **All**, **Shown**, or **Hidden**. Switching collections resets that list's search and filter state. The switch beside each preset controls its visibility in the quick menu, not whether the preset is currently applied. **Add Preset** creates a custom preset. **Clone** starts a copy you can customize; **Edit** opens the selected preset's configuration. ### Copy presets Copy preset rows with visibility switches, summary chips, Clone, and Edit Copy presets bundle prompt packaging choices, including Code Maps, file-tree and Git-diff inclusion, and stored prompts. The captured built-ins are **Standard**, **Plan**, **Review**, and **Diff Follow-Up**. Summary chips show non-default settings. **Map Auto** indicates automatic Code Map usage, and **Git** indicates Git content inclusion. The exact bundle can be inspected in the editor. ### Chat presets Workflow Presets Chat tab showing Chat, Plan, and Review Chat presets bundle the chat mode, optional model selection, context inclusion, and stored prompts. The pictured built-ins are **Chat**, **Plan**, and **Review**. Mode chips identify the chat mode; **Prompts: 1** reports one selected stored prompt, not one message in the conversation. Chat preset visibility controls and row actions ### Built-in and custom presets The lock and **Built-in** label identify shipped presets. They can have saved overrides; a modified built-in is marked accordingly. **Reset Overrides**, where available, restores its shipped configuration. Built-ins cannot be deleted. Custom presets have a delete action with confirmation. Hiding a preset keeps its saved configuration. Use [Copy Prompt Order](https://repoprompt.com/docs/settings/copy-prompt-order/) for the order of packaged sections, and [Chat Settings](https://repoprompt.com/docs/settings/chat-settings/) for the built-in model and planning prompt. --- ## Search Settings Settings search field. Search Settings filters the app’s settings navigation by page title and related keywords. Matching pages appear in an alphabetical list; clearing the search restores the grouped navigation. --- ## Manage Presets Manage Presets showing the current workspace and its empty preset list Manage saved workspace presets so you can restore reusable file selections and context configurations. Open **Settings → Workspaces → Manage Presets** for the workspace you want to organize. These presets restore workspace file selections. They are separate from [Oracle Model Presets](https://repoprompt.com/docs/settings/model-presets/) and [Workflow Presets](https://repoprompt.com/docs/settings/workflow-presets/). ### Workspace scope Existing Presets heading identifying the current workspace and numbered shortcuts The heading identifies the workspace whose presets you are editing. The first nine presets can be selected with **Option+Command+1–9**, unless you remapped them in [Keyboard Shortcuts](https://repoprompt.com/docs/settings/keyboard-shortcuts/). ### Create the first preset No presets found message directing you to the Presets menu The screenshot shows an empty list. Create a preset from the workspace's **Presets** menu after preparing the selection you want to reuse. The new-preset shortcut is **Option+Command+P** by default. ### Manage existing presets Once presets exist, each row offers switching, renaming, reordering, and deletion. Moving a preset up or down changes its position and therefore its numbered shortcut. A rename must contain non-whitespace text. Switching applies the preset and closes the management sheet. Deleting removes the saved preset from that workspace; it does not delete the selected project files. --- ## Manage Workspaces Manage Workspaces with launch restoration, global storage, workspace creation, and library filters Organize the workspaces that group your project folders and context. Use this page to manage workspace entries and their associated folders. Open **Settings → Workspaces → Manage Workspaces**. A workspace groups project folders and saved RepoPrompt context; it is not the project directory itself. ### Restore workspaces on launch Restore workspaces on launch checkbox **Restore workspaces on launch** controls restoration of workspace windows when RepoPrompt starts. It does not create a new workspace or delete existing saved workspaces. ### Global Storage Location Collapsed Global Storage Location disclosure Expand this section to see the custom storage path or **Using Default Storage**. **Set Storage Location** chooses where RepoPrompt stores workspace data. **Reset to Default** appears when a custom location is configured. Changing this setting can migrate saved workspace data. It is separate from adding project folders to a workspace; it does not relocate your source-code directories. ### Create a New Workspace Workspace name, Add Folders, and Create Workspace controls Enter a **Workspace name**, choose **Add Folders** to select one or more directories, then choose **Create Workspace**. You can create from a name without folders, or from selected folders with an automatically supplied name. The button is disabled while both name and folder selection are empty. The app creates the workspace and requests a switch to it. Adding folders references existing directories; it does not copy the project files. ### Browse and manage the library Saved, Temporary, and All filters, workspace search, and Select control Use **Saved**, **Temporary**, or **All** to choose the workspace collection, and **Search workspaces…** to filter the list. **Select** opens the multi-selection controls for bulk actions. Existing workspace rows provide management actions such as renaming and hiding. Hidden workspaces remain recoverable. Deleting a workspace removes its saved state, tabs, and history; project folders are kept. Bulk deletion asks for confirmation and stops running work in affected workspaces. When duplicate records share project roots, the page can offer **Consolidate Duplicates…**. Its confirmation explains the backup and preservation of records still in active use. Workspace operations requested by clients can also be governed by [Workspace Approvals](https://repoprompt.com/docs/settings/workspace-approvals/). --- ## Why RepoPrompt Modern coding agents optimize for raw _convenience_: you type a prompt, and the agent immediately starts running shell commands and editing files. On small scripts, this feels magical. But on production codebases, unguided autonomous agents frequently hit a wall. RepoPrompt was explicitly architected to solve the **top failure modes in standard coding agents**: --- ### The Top Failure Modes in Standard Coding Agents #### 1. Context Rot & Hallucinations As conversation histories and file dumps expand past a model's effective sweet spot (64k–128k tokens), attention degrades sharply. When forced to reason inside a bloated context window filled with dead-end searches, models invent non-existent APIs, misremember types, and hallucinate implementations. - **How RepoPrompt addresses it:** The **Context Builder** discovery coding agent curates a focused selection toward a configurable context budget before follow-up Oracle analysis. This reduces search noise in the receiving model's context, nearly guaranteeing that every relevant file is found or that all reasoning is spent on the solution. See [Reliable, Useful Results](https://repoprompt.com/docs/overview/how-it-really-works/#1-reliable-useful-results-context-over-convenience). #### 2. "Lost in the Middle" Forgetting Due to the U-shaped attention curve of transformers, models strongly weight instructions at the very beginning and very end of a prompt, but drop accuracy by 30%+ on vital constraints, types, or instructions buried in the middle of a large payload. **How RepoPrompt solves it:** 1. **Code Maps** are compact, Tree-sitter-generated summaries of a file's structure: types, method signatures, and `uses`/`used_by` relationships. They give the model an architectural overview and the interfaces of neighboring modules without filling the prompt with their full implementations. 2. **Line Slices** include selected line ranges from a file, so relevant functions or sections can appear together even when they are far apart in the source. Each slice retains its line numbers and can include a description, keeping implementation details available while leaving out unrelated code. 3. **Instruction Sandwiching** duplicates `` at both the top and bottom of assembled prompts when **Duplicate User Instructions at Top** is enabled. This places your requirements around the Code Maps and file contents, reinforcing them at both ends of the prompt. See [Advanced Context Engineering](https://repoprompt.com/docs/overview/how-it-really-works/#2-advanced-context-engineering). #### 3. MCP & Tool Context Bloat Unbounded tool schemas (schema bloat) and voluminous raw tool outputs (like 500-line `grep` logs) flood the message buffer, burning token budgets and destroying prompt caches before the model even begins reasoning. - **How RepoPrompt solves it:** Strict separation of **Model Context** (curated workspace selection) from **Tool Context** (noisy command history), preloaded compact tool catalogs, non-blocking auto-selection, and disabling redundant native file tools. See [Model Context vs. Tool Context](https://repoprompt.com/docs/overview/how-it-really-works/#3-model-context-vs-tool-context). #### 4. Multi-Turn Drift on Large Tasks As a single agent loops through dozens of iterative edits across 30+ turns, early constraints fade and small misinterpretations compound, causing the agent to wander away from the original goal or introduce conflicting changes. - **How RepoPrompt solves it:** A **Coordinator vs. Worker** architecture (Orchestrator Workflow) that breaks work into discrete 1–4 file work items for fresh sub-agents, coupled with the **Phase Gate Invariant** and an event-driven Overseer Mode **Oversight Auto-Wake**. See [Multi-Turn & Long-Horizon Operation](https://repoprompt.com/docs/overview/how-it-really-works/#4-agents-operating-over-multiple-turns-and-longer-time-horizons). #### 5. Compaction Amnesia Naive token-limit compaction summarizes conversation history by focusing on _what was done_, frequently stripping negative side constraints (e.g., _"never modify the public API"_) and raw file details, causing post-compaction regression loops. - **How RepoPrompt solves it:** Agent-initiated `self_compact` at clean turn boundaries with dedicated `` continuation delivery, `oracle_chat_log` recovery, and `` handoffs. See [Compaction Architecture](https://repoprompt.com/docs/overview/how-it-really-works/#5-compaction-and-preventing-compaction-amnesia). #### 6. Single-Model Blind Spots Forcing a single model to act as a search engine, architect, and coder causes failures—especially when reasoning models (trained to "think then act" in consensus) are forced to execute tool calls mid-thought. - **How RepoPrompt solves it:** Tool-less **Oracle** reasoning paired with tool-native CLI agents, 4 specialized **Agent Roles** (`explore`, `engineer`, `pair`, `design`), parallel **Multi-Oracle Rosters** (up to 5 models) with reconciliation guidance, and local **Usage Balancing**. See [LLM Variations & Limitations](https://repoprompt.com/docs/overview/how-it-really-works/#6-variations-and-limitations-of-large-language-models-llms). #### 7. Diff-Only Review Blindness Reviewing isolated Git patches without surrounding repository context creates high false-positive noise on style while completely missing breaking changes to callers one hop away from the diff. - **How RepoPrompt solves it:** Materialized selectable diff artifacts (`MAP.txt`, `all.patch`, per-file patches) combined with curated codebase context (callers, callees, and type contracts) in `/rp-review`. See [Codebase-Context Code Reviews](https://repoprompt.com/docs/overview/how-it-really-works/#7-code-reviews-diff-only-vs-codebase-context-reviews). #### 8. Over-Engineered Simple Edits Triggering heavy multi-agent orchestration, full discovery pipelines, or multi-model planning for small, well-understood edits adds unnecessary time and token use. - **How RepoPrompt solves it:** Use an ordinary Agent Mode request for a small, well-understood edit instead of selecting a workflow that adds planning or delegation. See [When RepoPrompt Would Not Be Helpful](https://repoprompt.com/docs/overview/how-it-really-works/#8-when-repoprompt-would-not-be-helpful). --- ### Explore the Architecture - Learn how to start your first task in [Getting Started](https://repoprompt.com/docs/overview/getting-started/). - Walk through the three-stage discovery pipeline in [How It Works](https://repoprompt.com/docs/overview/how-it-works/). - Dive deep into the source code implementation and the **Summary Matrix** in [How It (Really) Works](https://repoprompt.com/docs/overview/how-it-really-works/#summary-matrix-problem-vs-repoprompt-architecture). --- ## Create and Use a Worktree A worktree gives a coding task its own checkout. Before starting, open the intended Git repository and decide which committed starting point the task needs. A new worktree does not copy your main checkout's uncommitted tracked edits. ### Start a task in a new worktree 1. Open a new session and choose **Work locally** above the message editor. 2. Under **Start in**, select **New worktree**. This stages the choice; creation happens when you first send. 3. Write a focused task with an observable result. For example: “Fix the empty-state layout and verify it at narrow widths. Work in the new worktree; leave the main checkout unchanged.” 4. Send, then inspect the execution-location indicator. Check the path and branch or detached commit before assuming that work is isolated. If creation reports an error, resolve it before asking for edits. Start in picker offering the workspace checkout, a new worktree, and existing worktrees For a particular base revision or branch configuration, use the supported creation options exposed by the [manage_worktree tool](https://repoprompt.com/docs/mcp-server/mcp-tools/#manage_worktree), and inspect the returned descriptor. Do not infer the base from the task's name. ### Continue in an existing worktree Choose an entry under **Existing worktrees**. Rows identify the branch or detached commit, worktree name, and path. A prunable entry is unavailable. “No other worktrees available” means the picker has no alternative checkout to offer; it does not create one automatically. Changing an established session's location restarts its provider context and can require stopping an active turn. Follow [Execution Location](https://repoprompt.com/docs/agent-mode/execution-location/#change-an-existing-sessions-location) before moving an ongoing task. ### Prepare local setup Committed files come from Git. Dependencies, local configuration, and development services may need separate preparation. To copy selected ignored setup files into app-managed worktrees, put narrow patterns in `.worktreeinclude` at the main repository root: ```gitignore # Copy only these files if Git already ignores them. .env.local config/development.json ``` The include file does not make a file ignored. Add the appropriate ignore rules separately if needed. Automatic session creation uses the ignored-only default; see [copying rules and exclusions](https://repoprompt.com/docs/worktrees/#copying-local-ignored-files-with-worktreeinclude) for the MCP untracked-file opt-in and external-path limitations. ### Finish and preserve the result Run the project's relevant checks in the task's checkout and inspect the actual changes. Commit the intended source changes before requesting a RepoPrompt worktree merge. Stopping a coding agent, closing a conversation, or retiring an overseer lane does not merge its work. Keep the checkout until its work is integrated or deliberately preserved elsewhere. Unbinding a session is a routing change, not worktree deletion. Continue with [Review and Merge](https://repoprompt.com/docs/worktrees/review-and-merge/). --- ## Worktrees A **Git worktree** is a separate working directory attached to the same repository. Each checkout has its own files, index, and checked-out branch or commit, while sharing Git history. You can work on different branches at once without repeatedly switching branches in your main checkout. RepoPrompt creates worktrees through Agent Mode and the MCP `manage_worktree create` tool, with optional copying of local setup files. ### Start with a separate checkout Use a worktree when parallel coding tasks could edit the same files, or when you want to try an approach without changing your main checkout. Separate sessions alone do not isolate files. Follow [Create and use a worktree](https://repoprompt.com/docs/worktrees/create-and-use/) to choose a location and prepare its local setup. When the task is complete, follow [Review and merge](https://repoprompt.com/docs/worktrees/review-and-merge/) to bring committed changes into the intended target checkout. Starting a worktree does not automatically integrate its results. RepoPrompt can create worktrees for MCP tools and Agent Mode. App-managed worktrees are placed in the `.repoprompt-worktrees` container unless you deliberately choose an external path. A worktree gives a coding agent an isolated checkout while the main checkout and other worktrees remain available for parallel work. It does not isolate external services, databases, credentials, or processes outside that checkout. On APFS, RepoPrompt automatically attempts copy-on-write cloning when the new worktree starts from the same tree as a clean source checkout on the same volume. Tracked files initially share disk blocks with the source and consume additional space only when changed. RepoPrompt verifies the cloned checkout by refreshing its index and requiring a clean Git status. It uses an ordinary Git checkout when the source is dirty, the requested base differs, or repository features such as sparse checkout, submodules, Git LFS filters, special line-ending or encoding attributes, hooks, path collisions, different volumes, or an external destination make cloning unsuitable. Set `clone_tracked_checkout=false` when checkout speed matters more than disk space. ### Coordinate worktrees through an overseer An [Overseer](https://repoprompt.com/docs/overseer/#worktrees-on-behalf-of-linked-agents) with worktree authority can create, inspect, bind, or unbind worktrees for sessions in its delegation scope. Repository selection follows the target session's workspace and bindings. Tell the coordinator which repository to use if the target has several bindings. A binding change can wait until the target is idle. Releasing a worktree unbinds it and marks it for cleanup without removing files. The overseer can prepare a merge preview and request application, but you still review the merge in the target session. These operations do not make an isolated checkout a credential or process sandbox. ### Copying local ignored files with `.worktreeinclude` Add `.worktreeinclude` at the main repository root using `.gitignore` patterns. Matching ignored files are copied; tracked edits are excluded. MCP creation can explicitly include matching untracked files with `copy_worktree_include_untracked_files=true`. Patterns support comments, directory rules, globs, and `!` negations. With the default ignored-only behavior, Git must already treat a file as ignored, and the final matching `.worktreeinclude` rule must include it. The explicit MCP opt-in above also permits matching non-ignored untracked files. RepoPrompt copies regular files individually, using APFS clones when available and byte copies otherwise. It does not copy tracked files, ordinary untracked files by default, symlinks, unsafe paths, or files that would overwrite an existing destination. Copying is limited to RepoPrompt-managed worktrees. An external worktree created with `allow_external_path=true` is still created, but `.worktreeinclude` files are not copied there. Successful copying is silent; if a copy cannot be completed, the worktree remains and `manage_worktree create` may report a warning. Agent Mode and descriptor-only flows record production-safe diagnostics. ### Be careful with broad patterns There is no copy-size or file-count limit. Keep patterns narrow to avoid duplicating large caches. For implementation details, see the [worktrees guide in the application source repository](https://github.com/repoprompt/repoprompt-ce/blob/main/docs/worktrees.md). --- ## Review and Merge A worktree merge integrates committed history into another checkout in the same repository. It does not copy an unfinished working directory. The **source** is the session-bound worktree supplying commits; the **target** is the checkout that receives them. ### Prepare both checkouts Finish or stop work that could change either checkout. Review and commit the intended source edits, and ensure the target is clean. RepoPrompt blocks merges when either checkout is dirty, either already has a merge in progress, the repositories differ, or the source and target are the same worktree. If the source commit is already included in the target, there is no new source history to merge. If the session has bindings for several repository roots, identify which repository supplies the source. A session name alone does not identify a checkout. ### Request a preview Ask the coding agent to use the worktree merge tools and name the target explicitly. For example: > Preview merging this session's committed worktree changes into the main workspace checkout. Report the source and target paths, commits, and any blockers. Wait for my review before applying the merge. The [manage_worktree tool](https://repoprompt.com/docs/mcp-server/mcp-tools/#manage_worktree) separates `preview` from `apply`. A preview does not modify the repository. Its operation ID identifies the prepared operation; applying requires the corresponding confirmation or routed UI approval. ### Read Worktree Merge Review When routed through the session's review interface, the card shows source and target endpoints, a merge graph, preflight information, and available diff artifacts. Check the paths as well as branch names. The inline diff is a bounded excerpt; inspect the referenced artifacts or repository changes when the excerpt is incomplete. Choose **Merge** to approve the prepared operation or **Cancel** to dismiss it without applying. If either checkout changed after preview, the operation can become stale. Request a fresh preview and review the new state rather than reusing old approval. ### Resolve conflicts in the target Conflicts belong to the **target worktree**, whose path appears on the conflict card. Open that checkout, inspect Git status, resolve the listed files, and stage the resolutions there. Then choose **Continue after resolving**. When no conflicts remain, continuing creates the merge commit in the target. Choose **Abort merge** if you intend to discard the in-progress merge in the target. This is different from cancelling a preview before mutation. If continuing or aborting fails, read the reported error and inspect that target checkout before retrying. ### Verify the integrated result After completion, inspect the target's Git history and diff and run the relevant checks there. A completed merge does not publish a branch or establish that tests pass. Keep the source checkout until you have verified the result; closing or unlinking the session is not evidence that integration succeeded. --- ## Agent Mode Overview (Agent-mode) Agent Mode hands off RepoPrompt's context engineering to your coding agents. The same best practices that make IDE Mode in the older Classic Edition powerful — codemaps, file slicing, token-budgeted selection, structured prompts for reasoning models — are managed by agents on your behalf, inside a native macOS session host. Agent Mode new session screen showing workflow tips, oracle chat, and file tracking features ### What Is Agent Mode? Agent Mode runs CLI coding agents directly inside RepoPrompt, giving them full access to the same context tools you used in the Classic Edition's IDE Mode — file search, code structure, codemaps, Context Builder, and Oracle Chat. The agents apply RepoPrompt's best practices for context engineering automatically: curating token-efficient selections, using codemaps for architectural awareness, and structuring prompts for optimal reasoning. You watch their work stream in real time, review changes, and guide them as needed. ### Supported Providers Choose a coding-agent integration from the [Providers & Models directory](https://repoprompt.com/docs/1.6.0/providers/overview/#coding-agents). Each provider's reference explains setup prerequisites, authentication, capabilities, and account boundaries. Configure the corresponding fields and controls in [CLI Providers settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/). Use the models actually offered by that connection. The [Models guide](https://repoprompt.com/docs/1.6.0/providers/models/) explains availability, identifiers, reasoning effort, and separate choices for execution, Oracle, and Context Builder. ### Key Capabilities - **Per-Tab Sessions:** Each compose tab gets its own agent session. Run multiple agents in parallel across different tasks with isolated context - **Context Builder Integration:** Agents trigger Context Builder directly — a discovery agent curates the right files, then an analysis model generates plans, reviews, or deep answers grounded in your actual code - **Oracle Chat:** Consult separately configured reasoning models for plans, reviews, and answers based on prepared task context. - **Token-Efficient Tools:** Use Code Maps and line slices to supply relevant structure and implementation without including every file in full. - **Edit Review:** Inspect edits and control approval behavior through the provider's permissions and Auto Edit setting. - **Image Support:** Paste or drag-and-drop images into agent conversations - **Session Management:** Resume sessions, track token usage, and manage multiple agent conversations ### How It Works The typical Agent Mode flow looks like this: 1. **Open a workspace** and start a session for the task. 2. **Choose its execution location** — work in the workspace checkout, create a new worktree, or choose an existing worktree. 3. **Select a workflow template** from the **What are we building?** cards or the **Workflow** selector, then write your goal and constraints. The template wraps that message in a method for the task. 4. **Check the model, effort, tools, and permissions**, then send. 5. **Watch and guide** through conversation, tool cards, live questions, and approval requests. Inspect the resulting changes before accepting the result. Read [Sessions & Interface](https://repoprompt.com/docs/1.6.0/sessions/overview/) for the complete composer walkthrough and individual control guides. For coordinated top-level sessions and managed lanes, see [Overseer Mode](https://repoprompt.com/docs/1.6.0/overseer/). ### Getting Started Open **Settings → Agent Mode → CLI Providers** and connect the provider you intend to use. Codex includes a managed runtime; other integrations may require an installed CLI or a managed runtime installation. Use **Test Connection** and complete any authentication the selected provider requests. Open your project, choose the session's location and workflow, and send a specific task. Model availability and permission behavior depend on the connected provider. :::tip **Onboarding Wizard:** When you first launch RepoPrompt CE, the onboarding wizard will guide you through setting up Agent Mode and testing your CLI providers. ::: --- ## Skills & Slash Commands (Agent-mode) Skills are discoverable instruction files or packages. A skill can contain workflow instructions, but the words are not interchangeable: the workflow describes a process, while the skill is how a compatible host discovers and loads its instructions. RepoPrompt also has in-app workflow templates selected through the **Workflow** control. ### What Are Skills? RepoPrompt's slash-skill loader reads Markdown instruction files with optional YAML frontmatter, including folder-based `SKILL.md` files and supported legacy command files. In Agent Mode, invoking one expands its template with your task description. External coding hosts have their own discovery and invocation behavior. ### Skills in Agent Mode Agent Mode discovers skills from on-disk directories and presents them in the input bar. Type `/` at the start of your message to see available skills — they filter as you type by name and description. When you send a message with a slash skill, RepoPrompt expands the template (stripping frontmatter and substituting `$ARGUMENTS` with your task description) before sending it to the agent. **Skills vs. workflow templates** Agent Mode has two ways to load instructions for a task: the **Workflow** dropdown selects built-in or custom workflow templates, while a **slash skill** loads an on-disk instruction file typed as `/skill-name`. You can use one or the other per message, but not both. A custom in-app workflow template is not automatically an installed skill for an external coding host. ### Skills for Terminal Agents External coding agents can usually discover installed on-disk skills from shared directories when their host supports those locations. Connecting to RepoPrompt's MCP server supplies tool access; it does not install workflow skills. To make RepoPrompt's workflow skills available, install the matching MCP or CLI variant through **Quick Setup → Skills**, then use the external host's skill or slash-command picker. RepoPrompt supplies workflow instructions for external coding agents through commands such as `/rp-build` and `/rp-review`. **Quick Setup → Skills** installs the MCP or CLI variant as skill folders or prompt files for the selected host. These instructions guide the workflow; the client's tools and permissions determine what it can actually do. See [MCP Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/) for the complete catalog and installation locations. ### Creating Custom Skills Custom skills are Markdown files placed in specific directories. RepoPrompt automatically discovers them and makes them available — both in Agent Mode and for any terminal agents that share the same skill directories. #### Skill File Format Each skill file starts with optional YAML frontmatter followed by the prompt template: ```bash --- name: my-workflow description: My custom workflow for specific tasks --- # My Custom Workflow Task: $ARGUMENTS Your detailed instructions here. The agent will follow these instructions when the skill is invoked. ## Steps 1. First, do this... 2. Then do that... ``` The `$ARGUMENTS` placeholder is replaced with whatever the user types after the slash command. #### Folder-Based Skills (Recommended) Create a folder for each skill containing a `SKILL.md` file: ```text .claude/skills/ my-skill/ SKILL.md ← skill definition deploy-workflow/ SKILL.md ← another skill ``` The folder name becomes the default command name (overridden by the `name` field in frontmatter if present). #### Flat File Skills You can also place individual `.md` files directly in a commands directory: ```text .claude/commands/ review.md ← becomes /review deploy.md ← becomes /deploy ``` ### Skill Search Locations RepoPrompt scans provider-specific directories in order of priority. Project-level skills take precedence over global ones: #### For Claude Code 1. `/.claude/skills/` — Project-level folder-based skills 2. `/.claude/commands/` — Project-level flat file skills 3. `~/.claude/skills/` — Global folder-based skills 4. `~/.claude/commands/` — Global flat file skills #### For Codex CLI 1. `/.agents/skills/` — Project-level folder-based skills 2. `/.agents/slash/` — Project-level flat file skills 3. `~/.agents/skills/` — Global folder-based skills 4. `~/.agents/slash/` — Global flat file skills If two skills have the same name, the one found first (higher priority location) wins. Agent Mode watches these directories for changes, so newly created or modified skills appear automatically. ### Installing Built-in Skills RepoPrompt can install its built-in workflow skills into the appropriate directories for your terminal agents. You can do this from: - **Onboarding wizard** — During initial setup, the MCP Setup step includes a "Skills" install button - **MCP Settings** — The settings panel has options to install skills for different providers The installer offers **MCP skills** for instructions that call native MCP tools and **rpce-cli skills** for instructions that use the terminal command. The CLI label can reflect the running build's command name. These are alternate instruction variants, not separate tool permissions or automatic installation of the CLI executable. :::tip **Tip:** Global skills (`~/.claude/skills/` or `~/.agents/skills/`) are available across all your projects. Project-level skills let you create workflows specific to a particular codebase. Skills work in both Agent Mode and with terminal agents. ::: --- ## Agent Workflow Commands Agent Mode comes with built-in workflows that guide your agents through structured, multi-step tasks — from feature implementation to deep code reviews. ### How Workflows Work Each workflow wraps your task description in a structured prompt that teaches the agent a proven approach. Instead of the agent figuring out how to tackle your request from scratch, the workflow provides a step-by-step protocol that leverages RepoPrompt's context tools at each stage. Select a **What are we building?** card or use the **Workflow** selector above the message editor, then type your task. Your submitted message is wrapped in that template; the selection is cleared after submission. See [Workflow Templates](https://repoprompt.com/docs/1.6.0/sessions/workflow-templates/) for the interface walkthrough, and choose the [execution location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/) before sending. Agent Mode running an Investigate workflow with Context Builder, Oracle, and file reads *Note: This screenshot is a historical capture illustrating an earlier build's Investigate session.* ### Built-in Workflows Built-in workflows appear in the Agent Mode workflow picker in the following display order (`RepoPromptBuiltInAgentWorkflow.displayOrder`). Agent Mode sessions also support four specialized sub-agent roles: **Pair** (default when `model_id` is omitted in `agent_run`, for interactive pair programming and complex tasks), **Engineer** (balanced implementation), **Explore** (read-only reconnaissance), and **Design** (architecture and design critique producing markdown documents under `docs/`). #### Orchestrate Plans a complex task, decomposes it into discrete work items, and dispatches sub-agents (`pair`, `engineer`, `design`, `explore`) to implement each one. The orchestrator stays lean — it coordinates and monitors, while worker agents handle the actual implementation in fresh context windows. Works with both UI-started and MCP-started sessions. **Flow:** Workspace verification → Contextualize task & Context Builder (`plan` + export) → Decompose into work items → Dispatch sub-agents → Monitor and verify #### Deep Plan Produces a polished, ready-to-execute architectural specification at `docs/plans/-.md` without implementing code. The workflow asks for your preferred involvement level (**Up front**, **Mid-flow**, or **Hands-off**), dispatches parallel `explore` agents across workspace seams, external research, and prior art, runs Context Builder (`plan` mode with export) to build a coverage ledger, dispatches a `design` agent to write an independent critique under `docs/reviews/`, and performs a fidelity-preserving editorial pass. **Flow:** Involvement decision (`ask_user`) → Map seams (`explore` agents) → Scaffold plan → Context Builder (`plan` + coverage ledger) → Design critique (`design` agent) → Editorial polish & fidelity verification #### Optimize Runs a delegation-first, evidence-driven performance optimization loop. The agent scouts bottleneck candidates with parallel `explore` agents, plans debug-gated instrumentation and a baseline procedure via Context Builder, dispatches a `pair` agent to capture baseline metrics in a persistent scoreboard (`prompt-exports/optimize--runs.md`), and iterates one attributed change at a time — consulting the Oracle after each run until the target metric is met, diminishing returns are reached, or the 5-iteration cap is hit. **Flow:** Bottleneck scouting (`explore` agents) → Plan metrics & instrumentation (Context Builder) → Land debug instrumentation & baseline (`pair` agent) → Serial optimization loop (Plan → Implement & measure → Verify scoreboard → Consult Oracle) → Final rollup #### Plan & Build The comprehensive end-to-end implementation workflow. The agent does a quick scan of your codebase, calls Context Builder to gather deep context and generate an architectural plan, refines the plan through Oracle Chat when ambiguities arise, and then implements the solution directly. **Flow:** Quick scan → Context Builder (with `plan`) → Refine with Oracle Chat → Implement with editing tools #### Review Surveys your git changes, determines the comparison scope (uncommitted, staged, vs `main`, etc.), and uses Context Builder to produce a thorough code review grounded in your full codebase — not just the diff. **Flow:** Survey git state → Confirm scope → Context Builder (with `review`) → Clarify findings via Oracle if needed #### Refactor Analyzes your code for redundancies and complexity using parallel `explore` scouts and Context Builder's `review` mode, generates an incremental refactoring plan via Context Builder's `plan` mode, and dispatches `pair` or `engineer` sub-agents to implement improvements step by step while verifying that existing behavior and tests are preserved. **Flow:** Scope & analyze (`explore` + Context Builder `review`) → Plan improvements (Context Builder `plan`) → Decompose & dispatch (`pair`/`engineer`) → Verify tests and diffs #### Investigate Systematic codebase exploration for debugging and root-cause analysis. The current workflow template calls for read-only source inspection while creating and updating an investigation report; it explicitly rules out source-code changes. The coding agent triages symptoms into `docs/investigations/-.md`, optionally dispatches `explore` agents for git blame archaeology and external research, uses Context Builder for broad discovery, dispatches a `pair` investigator to test hypotheses, and synthesizes findings with the Oracle until the root cause is confirmed with line-level evidence. **Flow:** Triage & scaffold report → External fact-gathering (`explore`) → Broad discovery (Context Builder) → Deep investigation (`pair`) → Oracle synthesis & final report #### ChatGPT Export Builds focused context for your task using Context Builder (`clarify` mode), checks selection and token counts, and exports a self-contained Markdown prompt file under `prompt-exports/`. Use it with a model available in ChatGPT or another external AI service for a second opinion; the export does not select or grant access to a model. See [How Do I Find the ChatGPT Pro Interface?](https://repoprompt.com/docs/1.6.0/faq/chatgpt-pro/) for the browser workflow, account/model distinction, and how to return the analysis to a coding session. **Flow:** Classify intent → Context Builder (`clarify` mode) → Verify workspace context → Export prompt file to `prompt-exports/` ### Interview Mode Before launching into a workflow, you can enable **Interview Mode** to have the agent ask clarifying questions first. This ensures the agent fully understands the task requirements, edge cases, and constraints before it starts working. Toggle it from the agent settings — when enabled, the agent will conduct a brief interview to align on the task definition before proceeding with the selected workflow. ### Why Context Matters Coding agents are convenient but fundamentally limited by how they gather context. When you prompt an agent, it must understand your problem and codebase from scratch — searching with grep, reading small slivers of files, and starting to make changes before fully understanding the code. By the time the agent orients itself, its context window is filled with tool calls, search results, and irrelevant code, leaving less room for actual reasoning. This matters because models have an *effective* context window that's smaller than the advertised one. Most models perform well in the 64–128k token range, but going beyond that degrades reasoning ability significantly. Every token spent on orientation is a token not spent on solving your problem. RepoPrompt's workflow commands solve this by separating **discovery** from **implementation**. The Context Builder handles the heavy lifting of finding and curating relevant files, so the agent receives complete, well-organized context upfront — and can spend its entire thinking budget on the solution. Read more: [Context Over Convenience](https://repoprompt.com/blog/context-over-convenience) Context Builder onboarding showing the two-stage pipeline and built-in workflows *Note: This onboarding screenshot is a historical capture showing an earlier subset of built-in workflows.* ### The Context Builder Pipeline Every workflow is built around the Context Builder — a two-stage intelligence pipeline: 1. **Stage 1 — Discovery Agent:** A specialized model explores your entire codebase, identifies relevant files, and curates a token-budgeted selection. It uses codemaps (concise API signatures) and line slices to maximize context within the allocated budget 2. **Stage 2 — Analysis Model:** A powerful model receives the curated context and produces deep analysis — architectural plans, code reviews, or answers to questions — grounded entirely in your actual code The discovery agent is deliberately non-opinionated: it gathers facts and relationships without biasing toward a particular solution. This ensures the analysis model gets a complete, neutral picture of the relevant codebase before reasoning about what to do. ### Oracle Chat Oracle Chat is a curated context window shared between the agent and a powerful reasoning model. It leverages RepoPrompt's best practices for prompting reasoning models — optimized file selection, codemaps, and line slices — to get optimal insights, plans, and reviews. #### How It Works The Oracle sees a carefully curated selection of your codebase — not raw grep results or piecemeal file reads, but the precise files and slices relevant to the question. The pipeline: 1. The agent describes what it needs to know 2. Context Builder curates the most relevant files within a token budget 3. The Oracle receives this optimized context and reasons deeply over it 4. The answer flows back to the agent, which continues working with new understanding Oracle Chat maintains a conversation — the agent can ask follow-up questions in the same session, building on previous answers without re-running discovery each time. #### Shared Context, Always Current Agent Mode automatically tracks every file the agent reads and keeps the Oracle's selection in sync. The Oracle is never less informed than the agent — it always has at least the same files the agent has seen, plus whatever additional files Context Builder discovers during its research. The Oracle's strength is *context density*. Rather than working from whatever happens to be in the agent's context window, Context Builder curates the most relevant files for each specific question — pulling in related code the agent may not have encountered yet. This targeted curation is what enables the deepest insights. #### When Agents Use Oracle Chat - **During /rp-build:** Clarifying architectural patterns, edge cases, or how existing code handles similar situations - **During /rp-investigate:** Testing hypotheses about a bug's root cause with cross-file reasoning - **During /rp-refactor:** Understanding dependencies and usage patterns before proposing changes - **Mid-implementation:** When the agent needs to understand how something works before editing it #### Multi-Oracle Rosters (Parallel Second Opinions) You are not limited to a single reasoning model. In **Settings → Agent Mode → Agent Models**, you can configure an **Oracle Roster** comprising 1 Primary Oracle plus up to 4 additional models (up to 5 models total). When an agent calls `ask_oracle` or an MCP client invokes `oracle_send`, RepoPrompt queries all roster models in parallel against the exact same curated context package. Responses return the primary analysis alongside `` with automated reconciliation guidance: - Where models agree, your agent proceeds with higher confidence. - Where recommendations diverge, the agent evaluates the trade-offs against the codebase rather than blindly following a single model's blind spots. For named configurations exposed through MCP, see [Oracle Model Presets](https://repoprompt.com/docs/1.6.0/settings/model-presets/). ### Customizing Workflows You can toggle built-in workflows on or off, clone them as starting points for your own, or create entirely new ones from scratch. Open the **Configure...** option at the bottom of the Workflow dropdown to manage your workflow list. ### Use workflow instructions from an external client Related workflow instructions are available for external coding agents through commands such as `/rp-build` and `/rp-review`. Install the MCP or CLI variant for your client; the selected destination determines whether they are stored as skills or prompt files. Connecting to the MCP server alone does not install those instructions. See [MCP Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/) for the catalog and locations. :::tip **Which Workflow?** Start with **Plan & Build** for most tasks. Use **Review** before committing changes. Reach for **Investigate** when debugging tricky issues that need systematic exploration. ::: --- ## CE Version 1 ### Community Edition Version 1.x Series The Community Edition 1.x series is the first release in the Community Edition series. RepoPrompt CE is a native macOS app for orchestrating coding agents with a focus on context engineering. It builds an agent harness around an MCP server, giving you a shared place to prepare repository context, connect compatible CLI agents, run focused tasks, and inspect the work they produce. The goal is simple: make it easier to give agents the right context and keep multi-step engineering work understandable. #### Key Features in Community Edition 1.x - Native macOS workspace for context engineering and agent orchestration. - MCP-based harness for integrating compatible CLI agents. - Repository-aware context selection, search, diffs, and worktree workflows. - Public Sparkle update channel for signed, notarized releases. - Fully open source and free to use. #### 1.6.0 - October 11, 2026 RepoPrompt CE v1.6.0 (build 39) brings major Agent workflow improvements, new model choices, and a smoother app experience. **Highlights** - **Overseer and Agent sessions:** Opt-in Overseer management now includes lanes, role-aware discovery, and stronger recovery after relaunch or compaction. — @baron · #1080↗ · @crstdr · #1131↗ · @crstdr · #1308↗ - **More model choices:** Adds GPT-6.1 Sol and Claude Sonnet 5.5, refreshes Cursor models and effort choices, and adds usage-balanced routing for Codex and Claude plans. — @baron · #1135↗ · @dsebban · #1160↗ · @baron · #1265↗ - **Codex Computer Use:** Opt-in computer interaction in Codex chats, with local tab consent and quieter companion activity. — @crstdr · #1253↗ · @crstdr · #1284↗ - **MCP and Context Builder reliability:** Safer bootstrap handshakes, clearer startup binding results, and a way to talk to in-app Overseers without taking them over. — @baron · #1199↗ · @baron · #1200↗ · @crstdr · #1252↗ - **Code Maps and performance:** Code Maps work in non-Git folders; incremental indexing and idle-work fixes reduce background load. — @crstdr · #994↗ · @baron · #1085↗ · @dsebban · #1259↗ **[Full Changelog for 1.6.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.5.0...v1.6.0)** #### 1.5.0 - September 25, 2026 **What's Changed** - MCP fix: skip deletion fencing for uncatalogued missing paths — @w-winter · #980↗ - Add support for multiple Oracles — @dsebban · #884↗ - Fix: prevent codemap indexing page restart on git churn — @w-winter · #984↗ - Fix selection mirror wedge recovery — @mplibunao · #472↗ - Agent Session Oversight — @crstdr · #872↗ - Refactor Agent Session Oversight internals (stacked on #872) — @baron · #938↗ - Fix completed credential migration and blocked update recovery — @baron · #988↗ - Fix Sparkle startup update isolation — @baron · #992↗ - Fix Model Presets with multiple Oracles — @w-winter · #1000↗ - Put workspace first in window titles — @crstdr · #998↗ - Reuse matching workspaces when opening folders — @aAtila · #924↗ - Fix workspace root removal and discovery readiness — @aAtila · #986↗ - chore: approve contributor luqmannurhakimbazman — @najibninaba · #1006↗ - Migrate release artifact actions to Node 24 — @baron · #1021↗ - feat(agent-mode): add Devin CLI provider — @dsebban · #999↗ - Expand sidebar checkbox hit targets — @aAtila · #1008↗ - Fix seeded worktree publication deadlock and watchdog terminal errors — @luqmannurhakimbazman · #1003↗ - Fix Context Builder settled Oracle replies after primary failure — @dsebban · #1011↗ - Fix cancellation handoff and Context Builder watchdog reliability — @dsebban · #1013↗ - Make the OpenCode thinking level configurable — @crstdr · #1009↗ - Make the subagent wait configurable in Settings — @crstdr · #1005↗ - Fix: Clamp Context Builder budget slider values — @sentry[bot] · #834↗ - Fix: Cache AgentModeViewModel binding snapshot to prevent O(N²) app hang — @sentry[bot] · #990↗ - Fix JSON-valued MCP experimental capabilities — @baron · #1022↗ - Fix Tip publisher API authentication and latest convergence — @baron · #1024↗ - Fix composer cursor jumping during typing — @jsmcx · #1025↗ - Add persistent global model routing with Jev — @baron · #1031↗ - Fix post-migration Keychain item creation — @baron · #1034↗ - Fix Agent Mode sidebar render-loop performance — @baron · #1035↗ - Improve agent orchestration observability and history analytics — @baron · #1036↗ - Add Claude Opus 5.5 model choices — @baron · #1053↗ - Update bundled Codex app-server to 0.156.0 — @baron · #1051↗ - Preserve dirty Copy and Chat overlays during Agent Models changes — @baron · #574↗ - Stop MCP read_file from inventing a one-line success — @luqmannurhakimbazman · #1015↗ - Reduce composer keystroke latency — @baron · #1043↗ - Diagnose canonical workspace state at Agent admission — @baron · #1044↗ - Add bounded workspace projection decode measurements — @baron · #1046↗ - Make physical file reads cancellation-responsive — @mplibunao · #983↗ - Show captured Context Builder behavior during active runs — @bcgalvin · #1028↗ - perf(git): bound diff cache retention with LRU eviction — @morluto · #459↗ - Add bounded MCP lifecycle diagnostics for teardown investigation — @baron · #1048↗ - Make passive appcast callback main-actor contract explicit — @sentry[bot] · #1030↗ - Add Jev multi-question judgment foundation — @baron · #1045↗ - Fix Model Router persistence and refresh routing models — @baron · #1052↗ - Stabilize workspace lifecycle regression tests (#1054) — @baron · #1055↗ - Fix Context Builder prerequisite error classification — @bcgalvin · #1049↗ - Update bundled Codex app-server to 0.156.1 — @baron · #1056↗ - Preserve file authority across context binding — @mplibunao · #982↗ - Add MCP controls for agent session pins and manual order — @baron · #1058↗ - Guard protected Agent tabs during workspace replay — @baron · #1059↗ - Fix app hang by caching sorted model options — @sentry[bot] · #1060↗ - Add independent Jev Auto effort for Codex and Claude — @baron · #1062↗ - Add automatic APFS CoW cloning for app-managed worktrees — @baron · #1064↗ - Prepare v1.5.0 stable release metadata — @baron · #1066↗ - fix(mcp): allow background-tab selection mirrors to complete — @w-winter · #1069↗ - fix(agent-mode): apply Auto effort to Claude MCP runs — @baron · #1070↗ **New Contributors** - luqmannurhakimbazman made their first contribution. - jsmcx made their first contribution. - bcgalvin made their first contribution. **[Full Changelog for 1.5.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.4.1...v1.5.0)** #### 1.4.1 - September 7, 2026 **What's Changed** - Fix split-root Stable release metadata — @baron · #911↗ - Test MCP stdio and terminal commit barriers — @baron · #912↗ - Fix: codemaps to index nested repo worktree sources — @w-winter · #913↗ - Fix Tip recovery after Stable 1.4.0 — @baron · #914↗ - Harden Tip publisher release observation — @baron · #920↗ - Add Claude Fable 5.1 to the Claude Code model catalogs — @datawisebets · #932↗ - Authenticate Tip protected-main preflight — @baron · #925↗ - Fix (MCP) - align context routing with active workspace — @w-winter · #936↗ - Fix: out-of-bounds access due to stale workspace index after async yield — @sentry[bot] · #929↗ - Add Claude Fable Latest and normalize model picker fonts — @w-winter · #934↗ - Fix Tip release publication races — @baron · #943↗ - Fix (HistoryMCP) - prevent crash in buildGroups due to force-unwrap — @sentry[bot] · #942↗ - Fix: Swift overflow when converting negative st_dev to UInt64 — @sentry[bot] · #937↗ - Fix: Sanitize AI narration text to prevent SwiftUI crashes — @sentry[bot] · #940↗ - Fix: App hang due to expensive Codex model display name computation — @sentry[bot] · #941↗ - Fix: Context menu crash on dynamic item changes — @sentry[bot] · #939↗ - Prefer Grok's direct model parser when configOptions accompany models — @datawisebets · #933↗ - Fix file search freshness after Add Folder — @aAtila · #927↗ - Fix duplicate workspace consolidation persistence — @crstdr · #915↗ - Fix release provisioning profile permissions — @baron · #948↗ - Remove artificial timeouts from Tip workflow — @baron · #950↗ - Keep new windows eligible for Merge All Windows — @nickdavis · #853↗ - Fix InterceptingWindowDelegateProxy unrecognized selector crash — @sentry[bot] · #877↗ - Fix: EXC_BREAKPOINT in duplicate workspace cleanup — @sentry[bot] · #841↗ - Fix GitWorktreeDefaultPathPlanner O(N^2) hang — @sentry[bot] · #891↗ - Reduce repeated transcript snapshot access in row construction — @sentry[bot] · #820↗ - Index hidden-session slice paths during rebase planning — @sentry[bot] · #839↗ - Give Codex model options a consistent sort order — @sentry[bot] · #813↗ - Preserve competing files during exclusive creation — @baron · #964↗ - Derive session deletion targets from validated files — @baron · #959↗ - Preserve settings after failed backup recovery — @baron · #958↗ - Retain physical authority for protected file mutations — @baron · #969↗ - Revalidate worktree identity before alternate-root operations — @baron · #965↗ - Preserve workspace affinity across MCP reconnects — @baron · #966↗ - Prevent load-time repair from resurrecting deleted sessions — @baron · #967↗ - Retain process ownership until child termination settles — @baron · #968↗ - Preserve settings across schema migration and recovery retries — @baron · #970↗ - Fix FSEvents delivery liveness — @baron · #713↗ - Enforce MCP readiness caller deadlines — @baron · #711↗ - Fix qualified reads stalling on unrelated roots — @mplibunao · #889↗ - Resolve advertised Codex Max and Ultra effort selections — @nickdavis · #953↗ - Allow selecting a local Codex runtime — @crstdr · #956↗ - Fix Context Builder shutdown during app termination — @mplibunao · #955↗ - Fix concurrent same-workspace Agent admission — @mplibunao · #897↗ - fix: support verified Cursor agent ACP entrypoint — @najibninaba · #902↗ - feat(agent-mode): add Cursor Effort and Speed controls — @najibninaba · #960↗ - Prevent concurrent settings writes from overwriting newer data — @baron · #973↗ - Protect large prompt exports from watchdog disconnects — @mplibunao · #898↗ - Fix workspace loading, cleanup, and settings preservation — @baron · #974↗ - Fix OpenCode launch validation for admin-writable Homebrew Cellar paths — @AmrMohamad · #976↗ - Make bundled Codex predictable and upgrade to 0.153.4 — @baron · #979↗ - Add Google Antigravity ACP support — @z23cc · #975↗ - Prepare v1.4.1 release metadata — @baron · #978↗ **New Contributors** - AmrMohamad made their first contribution. - z23cc made their first contribution. **[Full Changelog for 1.4.1](https://github.com/repoprompt/repoprompt-ce/compare/v1.4.0...v1.4.1)** #### 1.4.0 - August 30, 2026 **What's Changed** - Scale MCP read_file concurrency to machine capacity — @baron · #798↗ - Globalize Context Builder Settings behavior and make Analysis Budget independent — @w-winter · #801↗ - Agent Mode: eliminate app hang from AgentImageInputAdapter init — @sentry[bot] · #779↗ - Stabilize AgentRunWorktreeStartTests production-capture selection race (#420) — @moonray · #430↗ - Dismiss tooltips when owner windows change lifecycle — @0xNino · #564↗ - Add multi-select + bulk actions to Agent Mode chats — @w-winter · #802↗ - Fix: Unify exact read and mutation paths — @w-winter · #800↗ - Add stored prompt management controls — @w-winter · #799↗ - Fix: decode legacy mutation journal status — @w-winter · #815↗ - Prevent ephemeral workspace leaks and add safe bulk cleanup — @baron · #814↗ - Route direct-headless agents through existing worktrees — @nickdavis · #761↗ - Add Grok Build CLI as an ACP Agent Mode provider — @datawisebets · #817↗ - Fix: bound MCP structure settlement recovery — @w-winter · #822↗ - Fix: expose global skills to Codex agents — @w-winter · #824↗ - Add inline file browser to manually add files/codemaps to selected set in Context Composer — @w-winter · #823↗ - Fix Codex session disconnect during worktree rebinding — @baron · #826↗ - Add Grok Build reasoning-effort selection — @datawisebets · #825↗ - Fix Codex wait-agent watchdog liveness — @baron · #833↗ - Fix replace-all matching with reused full-file indexes — @morluto · #737↗ - Add Grok Build CLI to Oracle and built-in chat models — @dsebban · #838↗ - test: stabilize worktree API smoke and agent-run startup — @dsebban · #832↗ - Add a Codex project hook approval flow to Agent Mode — @mplibunao · #678↗ - Bound release network operations and recover Sentry finalization — @baron · #579↗ - Fix bind_context active workspace routing — @nickdavis · #812↗ - Add session ID copying to Agent Mode sidebar menus — @aAtila · #846↗ - Reject rootless working_dirs tab bindings — @nickdavis · #835↗ - Enable Codex apps with runtime 0.149.0 — @nickdavis · #851↗ - Harden Apple identity migration bridge — @baron · #857↗ - Fix: App hang in MessageTimestampFormatterCache.CacheKey.init — @sentry[bot] · #819↗ - Include session title in handoff prompt — @baron · #747↗ - Fix Grok Oracle returning progress text instead of an answer — @dsebban · #856↗ - Harden identity rollover runtime safety — @baron · #868↗ - Add dormant identity transition release tooling — @baron · #869↗ - Enable Tip identity transition rehearsal — @baron · #870↗ - Fix Tip identity transition release credentials — @baron · #873↗ - Make Tip identity rollout dispatches reliable and truthful — @baron · #874↗ - Fail Tip identity credential errors before staging — @baron · #876↗ - Fix Tip staged rollout authority — @baron · #879↗ - Fix Tip signed artifact handoff — @baron · #880↗ - Fix Tip appcast generation without predecessors — @baron · #883↗ - Enable Tip identity transition role — @baron · #885↗ - Fix Tip transition stage identity validation — @baron · #888↗ - Fix Tip signer identity projection — @baron · #890↗ - Separate sidebar command progress from bulk selection UI — @aAtila · #878↗ - Refactor Apple identity transition release pipeline — @baron · #894↗ - Replace Tip release machinery with a direct protected-main publisher — @baron · #895↗ - Restore automatic Tip publication for all rollout roles — @baron · #896↗ - Remove manual Tip rollout role input — @baron · #901↗ - Refactor CI tests into deterministic contract and integration lanes — @baron · #899↗ - Fix redundant Tip package notarization — @baron · #905↗ - Fix Tip package signing key authorization — @baron · #907↗ - Fix: restore global Codex instructions in Agent Mode — @w-winter · #906↗ - Refactor test suite to remove low-value and timing-dependent coverage — @baron · #908↗ - Fix CLI single-shot selector routing — @mplibunao · #904↗ - Release v1.4.0 — @baron · #909↗ **New Contributors** - 0xNino made their first contribution. **[Full Changelog for 1.4.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.3.0...v1.4.0)** #### 1.3.0 - August 11, 2026 **What's Changed** - Trace worktree startup stall in shard 2 — @baron · #721↗ - Remove the 500-tab background Agent limit — @baron · #720↗ - Use scoped locking for ACP async state transitions — @baron · #719↗ - fix: require authoritative context builder completion — @w-winter · #722↗ - feat: show sessionless compose tabs in agent chats — @w-winter · #716↗ - Fix automatic Agent Mode tab eviction — @baron · #723↗ - Cancel superseded pull request CI runs — @morluto · #741↗ - P0: Protect live Agent session identity during admission — @baron · #742↗ - Report preset save failures and roll back non-durable edits — @morluto · #733↗ - Fix workspace authority conflict recovery — @baron · #744↗ - Harden legacy defaults collection during startup — @baron · #745↗ - Prevent cancelled CLI requests from stalling or spawning — @morluto · #724↗ - Prevent cancelled tasks from entering an unlocked AsyncMutex — @morluto · #725↗ - Self-heal workspace authority revision races — @baron · #746↗ - Settle cancelled Codex stderr waiters promptly — @morluto · #738↗ - Allow MessageReaper to tear down with queued messages — @morluto · #734↗ - Synchronize transcript debug instrumentation callbacks — @morluto · #736↗ - Clear transcript refresh signatures after tab removal — @morluto · #739↗ - Migrate RepoPromptShared to Swift 6 — @baron · #753↗ - Fence tool-card presentation derivation from render recomputation — @baron · #754↗ - Establish neutral agent execution contracts — @baron · #756↗ - fix: make agent read_file selection converge — @w-winter · #755↗ - Agent Mode: classify terminal failures at settlement — @baron · #759↗ - Agent Mode: extract run-attempt lifecycle authority — @baron · #763↗ - Make agent run identity teardown stale-safe — @baron · #764↗ - Harden conductor control-plane resilience — @baron · #765↗ - Bundle Codex 0.147.0 and fix exec permissions — @nickdavis · #748↗ - Add durable conductor build cache — @baron · #766↗ - Harden workspace-switch runtime ownership transfer — @baron · #767↗ - fix(mcp): add Sonoma async frame compatibility barrier — @baron · #768↗ - Agent Mode: bind terminal settlement to exact sessions — @baron · #772↗ - Agent Mode: hoist terminal attachment disposition — @baron · #773↗ - Agent Mode: detach Claude coordinator from view model — @baron · #776↗ - feat(agent-mode): add pinned Claude Opus 4.8 picker model — @aAtila · #774↗ - Bound untrusted Agent Mode tool names before normalization — @baron · #770↗ - Enforce one accounting identity per prompt file — @baron · #777↗ - Agent Mode: centralize Claude settlement authority — @baron · #778↗ - feat: streamline Context Composer entry points — @w-winter · #783↗ - Agent Mode: extract top-level tab session — @baron · #784↗ - Update APPROVED_CONTRIBUTORS — @baron · #785↗ - Agent Mode: share transient execution classification — @baron · #786↗ - Oracle: extract headless streaming runtime — @baron · #787↗ - Prompt: extract stored-prompt persistence boundary — @baron · #788↗ - Reconstruct diff chunks without repeated array shifts — @morluto · #735↗ - Add focused-build cost reporting and high-output conductor diagnostics — @morluto · #521↗ - fix(agent-mode): eliminate O(N) snapshot copies in handoffConfig — @sentry[bot] · #780↗ - Preserve Context Builder pending context through routing — @morluto · #566↗ - Add built-in workflow parity to direct headless mode — @nickdavis · #760↗ - Agent Mode: share Codex transient execution classification — @baron · #791↗ - Agent Mode: share Claude transient execution classification — @baron · #792↗ - Agent Mode: share ACP transient execution classification — @baron · #793↗ - Add operation-level MCP concurrency evidence — @baron · #794↗ - Release v1.3.0 — @baron · #797↗ **[Full Changelog for 1.3.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.2.0...v1.3.0)** #### 1.2.0 - August 3, 2026 **What's Changed** - Surface Code Map recovery exhaustion — @baron · #689↗ - Prevent file-action watchdog stalls during mutation I/O — @baron · #688↗ - Headless runtime M1: add runtime and catalog foundation — @provencher · #640↗ - Fix Oracle heartbeat liveness tracking — @dsebban · #696↗ - Fix App Hang: Disable text checking in AttributedTextView — @sentry[bot] · #697↗ - Fix App Hang: Optimize string prefix checks — @sentry[bot] · #683↗ - Fix AnchorGeometryView app hang — @sentry[bot] · #685↗ - Fix agent workspace performance regression — @baron · #680↗ - Improve ChatGPT login resilience and managed sign-out — @baron · #698↗ - Fix EXC_BREAKPOINT from dictionary mutation during iteration — @sentry[bot] · #693↗ - Headless runtime M2: move workspace/context authority — @provencher · #643↗ - Add opt-in Codex memories setting — @baron · #691↗ - Fix Tip socket ownership startup race — @baron · #699↗ - Headless runtime M3: migrate read and discovery families — @provencher · #657↗ - Keep failed CI from evicting Tip builds — @baron · #700↗ - M4: protect MCP mutations and security boundaries — @provencher · #660↗ - Provision Keychain for packaged release smoke — @baron · #701↗ - Remove test contract ledger system — @baron · #704↗ - Stabilize ledger-free CI routing and codemap contracts — @baron · #705↗ - [6/8] M5: move AI, Agent, Context Builder, and interaction into domain runtime — @provencher · #664↗ - Fix M5 credential pruning type inference — @baron · #706↗ - Optimize Agent Mode sidebar projection caching — @baron · #703↗ - Fix protected mutation commit boundary — @baron · #707↗ - Add Compose: context inspector inspired by RP Classic — @w-winter · #535↗ - [7/8] M6: Add direct headless MCP runtime — @provencher · #674↗ - M7: complete headless MCP runtime cutover — @provencher · #677↗ - perf: coalesce compose inspector refresh work — @baron · #709↗ - Fix current-main CI blockers after M7 merge — @baron · #712↗ - Release v1.2.0 — @baron · #714↗ **[Full Changelog for 1.2.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.1.2...v1.2.0)** #### 1.1.2 - July 30, 2026 **What's Changed** - Add semantic text-direction roles for app surfaces — @baron · #670↗ - Clamp Markdown selections before TextKit restoration — @baron · #671↗ - Preserve inline-code direction in mixed RTL Markdown — @baron · #672↗ - Rebase PR #70: Linkify Agent Mode prose URLs — @dah · #684↗ - Headless runtime M0: freeze contracts and evidence gates — @provencher · #639↗ - Fix Data.WritingOptions conflict in writeHandoffPayload — @sentry[bot] · #690↗ - Fix MCP settlement across Codex turns and file mutations — @provencher · #687↗ - Release v1.1.2 — @baron · #692↗ **[Full Changelog for 1.1.2](https://github.com/repoprompt/repoprompt-ce/compare/v1.1.1...v1.1.2)** #### 1.1.1 - July 29, 2026 **What's Changed** - Fix Codex app-server tool override policy — @baron · #603↗ - Add Codex app-server schema drift gate — @baron · #604↗ - perf: reduce codemap full-load latency — @provencher · #600↗ - build: bundle pinned Codex runtimes — @baron · #605↗ - Fix worktree-bound Codex app-server startup — @mplibunao · #568↗ - Fix bundled Codex release signing — @baron · #606↗ - Stabilize synthetic watcher integration tests — @baron · #607↗ - Optimize Swift and TypeScript CodeMap pipelines — @provencher · #608↗ - Add Agent Mode session handoff prompt — @baron · #610↗ - Fix packaged MCP smoke ownership checks — @baron · #611↗ - feat: make bundled Codex runtime authoritative — @baron · #612↗ - Make Codex session routing deterministic per tab — @baron · #614↗ - Add per-root Code Map generation controls — @provencher · #609↗ - feat(deep-plan): treat the context_builder export as a preservation baseline — @w-winter · #615↗ - Bound Codex app-server liveness and silent hangs — @baron · #617↗ - fix(mcp): preserve caller binding during agent runs — @w-winter · #616↗ - Fix Codex legacy thread resume by forwarding rollout path — @baron · #618↗ - Fix MCP reconnect abort and Git artifact fence spin — @baron · #613↗ - Replace codemap projections with root-local incremental graphs — @provencher · #621↗ - Fix Codex session tenacity recovery — @baron · #623↗ - Fix release codemap event type visibility — @baron · #624↗ - Optimize Codex thread startup memory policy — @baron · #625↗ - Preserve Codex completion across active reattach — @baron · #626↗ - Add Claude Opus 5 support — @baron · #627↗ - fix(agent-run): improve respond validation diagnostics — @w-winter · #622↗ - Fix stale codemap proof reclassification — @baron · #628↗ - Make async test oracles deterministic — @provencher · #629↗ - Automate guarded Codex runtime update candidates — @baron · #633↗ - Rebase 315/316 collapse nested threads and clean up provider conversations — @dah · #630↗ - Fix Finder launch and install commands when only Xcode beta is installed — @dah · #631↗ - Restore Codex messages rejected before dispatch — @baron · #619↗ - Update bundled Codex to 0.145.0 — @baron · #635↗ - Point fork dependencies at RepoPrompt organization — @provencher · #638↗ - Fix Codex watchdog for silent long-running tools — @baron · #636↗ - Add PR-ready validation timing receipts — @baron · #634↗ - Add MCP concurrency evidence telemetry — @baron · #632↗ - Improve tip update details — @baron · #637↗ - Show build numbers in Sparkle update alerts — @baron · #641↗ - Fix MCP read timeout settlement without bridge disconnect — @baron · #644↗ - Fix CollapsibleUserMessage performance on large messages — @sentry[bot] · #601↗ - Fix bundled Codex V8 JIT entitlements — @baron · #647↗ - Keep Tip update alerts compact — @baron · #656↗ - Add reusable Agent Mode handoff instructions — @erauner12 · #645↗ - Refresh approved contributors — @provencher · #572↗ - Fix Code Map stalls and manifest write amplification — @baron · #659↗ - Harden Code Map recovery after performance cutover — @baron · #661↗ - Fix Tip release optimizer ownership crash — @baron · #663↗ - Fix Codex watchdog for composite waits — @baron · #667↗ - Fix path-scoped Git artifact publication freezes — @baron · #668↗ - Fix duplicate physical root label traps — @erauner12 · #673↗ - Include steering text in Agent Mode wait interruptions — @erauner12 · #669↗ - Fix CodeHighlighter cache race condition — @sentry[bot] · #676↗ - Fix: Prevent duplicate worktree path crash — @sentry[bot] · #553↗ - Fix dirent struct copy causing EXC_BAD_ACCESS in FileSystemService — @sentry[bot] · #602↗ - Optimize Agent Mode: Transcript snapshot access — @sentry[bot] · #658↗ - Eliminate app hang from synchronous file open — @sentry[bot] · #589↗ - Release v1.1.1 — @baron · #682↗ **New Contributors** - w-winter made their first contribution. **[Full Changelog for 1.1.1](https://github.com/repoprompt/repoprompt-ce/compare/v1.1.0...v1.1.1)** #### 1.1.0 - July 21, 2026 **What's Changed** - fix(release): support Sentry org:ci tokens — @baron · #551↗ - refactor(workspace): isolate path policy core — @provencher · #559↗ - Complete Agent Models workspace follow-ups — @crstdr · #545↗ - fix: update Codex app-server text payload key — @mplibunao · #450↗ - fix(mcp): avoid task-group teardown abort in runTransport retry backoff — @pnascimento9596 · #517↗ - Fail Codex child sessions closed when RepoPrompt MCP provisioning or routing never confirms — @mplibunao · #532↗ - Add durable MCP watchdog attribution — @baron · #567↗ - Stream Context Builder progress over standard MCP — @OCWC22 · #510↗ - Harden Context Builder MCP routing readiness — @baron · #569↗ - Preserve MCP connection on code structure timeout — @baron · #570↗ - Fix authenticated tip release lookup — @baron · #571↗ - perf(codemap): reduce manifest write amplification during indexing — @morluto · #487↗ - Avoid global manifest scans for access refreshes — @baron · #552↗ - fix: restore Sentry telemetry in Tip builds — @baron · #555↗ - perf(codemap): avoid repeated full-store scans when publishing manifests — @morluto · #488↗ - Make MCP watchdog deadlines independent of event ordering — @baron · #575↗ - Harden code-structure settlement lifecycle — @baron · #576↗ - Make MCP route confirmation and revocation authoritative — @baron · #577↗ - Bound MCP advisory progress backpressure — @baron · #578↗ - Bound agent session cleanup and preserve partial results — @baron · #582↗ - Bound history MCP work and preserve transport — @baron · #583↗ - Fix agent message bubble line counting performance — @sentry[bot] · #584↗ - Fix history tool catalog golden — @baron · #585↗ - Preserve codemap authority across publication retries — @baron · #586↗ - Fix Context Builder cancellation after discovery commit — @baron · #588↗ - Speed up Context Builder selection handoff — @baron · #591↗ - Fix Context Builder routing and settlement — @baron · #592↗ - Migrate CodeMap core to Swift 6 with exact official Tree-sitter pins — @provencher · #580↗ - Fix clean release dependency cloning — @baron · #596↗ - Remove Dart CodeMap support — @provencher · #597↗ - Release v1.1.0 — @baron · #599↗ **New Contributors** - pnascimento9596 made their first contribution. - OCWC22 made their first contribution. **[Full Changelog for 1.1.0](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.29...v1.1.0)** #### 1.0.29 - July 15, 2026 **What's Changed** - Make Context Builder model selection globally authoritative — @morluto · #463↗ - Prepare hosted app tests for optional sharding — @morluto · #440↗ - fix(agent-mode): stop tool-result updates from remounting unrelated cards — @morluto · #458↗ - Add RPCE maintainer guidance skill — @baron · #502↗ - Harden Sentry privacy and release metadata — @baron · #474↗ - Add scoped Agent Models settings — @crstdr · #275↗ - Fix debug provenance JSON validation — @provencher · #512↗ - Add title-adjacent Agent chat options menu — @baron · #516↗ - Fail closed on unsigned Tip appcasts — @baron · #497↗ - Fix Oracle selection packaging and mutation ingress stalls — @provencher · #520↗ - Enforce strict ledger validation for suite plans — @baron · #528↗ - Fix global settings schema rollback compatibility — @baron · #530↗ - Harden Sentry privacy and release promotion — @baron · #533↗ - Fix typed Context Builder prompt handoff (#526) — @mplibunao · #529↗ - Fix scoped Agent Models state integrity — @baron · #534↗ - Fix inactive-workspace Context Builder authority — @baron · #538↗ - Harden Git process launch lifecycle — @baron · #539↗ - Prevent recursive workspace path-index teardown overflow — @baron · #540↗ - Make TextKit external replacements undo-safe — @baron · #543↗ - Prevent duplicate workspace root ID crashes — @baron · #541↗ - Bound applied-index fallbacks and harden workspace autosave — @baron · #542↗ - Fix app hang during date formatting by pre-warming locale cache — @sentry[bot] · #438↗ - Harden transcript export against duplicate turn IDs — @sentry[bot] · #544↗ - Improve Tip build update notices — @baron · #537↗ - Harden Agent chat titlebar safety — @baron · #536↗ - Fix execution-location popover resize crash — @baron · #548↗ - Release v1.0.29 — @baron · #550↗ **New Contributors** - crstdr made their first contribution. - mplibunao made their first contribution. - sentry made their first contribution. **[Full Changelog for 1.0.29](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.28...v1.0.29)** #### 1.0.28 - July 10, 2026 **What's Changed** - Harden release packaged smoke timeout — @baron · #441↗ - Split RepoPrompt into thin executable and app target — @provencher · #437↗ - Add opt-in tip update channel and rolling publish workflow — @baron · #442↗ - Fix Tip build number override — @baron · #467↗ - Improve conductor worktree parallelism — @baron · #470↗ - Fix Context Builder teardown finalization — @baron · #448↗ - Update Codex support for GPT-5.6 models — @baron · #462↗ - Release v1.0.28 — @baron · #477↗ **[Full Changelog for 1.0.28](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.27...v1.0.28)** #### 1.0.27 - July 9, 2026 **What's Changed** RepoPrompt CE 1.0.27 is the public release for everything merged after v1.0.24. It includes the intended but unpublished v1.0.25/v1.0.26 payloads plus the follow-up CLI, test-harness, and Sentry release fixes needed to make this train safe for in-app updates. **App and Agent Mode** - History query MCP tools (`list_sessions`, `search`, `time`) with tunable idle threshold, per-day attribution, duration fixes, and review hardening. — @moonray · #303↗ - Enhanced Agent session search HUD behavior and archived-session visibility. — @baron · #397↗ - Faster, less noisy workspace switch load readiness. — @baron · #347↗ - Hardened agent CLI startup in fragile user environments. — @baron · #424↗ - Fixed git diff artifact export after alias authorization rejection. — @baron · #429↗ - Hardened build storm coordination and process cleanup. — @baron · #427↗ **Settings, CLI, and Developer Workflow** - Persist global defaults across restarts and propagate changes across windows. — @moonray · #418↗ - Speed up `dev-lint` SwiftLint discovery. — @baron · #428↗ - Recover CLI installation from stale App Translocation symlinks. — @amittell · #413↗ - Harden test harness behavior against hangs and waiter leaks. — @morluto · #435↗ **Telemetry and Release Reliability** - Integrated full Sentry telemetry. — @baron · #409↗ - Added release-pipeline dSYM generation and upload coverage. — @cameroncooke · #332↗ - Fixed Sentry-enabled release build coverage for the v1.0.26 attempt. — @baron · #433↗ - Refactored Sentry telemetry controls and added release coverage for official Sentry-enabled builds. — @baron · #436↗ - Release preparation for the unpublished v1.0.25 train and this final v1.0.27 publish. — @baron · #431↗ · @baron · #439↗ **New Contributors** - amittell made their first contribution. **[Full Changelog for 1.0.27](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.24...v1.0.27)** #### 1.0.24 - July 6, 2026 **What's Changed** - Add impacted XCTest lane and harden test tooling — @morluto · #374↗ - Refresh approved contributors — @provencher · #378↗ - fix(agent-mode): open live oracle from running tool card — @morluto · #358↗ - Stabilize CI app tests with sharding and lifecycle cleanup — @morluto · #379↗ - Polish agent sidebar worktree capsules (auto-naming, sizing, styling) — @provencher · #380↗ - Fix routed worktree inheritance for UI parents — @baron · #388↗ - Fix mutation tools when worktree scope is unavailable — @baron · #387↗ - Tail-window massive agent transcripts — @baron · #391↗ - Fix issue 390 targeted authority reconciliation — @baron · #392↗ - Add minimal Sentry runtime wiring — @baron · #393↗ - Release RepoPrompt CE 1.0.24 — @baron · #395↗ **[Full Changelog for 1.0.24](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.23...v1.0.24)** #### 1.0.23 - July 3, 2026 **What's Changed** - Add content-addressed codemaps and diff-seeded worktree startup — @provencher · #314↗ - Add Codex reasoning summary setting — @provencher · #336↗ - Collapse Interview toggle to icon-only — @baron · #321↗ - Refresh selected files popover UI and performance — @baron · #333↗ - [codex] Contain codemap selection decode failures — @provencher · #339↗ - Fix MCP token accounting freshness reporting — @provencher · #343↗ - Add Claude Sonnet 5 model support — @BetaFold3 · #338↗ - Start test-suite wallclock optimization reliability campaign — @provencher · #346↗ - build(telemetry): link Sentry conditionally and document privacy model — @cameroncooke · #323↗ - Resume inactive agent sessions when steering — @provencher · #353↗ - fix(agent-mode): stop listener leaks and orphaned Claude processes on close — @morluto · #319↗ - fix: omit nil Codex service tier — @dsebban · #317↗ - Fix Codex steer crash and resume handling — @provencher · #354↗ - Stabilize sidebar root updates during workspace switch — @baron · #351↗ - Add agent session switcher HUD — @baron · #352↗ - Fix MCP selection token freshness — @baron · #359↗ - Avoid applied-index hierarchy rebuilds for small deltas — @baron · #361↗ - Bump engineer role default to GPT-5.5 Medium — @baron · #364↗ - Fix crash restore settings persistence — @baron · #365↗ - Fix bound-tab token cache freshness — @baron · #367↗ - Prepare release 1.0.23 — @baron · #369↗ **New Contributors** - dsebban made their first contribution. **[Full Changelog for 1.0.23](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.22...v1.0.23)** #### 1.0.22 - June 28, 2026 **What's Changed** - Fix Context Builder worktree review selection authority and freshness — @provencher · #277↗ - keep @file tag paths pathful and non-absolute — @aAtila · #274↗ - build: Add Makefile help target — @cameroncooke · #272↗ - fix: resume MCP helper sessions after app restart — @clairernovotny · #286↗ - fix(claude-code): emit CLI identity preamble for GLM/z.ai backend — @moonray · #296↗ - Fix and modernize Codex agent_run transcripts — @provencher · #299↗ - Refresh approved contributors — @provencher · #300↗ - Fix symlinked global skill root readability — @BetaFold3 · #289↗ - Fix CE URL scheme routing — @baron · #101↗ - Restore Agent Mode Interview pill — @baron · #147↗ - Fix orphaned OpenCode ACP runtimes on tab teardown killing CPU memory — @morluto · #292↗ - Refresh approved contributors — @provencher · #302↗ - Fix Oracle and sub-agent role model selections resetting on restart — @datawisebets · #305↗ - Clarify sliced file selection summaries — @provencher · #262↗ - Surface OpenCode empty ACP completions — @baron · #310↗ - Prepare RepoPrompt CE 1.0.22 — @baron · #311↗ **New Contributors** - clairernovotny made their first contribution. - datawisebets made their first contribution. **[Full Changelog for 1.0.22](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.21...v1.0.22)** #### 1.0.21 - June 21, 2026 **What's Changed** - Stabilize workspace switch cleanup tests — @erauner12 · #263↗ - Refresh approved contributors — @provencher · #269↗ - Fix duplicate Check for Updates menu item — @BetaFold3 · #268↗ - Optimize workspace file search index readiness — @provencher · #270↗ - Add generated Xcode workspace workflow — @provencher · #260↗ - fix(xcode): Support generated workspace in Xcode 26 and 27 — @cameroncooke · #271↗ - Fix Oracle review diffs for worktrees — @provencher · #265↗ - Release RepoPrompt CE 1.0.21 — @provencher · #273↗ **New Contributors** - cameroncooke made their first contribution. **[Full Changelog for 1.0.21](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.20...v1.0.21)** #### 1.0.20 - June 19, 2026 **What's Changed** - Preserve Agent chat order when opening sessions — @provencher · #253↗ - Fix Context Builder completion after discovery peer EOF — @provencher · #254↗ - Fix file search scope failures and cold catalog cost — @provencher · #255↗ - Reduce Agent Mode file-tool MainActor stalls — @provencher · #256↗ - Refactor Oracle routing policy boundaries — @provencher · #251↗ - Improve Cursor Agent CLI launch resolution diagnostics — @dlcen · #208↗ - Add smart Agent Mode timestamps — @antonioc-cl · #182↗ - Show a Built-in badge instead of a no-op Remove button for default trusted clients — @BetaFold3 · #178↗ - Fix Claude Safe Managed launch settings and MCP CLI wait bounds — @morluto · #252↗ - Release RepoPrompt CE 1.0.20 — @provencher · #258↗ **New Contributors** - dlcen made their first contribution. - antonioc-cl made their first contribution. - morluto made their first contribution. **[Full Changelog for 1.0.20](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.19...v1.0.20)** #### 1.0.19 - June 18, 2026 **What's Changed** - Refresh approved contributors — @provencher · #234↗ - Optimize XCTest suite lifecycle and runtime — @provencher · #236↗ - Add repo skill for standardized issue creation — @erauner12 · #237↗ - Fix Agent Mode Oracle transcript routing — @provencher · #247↗ - Add MCP read latency diagnostics — @provencher · #239↗ - Fix canonical codemap selection and packaging — @provencher · #245↗ - Refresh approved contributors — @provencher · #243↗ - Add Z.ai GLM 5.2 model support — @baron · #240↗ - Fix Agent sidebar restore hierarchy and ordering — @provencher · #246↗ - Fix worktree readiness and parallel agent startup — @provencher · #248↗ - Release RepoPrompt CE 1.0.19 — @provencher · #250↗ **[Full Changelog for 1.0.19](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.18...v1.0.19)** #### 1.0.18 - June 16, 2026 **What's Changed** - Reduce structural tests and harden test lifecycle — @provencher · #218↗ - Fix Agent Files preview loading state — @erauner12 · #221↗ - Avoid duplicate manage_selection freshness work — @provencher · #220↗ - Integrate MCP lifecycle and bounded search freshness fixes — @provencher · #226↗ - Fix role-default rows under filtered availability — @baron · #224↗ - Fix agent preview retention architecture — @baron · #225↗ - Reduce parallel MCP contention and preserve Agent selections — @provencher · #231↗ - Release RepoPrompt CE 1.0.18 — @baron · #233↗ **[Full Changelog for 1.0.18](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.17...v1.0.18)** #### 1.0.17 - June 14, 2026 **What's Changed** - Stabilize descriptor inheritance test — @provencher · #198↗ - Stabilize watcher restart barrier coverage — @provencher · #199↗ - Fix Git pipe drain descriptor race — @provencher · #201↗ - Stabilize codemap unload reentrancy test teardown — @provencher · #203↗ - Fix CC Zai availability refresh for preconfigured keys — @baron · #188↗ - Refresh approved contributors — @provencher · #202↗ - Fix test runtime lifecycle disposal — @provencher · #209↗ - Fix composer binding after chat handoff — @provencher · #204↗ - Integrate PR #195 worktree test settings stabilization — @provencher · #200↗ - Fix warm file_search validation stalls — @provencher · #205↗ - Show workspace names in window and native tab titles — @nickdavis · #180↗ - Improve Agent Mode workspace footer readability — @erauner12 · #185↗ - Fix Git cancellation output-drain stall — @provencher · #210↗ - Fix Context Builder MCP response teardown race — @provencher · #211↗ - Add active worktree context actions — @erauner12 · #193↗ - Prepare RepoPrompt CE 1.0.17 — @provencher · #213↗ **New Contributors** - nickdavis made their first contribution. - erauner12 made their first contribution. **[Full Changelog for 1.0.17](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.16...v1.0.17)** #### 1.0.16 - June 14, 2026 **What's Changed** - chore: update approved contributor handles — @provencher · #179↗ - Integrate MCP throughput remediation into staging — @baron · #176↗ - Promote MCP throughput remediation staging to main — @provencher · #186↗ - Fix MCP transport timeout recovery — @provencher · #171↗ - Fix Agent Mode wait recovery and Codex managed defaults — @provencher · #190↗ - Keep CLI provider disclosures user-controlled — @provencher · #191↗ - Fix resumed agent ownership and file-search tail latency — @provencher · #192↗ - Integrate PR #146 worktree-aware Context Builder on main — @provencher · #194↗ - Fix Context Builder model restoration on launch — @provencher · #196↗ - Prepare RepoPrompt CE 1.0.16 — @provencher · #197↗ **[Full Changelog for 1.0.16](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.15...v1.0.16)** #### 1.0.15 - June 11, 2026 **What's Changed** - Fix Codex steering and composer submission races — @provencher · #152↗ - Make MCP transport stderr diagnostics crash-safe on closed pipes — @provencher · #163↗ - Prepare RepoPrompt CE 1.0.15 — @baron · #165↗ **[Full Changelog for 1.0.15](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.14...v1.0.15)** #### 1.0.14 - June 11, 2026 **What's Changed** - Add Claude Fable 5 across Agent Mode model catalogs — @BetaFold3 · #142↗ - Harden MCP concurrency and workspace switching — @provencher · #155↗ - Prefer OpenCode provider path before native defaults — @fitchmultz · #148↗ - Model picker missing Z.ai options at startup — @moonray · #116↗ - Fix Cursor CLI Composer ACP routing — @baron · #126↗ - Prepare RepoPrompt CE 1.0.14 — @baron · #162↗ **New Contributors** - BetaFold3 made their first contribution. **[Full Changelog for 1.0.14](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.13...v1.0.14)** #### 1.0.10 - June 9, 2026 **What's Changed** - Harden runtime test coverage — @provencher · #111↗ - Fix Agent Mode capsule label compression — @provencher · #112↗ - Add worktree controls to agent_explore.start — @provencher · #113↗ - Fix ACP mode negotiation and OpenCode routing — @provencher · #97↗ - Prepare RepoPrompt CE 1.0.10 release — @provencher · #119↗ **[Full Changelog for 1.0.10](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.9...v1.0.10)** #### 1.0.9 - June 9, 2026 **What's Changed** - [codex] Avoid stale descriptor assertions in socket cleanup tests — @provencher · #91↗ - Fix onboarding Skip All routing — @fitchmultz · #93↗ - Fix branch popover scroll containment — @strickvl · #89↗ - Add Dock New Window menu item — @dah · #58↗ - Harden MCP response delivery, execution, and agent waiters — @provencher · #96↗ - Distinguish web tool card action labels — @strickvl · #68↗ - Refresh approved contributors — @provencher · #87↗ - Document Homebrew tap install path — @najibninaba · #88↗ - Add expanded file mention picker style — @aAtila · #95↗ - Fix local self-signed production packaging — @fitchmultz · #92↗ - Enforce custom hover tooltips — @provencher · #98↗ - Refresh SwiftPM release lockfile — @provencher · #99↗ - Add PR batch merge skill — @provencher · #100↗ - Optimize store-backed file search performance — @provencher · #104↗ - Fix Codex submit during agent wait drain — @provencher · #105↗ - Fix Git process output drain race — @provencher · #107↗ - Add lean test quality skill — @provencher · #106↗ - Fix conductor daemon stdin handling for local install — @dah · #103↗ - Prepare RepoPrompt CE 1.0.9 release — @provencher · #109↗ **New Contributors** - fitchmultz made their first contribution. - dah made their first contribution. **[Full Changelog for 1.0.9](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.8...v1.0.9)** #### 1.0.8 - June 7, 2026 **What's Changed** - Allow ad-hoc release manifests without designated requirements — @provencher · #83↗ - Fix warm Agent Mode tab activation — @provencher · #85↗ - Prepare RepoPrompt CE 1.0.8 release — @provencher · #86↗ **[Full Changelog for 1.0.8](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.7...v1.0.8)** #### 1.0.7 - June 7, 2026 **What's Changed** - [codex] Refresh approved contributors — @provencher · #67↗ - Harden flaky worktree CI tests — @strickvl · #72↗ - Refresh approved contributors — @provencher · #75↗ - Fix Keyboard Shortcuts settings crash — @strickvl · #73↗ - Fix stalls in long Agent Mode and Context Builder runs — @provencher · #74↗ - Document KeyboardShortcuts packaging workaround — @strickvl · #78↗ - Harden Keychain signing domains and MCP release packaging — @provencher · #80↗ - Prevent MCP frame starvation and lifecycle cleanup races — @provencher · #81↗ - Fix / improve Agent mode Git branch and worktree UI — @strickvl · #69↗ - Prepare RepoPrompt CE 1.0.7 release — @provencher · #82↗ **[Full Changelog for 1.0.7](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.6...v1.0.7)** #### 1.0.6 - June 4, 2026 **What's Changed** - Package CE releases with the CE bundle name — @provencher · #65↗ - Prepare RepoPrompt CE 1.0.6 release — @provencher · #66↗ - Add Agent Mode session row context menus — @strickvl · #60↗ - Add .worktreeinclude support for managed worktrees — @strickvl · #61↗ - Show Git worktree context in Agent sidebar — @strickvl · #62↗ **[Full Changelog for 1.0.6](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.5...v1.0.6)** #### 1.0.5 - June 4, 2026 **What's Changed** - Sync MCP CLI version during release prep — @provencher · #56↗ - Prepare RepoPrompt CE 1.0.5 release — @provencher · #63↗ **[Full Changelog for 1.0.5](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.4...v1.0.5)** #### 1.0.4 - June 3, 2026 **What's Changed** - Prepare RepoPrompt CE 1.0.4 release — @provencher · #55↗ - Harden signed test build workflow — @baron · #45↗ - Improve native Web Search tool cards — @HomunculusLabs · #50↗ - Fix `scripts/doctor.sh` SDK version detection — @strickvl · #53↗ **New Contributors** - baron made their first contribution. - HomunculusLabs made their first contribution. - strickvl made their first contribution. **[Full Changelog for 1.0.4](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.3...v1.0.4)** #### 1.0.3 - June 2, 2026 **What's Changed** - Prepare RepoPrompt CE 1.0.3 release — @provencher · #43↗ - docs(readme): document debug signing setup — @aAtila · #36↗ **New Contributors** - aAtila made their first contribution. **[Full Changelog for 1.0.3](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.2...v1.0.3)** #### 1.0.2 - June 2, 2026 **What's Changed** - Harden workspace file mutation paths — @provencher · #39↗ - Default-enable Codex goal support — @najibninaba · #33↗ - Harden OSS release validation — @provencher · #40↗ - Prepare RepoPrompt CE 1.0.2 release — @provencher · #41↗ **[Full Changelog for 1.0.2](https://github.com/repoprompt/repoprompt-ce/compare/v1.0.1...v1.0.2)** #### 1.0.0 - June 1, 2026 ## RepoPrompt CE 1.0.0 RepoPrompt CE is a native macOS app for orchestrating coding agents with a focus on context engineering. It builds an agent harness around an MCP server, giving you a shared place to prepare repository context, connect compatible CLI agents, run focused tasks, and inspect the work they produce. The goal is simple: make it easier to give agents the right context and keep multi-step engineering work understandable. **Highlights** - Native macOS workspace for context engineering and agent orchestration. - MCP-based harness for integrating compatible CLI agents. - Repository-aware context selection, search, diffs, and worktree workflows. - Public Sparkle update channel for signed, notarized releases. - Fully open source and free to use. **Install The App** Download `RepoPrompt-1.0.0-1.dmg`, open it, and install `RepoPrompt CE.app` in your Applications folder. **First Public Release** This is the first RepoPrompt CE release. It starts a new `1.0.0` version line with its own bundle identifier, signing setup, and update channel. --- ## Do I Need an API Key? (Faq) It depends on the connection you use. A coding-agent runtime can use its own account sign-in, while direct hosted API requests usually require an API credential. A local model server can provide another route. Use [Providers & Models](https://repoprompt.com/docs/1.6.0/providers/overview/) to choose the connection before obtaining a key. ### Does my coding subscription include API access? Do not assume so. Signing into a coding runtime does not automatically configure the same company's direct API. API usage, coding-plan allowances, and local inference have separate requirements. See [AI service costs](https://repoprompt.com/docs/1.6.0/faq/pay-for-services/) for the billing distinction. Oracle and Context Builder can use different connections from your execution session. A working coding-agent login therefore does not prove that every model feature is configured. ### Where do I add or remove a key? Use the corresponding provider's settings. [API Providers](https://repoprompt.com/docs/1.6.0/settings/api-providers/) documents direct-provider controls; [OpenRouter](https://repoprompt.com/docs/1.6.0/settings/openrouter/) and [Custom API](https://repoprompt.com/docs/1.6.0/settings/custom-api/) have their own pages. Runtime-specific credentials and login controls belong under [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/). You can configure several provider connections. This does not mean every provider supports multiple saved keys or automatic key rotation. Follow its actual controls. Deleting a saved key removes that local credential; revoke it with the issuing service if you intend to invalidate the key itself. ### Where are credentials stored and used? Official builds use local macOS Keychain-backed secure storage for credentials managed by the app. Coding runtimes can maintain separate login state. Ad-hoc debug builds use temporary secure storage; see [source-build behavior](https://repoprompt.com/docs/1.6.0/faq/how-to-build/). Credentials are used by the configured connection, including validation and model requests. Some integrations also pass a saved key to a child coding runtime; a custom endpoint receives requests routed to that endpoint. Local storage does not mean the credential never leaves the app process. The provider reference explains shared credentials and account boundaries. If a credential appears missing after an upgrade, use [Credential Recovery](https://repoprompt.com/docs/1.6.0/faq/credential-recovery/) before replacing it. Storage repair and successful authentication with the service are separate checks. --- ## How Do I Find the ChatGPT Pro Interface? (Faq) For this workflow, use ChatGPT's browser conversation at [chatgpt.com](https://chatgpt.com). **ChatGPT Pro** is an account plan; it is not a separate RepoPrompt interface or a model name. A model or reasoning option labeled **Pro**, when offered, is a separate selection inside ChatGPT. Account access and labels can change, so confirm the option actually selected in your conversation. ### Why use it with RepoPrompt? Use a separate reasoning conversation for architectural planning, a difficult diagnosis, or a second review of a proposed change. RepoPrompt supplies focused code context; the receiving model can concentrate on the question rather than reconstructing the repository through a long series of searches. This is useful when you want an independent analysis before implementation. It can be slower than a quick response, and neither a paid plan nor a higher reasoning setting guarantees a better answer. Compare the result with the actual code and your acceptance criteria. OpenAI's [model-selection guidance](https://learn.chatgpt.com/docs/model-selection) explains the depth, speed, and usage tradeoff. ### Find it manually on chatgpt.com 1. Open [chatgpt.com](https://chatgpt.com) in your browser and sign in to the account with the access you intend to use. 2. Start a new conversation. If the interface offers **Chat** and **Work**, choose **Chat** for this question-and-answer workflow. You do not need to start a Codex task to paste a prepared prompt. 3. Open the conversation's model selector and inspect its model and reasoning choices. Use the displayed model control rather than assuming the account's Pro badge identifies the selected model. 4. If your account offers a **Pro** reasoning/model choice, select it explicitly. Otherwise, choose an available reasoning model suited to the task, or check your account/workspace access if you specifically need the Pro option. A missing choice is not evidence that a direct URL will unlock it. 5. Confirm the selected model and any reasoning setting before sending the prompt. Increase reasoning effort when deeper analysis is useful and the additional time and usage fit the task. OpenAI's [web quickstart](https://learn.chatgpt.com/docs/web) documents signing in, choosing Chat or Work, and model selection. The exact controls depend on your account and rollout; this guide does not promise a permanently named Pro menu item or fixed model release. ### Prepare and send the context In RepoPrompt, use **ChatGPT Export** to assemble a self-contained prompt, or use [Prepare and Copy Context](https://repoprompt.com/docs/1.6.0/sessions/context-composer/) to inspect the selected code, receiving-model instructions, and Git changes before copying. The [export workflow](https://repoprompt.com/docs/1.6.0/agent-mode/workflows/#chatgpt-export) can produce a Markdown prompt under `prompt-exports/`; inspect the actual result before using it. Paste the prepared prompt into the browser conversation. Check that the instructions and code arrived intact and fit the receiving interface's limits. If they do not fit, reduce irrelevant context rather than assuming a Pro plan accepts an unlimited repository. Send a concrete analysis request, for example: > Review the attached context and propose an implementation plan. Identify assumptions, affected files, risks, and verification steps. Do not implement changes. Ask for missing code rather than inventing its behavior. Use context you are permitted to share with that service. Pasting the export does not connect the conversation to your live checkout or automatically send later file changes. ### Bring the result back to RepoPrompt Read the analysis, resolve open questions, and copy the useful plan or findings into the intended RepoPrompt session. Include the source context and note any repository changes made since export. For a long plan, save it as a project document and tell the coding agent which file to read. Ask the coding agent to verify the analysis against the current checkout before implementing it. For example: “Check this plan against the current code, flag mismatches, then implement the agreed changes and run the permitted checks.” Review the resulting diff and validation evidence. ChatGPT's answer does not itself apply edits, merge a worktree, or prove the implementation works. ChatGPT account access, API billing, and RepoPrompt's provider connections are separate. See [AI Service Costs](https://repoprompt.com/docs/1.6.0/faq/pay-for-services/) and [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for those distinctions. --- ## How Can I Contribute? (Faq) You can help with reproducible bug reports, documentation corrections, focused code changes, and tested improvements. Start with the repository responsible for the change; application and documentation contributions follow separate policies. ### Contribute to the application Read the [application contribution guide](https://github.com/repoprompt/repoprompt-ce/blob/main/CONTRIBUTING.md) before opening an issue or pull request. The current guide describes a contribution gate: issues from accounts without issue approval and pull requests from accounts without PR approval are closed automatically. Maintainers may review and reopen worthwhile issues. The tracked approved-contributor list distinguishes issue approval from PR approval; neither grants repository access. Follow the policy's approval process rather than repeatedly reopening or duplicating a closed submission. Historical customer status alone is not a substitute for checking the project's current rules. For code changes, read the application's `AGENTS.md`, keep the patch focused, and run the relevant checks required by that repository. Include what changed, why, and validation results. AI-assisted work is welcome under the contribution guide, but you should understand and be able to explain the code you submit. Do not include raw generated investigation or prompt dumps as a substitute for a clear change description. See [How to Build](https://repoprompt.com/docs/1.6.0/faq/how-to-build/) if you need a local development environment. ### Improve the documentation Correct an inaccurate step, explain a missing workflow, improve accessible image descriptions, or fix a broken link. Use the documentation repository's contribution guide for its process. Substantial rewrites and new sections should be discussed there first; small corrections can go directly to a focused pull request. Edit the current documentation collection and verify instructions against application source or the relevant interface. Keep Classic archived, link shared provider facts to Providers & Models, and prefer capabilities over release-specific model lists. Include the affected page and how you checked the correction. ### Not ready to write a patch? A minimal reproduction, a precise documentation correction, or a well-scoped proposal can be useful on its own. Follow [Issue and Feature Request guidance](https://repoprompt.com/docs/1.6.0/faq/report-issue/) so the report reaches the right project with enough information to assess it. --- ## Recover Credentials After an Upgrade (Faq) If a previously saved API credential appears missing after upgrading an official build, it may still exist in the older Keychain service. RepoPrompt provides an explicit repair flow; it does not scan legacy accounts automatically at startup. This flow repairs known secure-storage accounts. It does not sign a CLI runtime into its provider, renew a subscription, or grant API access. First identify the connection in [Providers & Models](https://repoprompt.com/docs/1.6.0/providers/overview/), especially when the same company offers separate CLI and API products. The legacy service targeted by this repair belongs to earlier CE builds; it is not a general Classic import. For that transition, see [Migrating from Classic to CE](https://repoprompt.com/docs/1.6.0/faq/migrate-from-classic/). ### Inspect known legacy accounts 1. Open **Settings → Models & Providers → API Providers**. 2. Under **Legacy secure storage repair**, choose **Review…**. 3. Choose **Scan Known Accounts**. Scanning is noninteractive; importing a selected account may subsequently request macOS Keychain approval. 4. Read the status for the intended account before choosing an action. **No legacy value** means that scan did not find a value for that known account; it does not prove that the credential never existed elsewhere. **Ready to import** and **Import may require Keychain approval** identify accounts you can attempt to import. ### Import without replacing a current value Choose **Import** for the relevant account and respond to any Keychain prompt. A successful import reports **Imported and verified**. Legacy values are retained by default so that an older build can still use them. If the status says **A different v2 value already exists**, automatic replacement is withheld. **Replace v2…** opens a separate confirmation. Replace only when you intend to overwrite that account's current stored value; the legacy value is still retained. “Verified” describes the storage repair result. Check the relevant provider's connection or validation control separately to confirm that the credential still works with the service. ### Cancelled or failed imports **Import was cancelled** and **Repair failed; retry this account** allow another import attempt. Read the reported state, check whether a Keychain request needs attention, and retry the affected account. **Rescan** refreshes the known-account list. If no usable legacy value is available, re-enter the credential using the appropriate [provider guide](https://repoprompt.com/docs/1.6.0/providers/overview/). ### Keep rollback possible After a verified import, **Delete Legacy…** may be available. Its confirmation explains that deleting the old value can make a return to an older build require re-entry. Deletion is optional and separate from importing; leave the legacy value in place when you still need rollback access. For a locally built app, check [How to Build](https://repoprompt.com/docs/1.6.0/faq/how-to-build/) as well: ad-hoc debug builds use temporary secure storage, so losing saved credentials after quitting can be expected for that build type rather than an upgrade migration failure. --- ## How can I build the application? (Faq) RepoPrompt CE is a native macOS application. To build it from source, use the public [RepoPrompt CE repository](https://github.com/repoprompt/repoprompt-ce). ### Requirements - macOS 26 or later. - Xcode 26 or later, installed as the full `Xcode.app`. The Command Line Tools package alone is not enough because the app and its dependencies use Swift macros shipped with Xcode. - Python 3 for the Finder launchers and generated Xcode workflow. From Terminal, clone the repository and check the build toolchain: ```bash git clone https://github.com/repoprompt/repoprompt-ce.git cd repoprompt-ce ./Scripts/doctor.sh ``` The doctor script checks whether the required development tools are available. Resolve any reported Xcode or SDK issue before building. ### Build and launch a debug app For a quick local build, double-click **Launch RepoPrompt CE.command** in Finder. The launcher builds the debug app, opens it, and leaves a small Terminal window available for rebuild and stop controls. It requires Python 3 and coordinates build and launch operations through the repository's developer daemon. If your Mac has an Apple Development signing identity, the launcher uses it. Without one, you can build and launch from Terminal with explicit ad-hoc signing: ```bash ALLOW_ADHOC_SIGNING=1 ./conductor app relaunch ``` Ad-hoc debug builds use temporary in-memory secure storage. API keys and secure permission changes do not persist after the app closes. To use persistent Keychain storage for local development, set your installed Apple Development identity: ```bash SIGN_IDENTITY="Apple Development: Your Name (TEAMID)" ./conductor app relaunch ``` Replace the example identity with one installed on your Mac. You can list available signing identities with `security find-identity -v -p codesigning`. ### Open the project in Xcode Generate and open the disposable contributor workspace from the repository root: ```bash make xcode ``` The generated workspace lives in `.build/xcode/RepoPromptCE.xcworkspace`; it is derived output and should not be edited or committed. In Xcode, use the **RepoPrompt CE App** scheme to build and run the packaged debug application. The **RepoPrompt CE MCP** scheme builds the coordinated MCP executable. The **RepoPrompt CE Tests** scheme delegates tests to the repository's conductor workflow. For generation, validation, cleanup, and scheme details, see the repository's [Generated Xcode Workspace guide](https://github.com/repoprompt/repoprompt-ce/blob/main/docs/architecture/xcode-workspace.md). ### Install a local release-mode build To build and install a release-mode app locally, install Python 3 and double-click **Install RepoPrompt CE Local Production.command** in Finder. It builds from source and replaces `/Applications/RepoPrompt CE.app` with a locally signed app. macOS may ask you to approve the local self-signed certificate. This local build is not notarized. Keep it on your Mac; it is not the distribution method for another computer. For the signed, notarized public application, follow the repository's [Homebrew installation instructions](https://github.com/repoprompt/repoprompt-ce#install-with-homebrew), which install the released app rather than building from source. ### Troubleshooting - If the toolchain check fails, install or select a full Xcode 26+ installation and run `./Scripts/doctor.sh` again. - If the debug app cannot sign, use the explicit ad-hoc command above or configure an Apple Development identity. - If an ad-hoc build appears to lose saved API keys or secure permission changes, that is expected: ad-hoc builds use ephemeral secure storage. - If you need more build detail, see the repository's [README build instructions](https://github.com/repoprompt/repoprompt-ce#build-and-launch-locally) and [contributor guide](https://github.com/repoprompt/repoprompt-ce/blob/main/AGENTS.md). ### Build Tip code with Xcode Tip Builds follow development on the repository's `main` branch. To build that code locally, start with a fresh clone of the repository, or update an existing clean checkout to the latest `main`. If you want to reproduce the source used for a particular published Tip Build, check out the commit identified in that release before generating the workspace. From the repository root, run `make xcode` to generate and open the contributor workspace. In Xcode, select the **RepoPrompt CE App** scheme and the **My Mac** destination, then choose **Product → Run** to build and launch the packaged debug app. Use the same macOS, full Xcode, Python, and signing requirements described above. After updating your checkout, run `make xcode` again to regenerate the workspace for that source revision. This gives you a local development build of the Tip source. The official Tip distribution is signed and notarized by the project's release workflow; Xcode's contributor workspace builds the debug app and does not perform that release packaging. To install the published Tip Build instead, follow [Installing Tip Build](https://repoprompt.com/docs/1.6.0/overview/installation/#installing-tip-build). --- ## Why Is My MCP Connection Not Working? (Faq) Start by identifying the symptom. Installing an MCP connection, authenticating a coding runtime, and configuring an Oracle model are separate operations. A failure in one does not necessarily mean the others are broken. ### The client cannot find the executable Copy configuration from the running CE app using **Quick Setup** or **Settings → MCP Server**. Confirm that the generated command path exists and belongs to the intended release or debug build. Do not reuse a Classic executable path. If the CLI Tools row reports **Needs update**, use **Update**, then reconnect the client. Follow the [Setup Guide](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/) for installation and a connection check. Installing workflow instructions alone does not install the MCP server connection. ### The executable starts, but the client cannot connect Keep RepoPrompt open and enable MCP access for the intended window. **Active** indicates that the listener and that window's access are ready; **Waiting for listener…** does not. Bring the app forward to inspect any pending connection request, then check **Status Dashboard** and its errors. The app-backed bridge uses local UNIX sockets. Changing a firewall, VPN, or TCP port is not the first troubleshooting step for this path. See [Transport Modes](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-transport/) and [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/#troubleshooting-connections). ### The client connects, but tools are missing Check window access and [MCP Tools settings](https://repoprompt.com/docs/1.6.0/settings/tools/). Disabled tools and connection policy affect the advertised list; some tools are available only in eligible session contexts. Reconnect a client that cached an earlier tool list. A connection approval is not a blanket grant for all tools or workspace mutations. ### Tools use the wrong project or conversation Use `bind_context` with `op="list"` to discover contexts and `op="status"` to inspect the binding. Bind the intended workspace roots or a returned context ID. Switching the visible tab does not reliably replace an explicit connection binding. See [Context Binding](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/#context-binding). Multiple clients and windows are supported. Diagnose their bindings rather than disconnecting every other client as a general rule. ### Oracle or Context Builder fails after connection Check the selected model connection, authentication, and provider response. [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/) configures Oracle and discovery choices; they need not use the same connection. Use the current [Tools Reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/), rather than Classic examples for obsolete planning tools. If the failure persists, record the exact error, app version, client, and a minimal reproduction. Follow [Issue Reporting](https://repoprompt.com/docs/1.6.0/faq/report-issue/); remove credentials and private repository content from shared diagnostics. --- ## How Do I Safely Migrate from Classic to CE? Treat the move as setting up a different application and verifying the workflows you need. CE is the active community codebase, but it is not a feature-for-feature replacement for Classic. Keep your working Classic setup and backups until you have confirmed that CE meets your needs. ### The simple answer: As your favorite AI Harness to do it for you. Or... ### 1. Preserve your work before changing anything Finish or stop active coding sessions, then back up your project folders, including uncommitted work and local files you need. A Git commit does not preserve ignored files, application settings, or credentials. Quit Classic before copying its application data. Preserve its installed app, saved workspace data, custom storage location if you use one, and custom prompts or workflow files. Keep a macOS backup that includes the Keychain rather than copying secrets into a plaintext migration note. Record which features and external clients you rely on. The [Classic documentation archive](https://repoprompt.com/docs/classic-2.1.0/) remains available for reference. Its **Classic 2.1.0** label is an archive label, not necessarily the version of your installed application. ### 2. Install CE and start with one project Follow [Installation](https://repoprompt.com/docs/1.6.0/overview/installation/) and start with the Stable channel unless you specifically need a Tip change. Keep the Classic installation available while evaluating CE. Check that you launched the intended app before changing settings or reconnecting clients. Open an existing project folder in CE and create or select a CE workspace. Opening a project references its files; it does not copy them. A coding agent working in that folder can modify the same source files you used with Classic. Choose a [separate worktree](https://repoprompt.com/docs/1.6.0/worktrees/create-and-use/) when you want to isolate trial edits. Do not replace CE's application-data directory with Classic's directory or assume that copying a preferences file migrates every workspace, conversation, and setting. CE's preference and storage migrations serve specific schemas and application identities; they are not a general guarantee of Classic compatibility. ### 3. Reconnect providers and credentials Use [Providers & Models](https://repoprompt.com/docs/1.6.0/providers/overview/) to configure the coding runtime and the model connections your workflow needs. Check Oracle and Context Builder choices separately. A working CLI login does not automatically configure direct API access. If an expected credential is missing, inspect the relevant provider settings. [Credential Recovery](https://repoprompt.com/docs/1.6.0/faq/credential-recovery/) describes the explicit repair flow for known legacy CE Keychain accounts. That flow is not a complete Classic credential import. If it finds no suitable value, authenticate or enter the credential through the provider's current setup controls. Validate the connection before changing or removing old credentials. Keep legacy values while you still need rollback access; deleting a local key is different from revoking it with the provider. ### 4. Reconnect external tools and review custom prompts Generate a new MCP configuration from the CE app for each external client. Follow [MCP Setup](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/), rather than reusing Classic executable paths or command examples. Check which integration is enabled, verify the CE connection, and bind the intended project before asking the client to work. Avoid letting Classic and CE sessions edit the same checkout at the same time. Install the matching CE [workflow instructions](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/) when needed; connecting MCP alone does not install their skill folders or prompt files. Review custom prompts for old tool names, XML-editing instructions, paths, and assumptions about Classic features. CE has **Import Prompts** and **Export Prompts** under [Advanced → Saved Prompts](https://repoprompt.com/docs/1.6.0/settings/advanced/#saved-prompts). Import requires a compatible format; it is not a whole-application restore. Preserve the original export, inspect imported content, and copy prompt text manually if the old format is unsupported. Recreate the settings you need instead of assuming every old preset has an equivalent. ### 5. Verify a small workflow Start with a bounded request such as explaining a function without editing files. Confirm the selected provider, project path, returned context, and any usage charges. Then try a small, isolated change and inspect its diff and validation results. Check the features you actually use: [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/), [Oracle](https://repoprompt.com/docs/1.6.0/faq/what-is-an-oracle/), [manual context copying](https://repoprompt.com/docs/1.6.0/sessions/context-composer/), and [approval behavior](https://repoprompt.com/docs/1.6.0/sessions/approvals/). Keep Classic for a workflow you still need if CE does not provide an equivalent. ### 6. Retire the old setup only after verification Once your normal work succeeds in CE, you can remove obsolete client integrations and decide whether to retain the Classic app. Keep dated backups of its data and exported prompts. Uninstalling an app is not a substitute for checking which configurations and credentials your external tools still use. If you return to Classic, use its preserved data or backup; do not overwrite it with CE data and assume backward compatibility. Project-file changes remain project changes regardless of which app created them. Review or restore those separately. CE does not require an old paid license. See [What Happened to the Paid Version?](https://repoprompt.com/docs/1.6.0/faq/paid-version/) for the transition history and [Issue Reporting](https://repoprompt.com/docs/1.6.0/faq/report-issue/) if a reproducible migration problem remains. --- ## What Happened to the Paid Version of RepoPrompt? (Faq) RepoPrompt moved from the paid Classic product to a free, open-source Community Edition. The founder's [transition announcement](https://repoprompt.com/blog/repo-prompt-next-chapter/) states that Classic's licensing restrictions were removed in the **2.1.32 update** and that all then-current subscriptions were cancelled. Community Edition itself does not require an old Classic license or a new RepoPrompt subscription. ### What should I install now? For the current community application, follow [Installation](https://repoprompt.com/docs/1.6.0/overview/installation/). The [Community Edition launch announcement](https://repoprompt.com/blog/repo-prompt-community-edition/) links the active CE repository and the archived Classic source and download. If you already use Classic, follow [How Do I Safely Migrate from Classic to CE?](https://repoprompt.com/docs/1.6.0/faq/migrate-from-classic/) before replacing your setup. Classic remains an archived product, not the current CE interface. The documentation label **Classic 2.1.0** identifies the archive; it is not a claim that Classic stopped at that application version. Use the documentation appropriate to the app you installed. ### Does CE include every feature from the paid app? Do not assume feature-for-feature equivalence. CE concentrates on context engineering and coding-agent workflows; the launch announcement describes the removal of legacy features. Consult current guides for a specific workflow rather than treating an old purchase, screenshot, or tutorial as a current feature list. ### Why might I still pay for AI usage? Removing RepoPrompt's application subscription did not make external services free. Coding-runtime plans, API usage, and other services have their own terms and billing. See [Do I Need to Pay for AI Services?](https://repoprompt.com/docs/1.6.0/faq/pay-for-services/) and the [provider directory](https://repoprompt.com/docs/1.6.0/providers/overview/) for those account boundaries. For current participation and support, see [Who Maintains RepoPrompt CE?](https://repoprompt.com/docs/1.6.0/faq/solo-project/). --- ## Do I need to pay for AI services? (Faq) RepoPrompt Community Edition is free and open source. AI usage depends on the connection you choose: a coding-agent account, an API credential, or a model server you operate. ### What RepoPrompt charges RepoPrompt CE does not charge for the application or add a markup to provider bills. You supply the relevant account or service. Its terms, quotas, pricing, and data practices apply to requests sent through that route. A CLI subscription does not automatically pay for direct API requests, and an API key does not establish access to a separate subscription product. Check which account and connection the task actually uses. For the transition from the former application subscription, see [What Happened to the Paid Version?](https://repoprompt.com/docs/1.6.0/faq/paid-version/). For credentials, see [Do I Need an API Key?](https://repoprompt.com/docs/1.6.0/faq/api-keys/). ### Supported AI providers The [Providers & Models directory](https://repoprompt.com/docs/1.6.0/providers/overview/) maintains the supported coding-agent, API, compatible-backend, and local-service references. Each provider page explains prerequisites, authentication, capabilities, account boundaries, and billing distinctions. #### Provider setup and current model catalogs Use the provider's reference page for its connection instructions and official catalog links. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains discovery, availability, aliases, effort, and how selections differ between execution, Oracle, and Context Builder. Model names and prices change, so this FAQ does not maintain a second catalog. ### How to keep costs predictable - Inspect the provider account that owns the login or API key and review its current pricing, quotas, and billing controls. - Keep context focused and choose a capability level suited to the task. A workflow can make several model requests, including discovery, consultation, or draft rewriting. - Review paid speed tiers and automatic follow-up features before using them for extended tasks. - For [local models](https://repoprompt.com/docs/1.6.0/providers/local-models/), confirm that inference actually stays local and account for hardware and electricity use. A local server can also be configured to call a hosted route with separate charges. ### What is free and what is not The application is free. AI access is free only when the selected service, account, model, and usage are free under its current terms, or when inference runs locally without a hosted API bill. RepoPrompt cannot guarantee a provider's free allowance or subscription entitlement. --- ## How Do I Report an Issue or Submit a Feature Request? (Faq) Search for an existing report first. Add useful reproduction details to a matching issue rather than creating duplicates. Then choose the project responsible for the problem. ### Application bugs and feature requests Use the [RepoPrompt CE application issue tracker](https://github.com/repoprompt/repoprompt-ce/issues). Read its [contribution policy](https://github.com/repoprompt/repoprompt-ce/blob/main/CONTRIBUTING.md) first: the project automatically closes issues from accounts without issue approval. An automatic closure can reflect that gate rather than a decision on the report's technical merits; maintainers may review and reopen worthwhile submissions. Do not assume that opening a public issue bypasses the gate. For a bug, include: - The app version/build, Stable or Tip channel, and macOS version. - Steps to reproduce, what you expected, and what happened. - The affected feature and provider/runtime when relevant. - The exact error and a small example or redacted screenshot that demonstrates it. For a feature request, describe the user problem, the current workaround, and a concrete example of the desired outcome. Explain why the existing workflow does not address it. A request starts a discussion; it does not establish a release commitment. ### Documentation or website problems Use the documentation issue tracker for incorrect instructions, broken links, confusing explanations, screenshots, and website behavior. Include the page URL, documentation version, and the exact sentence or step. Add browser/device details for a display problem and app-version details for an application instruction. The documentation repository has its own participation rules; application contributor approval does not automatically describe its process. See [How Can I Contribute?](https://repoprompt.com/docs/1.6.0/faq/contributing/) if you want to submit a correction. ### Security problems and exposed credentials Report suspected vulnerabilities privately through the affected repository's **Security → Report a vulnerability** flow, following its security policy. Do not put credentials, private project content, or exploit details in a public issue. If private reporting is unavailable, ask a maintainer to enable a private channel without disclosing the sensitive details publicly. For a connection problem, first try [MCP Troubleshooting](https://repoprompt.com/docs/1.6.0/faq/mcp-troubleshooting/). For a paused coding session, see [Approvals and Paused Sessions](https://repoprompt.com/docs/1.6.0/sessions/approvals/). Community support has no guaranteed response time. --- ## Who Maintains RepoPrompt CE? RepoPrompt began as a solo project, but the Classic answer “RepoPrompt is currently a solo project” does not describe Community Edition's maintenance model. CE is developed through the community repository, where maintainers review contributions and the project records its participation rules. The founder's [transition announcement](https://repoprompt.com/blog/repo-prompt-next-chapter/) explains the move away from daily stewardship. The [Community Edition announcement](https://repoprompt.com/blog/repo-prompt-community-edition/) identifies the open-source repository as the active development home and invites community participation. ### Where should I go for help? Use the [application repository](https://github.com/repoprompt/repoprompt-ce) for application behavior, source builds, and feature proposals. Documentation corrections belong with the documentation project. Read [Issue Reporting](https://repoprompt.com/docs/1.6.0/faq/report-issue/) before submitting, including the application's contributor-approval policy. Support is community-based, with no guaranteed response time. See [the paid-version FAQ](https://repoprompt.com/docs/1.6.0/faq/paid-version/) for what the transition announcement says about licensing and subscriptions. ### Can I participate? Yes, subject to the relevant repository's contribution rules. See [How Can I Contribute?](https://repoprompt.com/docs/1.6.0/faq/contributing/) for focused ways to help and the difference between application and documentation contributions. Maintainer roles and contributor approval are governed by the project, rather than a permanent team-size claim in this FAQ. --- ## What Is the Tip Version and Should I Use It? (Faq) **Tip Builds** are official signed and notarized builds from the latest passing main branch. They make development changes available before the next curated Stable release. **Stable** is the default update channel. ### Which should I choose? Use Stable for routine work when you do not need a particular development change. Consider Tip when you want to try a recent fix or feature, help test ongoing development, and can tolerate regressions or changing behavior. A passing build and notarization do not guarantee that every workflow is free of bugs. Tip is a distribution channel, not a different subscription or an included model plan. A locally compiled source build is also different from the official signed Tip distribution; see [How to Build](https://repoprompt.com/docs/1.6.0/faq/how-to-build/). ### How do I install it? Install and launch RepoPrompt CE, then open **Settings → General → Updates**. Change **Update Channel** to **Tip Builds**, choose **Check for Updates**, and follow the updater's prompts if an eligible build is offered. Changing the selector or checking alone does not establish that a new version was installed. Read the offered build information and preserve work you need before changing versions. If you report a regression, include the exact build and Tip channel in the [issue report](https://repoprompt.com/docs/1.6.0/faq/report-issue/). ### How do I return to Stable? Set **Update Channel** back to **Stable**. The updater switches with the next applicable Stable release; it does not necessarily downgrade an installed Tip build immediately. To return immediately, reinstall the Stable app using the official installation or recovery download path. Reinstalling the application is separate from reverting repository changes or migrating saved application data. Do not delete workspace data or Keychain entries merely to switch channels. See [Software Updates](https://repoprompt.com/docs/1.6.0/settings/updates/) for channel controls and [Installation](https://repoprompt.com/docs/1.6.0/overview/installation/) for getting the application. --- ## What Is an Oracle? (Faq) An **Oracle** is a model consultation that helps you or your coding agent think through a problem using prepared project context. It returns analysis: an implementation plan, a code review, an explanation, or a second perspective on a difficult decision. Think of it as asking a reviewer who has been given the relevant code and a clear question. The value comes from both the model's reasoning and the context it receives. ### How is it different from the coding agent? The execution coding agent carries out the task: it searches the repository, edits files, and runs permitted tools. The Oracle reasons over the context supplied to its consultation and returns an answer. Consulting it does not automatically apply changes or replace the execution model in your session. An Oracle is a role in the workflow, not a particular model brand. You can choose its model separately from the model doing the coding. See [Models and their roles](https://repoprompt.com/docs/1.6.0/providers/models/#model-roles). ### When would I use one? - **Before a substantial change:** ask for a plan that considers existing interfaces, dependencies, and constraints. - **During an investigation:** ask it to explain how the selected code could produce a particular failure. - **Before accepting a change:** ask for a review of the diff together with the surrounding implementation. - **When an approach is uncertain:** ask it to compare alternatives and identify assumptions that need checking. For example: “Review this change for cancellation bugs. Use the selected implementation and callers to explain any findings, and identify missing context before drawing conclusions.” ### Where does its context come from? The consultation uses a prepared package that can include selected files, Code Maps, instructions, conversation context, and relevant Git changes. [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/) can discover and assemble the code before an Oracle analyzes it. Discovery and analysis are separate stages; they can use different models. The Oracle does not automatically know your entire repository. If an answer overlooks an important dependency, inspect the supplied context, add what is missing, and ask a focused follow-up. ### How do I configure it and read the answer? Choose the Oracle model in **Settings → Agent Mode → Agent Models**. You can configure additional Oracles for independent perspectives; their answers remain separate, so compare their reasoning rather than assuming agreement or automatic synthesis. The brain-shaped **Oracle** control above the session editor opens the associated consultations. They can be created by a workflow, a coding-agent request, or a Context Builder analysis follow-up. Follow the [Oracle interface guide](https://repoprompt.com/docs/1.6.0/sessions/oracle/) for the controls and [Agent Models settings](https://repoprompt.com/docs/1.6.0/settings/agent-models/) for configuration. Bring useful findings back into the coding task, verify them against the current code, and review the resulting changes. An Oracle answer is advice, not proof that a change is correct. Consultations also use the selected provider's allowance or billing; see [AI Service Costs](https://repoprompt.com/docs/1.6.0/faq/pay-for-services/). --- ## Does RepoPrompt Run on Windows or Linux? (Faq) The RepoPrompt CE desktop application documented here is a native macOS app. These installation and interface instructions do not describe an official Windows or Linux desktop release. ### Does open source mean it runs on every platform? No. The application uses macOS interfaces and services. Making source code available lets contributors adapt it, but it does not establish that the complete app builds or behaves the same way on another operating system. Community experiments and package-level portability work are different from a supported desktop distribution. Check the project's actual release artifacts before treating a port as available. This FAQ does not promise a port or a release date, and the old Classic waitlist is not the installation path for CE. ### Can I use the CLI instead? The documented app-backed `rpce-cli` and MCP bridge connect to the running macOS app. Installing a client or copying its configuration does not install an equivalent Windows or Linux application. Individual source components can have different requirements from that app-backed workflow. For macOS installation, see [Installation](https://repoprompt.com/docs/1.6.0/overview/installation/). Building the development source has its own toolchain requirements in [How to Build](https://repoprompt.com/docs/1.6.0/faq/how-to-build/); those are not a universal compatibility statement for every previously published binary. ### Can I help with another platform? Read [How Can I Contribute?](https://repoprompt.com/docs/1.6.0/faq/contributing/) and the application's contribution policy before proposing a port. A proposal should identify the target platform, which UI and system integrations it replaces, and how it will be maintained and tested. --- ## Introduction (Version-1.6.0) **Bring your code, context, and AI coding tools together.** RepoPrompt CE gives you a well-thought-out, unified workspace for exploring a repository and working with your go-to AI coding tools. Use its first-class tooling to explore an extensive repo, trace unfamiliar code, work through an architectural decision, review a series of changes, or coordinate work across coding agents you already use. The macOS application is **free and open source**. Connect your own coding-runtime account, API provider, or local model service; [AI service costs](https://repoprompt.com/docs/1.6.0/faq/pay-for-services/) depend on the connection you use. ### Give your coding work the right tools and the right context Before any coding agent can make production-ready changes, it needs to understand the code already there: the relevant files, their interfaces, the changes in progress, and the constraints that matter. We all know that finding and sharing that context can take longer than writing the plan or prompt. RepoPrompt helps you build a focused view of the task and assemble that context accurately and narrowly so you get the best results from your favorite models from your preferred providers. It gathers full files when implementation details matter, slices when only a few lines are relevant, and delivers Code Maps when structure and signatures are enough. Add Git changes and clear instructions to show the model what you want it to examine. Then select a battle-tested, pre-built workflow or manually inspect and adjust the package before asking for a plan, review, or implementation. You still judge the answer and verify the resulting changes. [See how context preparation works →](https://repoprompt.com/docs/1.6.0/overview/how-it-works/) ### Choose how you want to work #### Run a coding session in RepoPrompt Choose a connected coding runtime, then describe the task, choose a workflow, and follow the work in conversations and the Oracles that guide the results. You can inspect tool activity and changes, answer questions, and steer the agent as it works, all without switching between terminal sessions. RepoPrompt session composer with workflow, context, model, tools, and permission controls [Get to know the session interface →](https://repoprompt.com/docs/1.6.0/sessions/overview/) #### Keep using your preferred coding tools Connect an MCP-compatible client to RepoPrompt's repository and context tools. Your external coding agent can search files, inspect Code Maps, assemble context, and consult an Oracle while you review the work in RepoPrompt. [Connect an external coding tool →](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/) #### Prepare a prompt for another model Select code, add instructions and Git changes, then copy a self-contained package. Use it for a design discussion or an independent review in ChatGPT or another service, and bring the useful findings back to your coding session. [Prepare and copy your context →](https://repoprompt.com/docs/1.6.0/sessions/context-composer/) ### Start with the task you need to finish Choose a built-in workflow from the welcome cards or the **Workflow** selector, then describe what you want to accomplish. Let RepoPrompt go from there. | What you want to do | Where to start | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | | Coordinate a larger piece of work | **Orchestrate** breaks down the task, delegates work, and checks the results. | | Check changes for bugs and regressions | **Review** examines the change with its surrounding code. | | Understand a bug or unfamiliar behavior | **Investigate** gathers evidence and explores the relevant code. | | Plan a substantial change before editing | **Deep Plan** develops an implementation plan grounded in the repository. | | Build a feature or fix | **Plan & Build** guides research, planning, and implementation. | | Improve code structure | **Refactor** focuses on preserving intended behavior while improving the implementation. | | Get an independent perspective | **ChatGPT Export** prepares context for a conversation outside RepoPrompt. | [Choose a workflow for your task →](https://repoprompt.com/docs/1.6.0/sessions/workflow-templates/) ### Let Context Builder do the discovery You don't need to know every relevant filename before you start. Give Context Builder a task and any useful starting points, then inspect what it finds. #### 1. Explore A discovery coding agent searches the repository and follows the code related to your question. #### 2. Curate It selects relevant files, slices, and Code Maps within your context budget (which is what context engineering is all about). You can optionally review the selection, remove anything unnecessary, and add what it missed. #### 3. Handoff Use the prepared context to ask an Oracle for a plan, review, or answer, or export it for another model. Discovery and analysis can use different models. [Explore the Context Builder workflow →](https://repoprompt.com/docs/1.6.0/sessions/context-builder/) ### Coordinate larger changes without losing sight of them RepoPrompt overcomes the AI-assisted nightmare of big edits. For a larger change, you can use separate sessions for investigation, implementation, and review. **Overseer Mode** lets a coordinating conversation follow linked sessions and direct the next steps. Use **worktrees** when parallel tasks need separate checkouts; separate conversations can still edit the same checkout. Review the work, merge it into the intended target, and verify the combined result. [Coordinate sessions with Overseer →](https://repoprompt.com/docs/1.6.0/overseer/) · [Create and use a worktree →](https://repoprompt.com/docs/1.6.0/worktrees/create-and-use/) · [Review and merge the result →](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/) ### Keep control as the work develops - **Make the request clearer.** Use [Interviewer](https://repoprompt.com/docs/1.6.0/sessions/interviewer/) to resolve open questions or [Re-Prompter](https://repoprompt.com/docs/1.6.0/sessions/re-prompter/) to refine a draft before sending. - **Show the problem.** Attach a [screenshot or mockup](https://repoprompt.com/docs/1.6.0/sessions/image-support/). Eligible Codex sessions can also use [Computer Use](https://repoprompt.com/docs/1.6.0/sessions/computer-use/) for tasks that need the visible interface. - **Choose how the model works.** Set the [model and reasoning effort](https://repoprompt.com/docs/1.6.0/sessions/model-and-effort/) yourself, or configure [Model Router](https://repoprompt.com/docs/1.6.0/sessions/model-router/) for eligible new tasks. - **Review the decisions that matter.** Inspect [approval requests and edit reviews](https://repoprompt.com/docs/1.6.0/sessions/approvals/), then return to [session history](https://repoprompt.com/docs/1.6.0/sessions/session-history/) when you need the context behind a result. ### Use the connection that fits your work Connect a supported coding runtime for implementation, a direct API for model features, or a local model server. Configure Oracle consultations separately when you want another model to assess a plan or review the code. The **Providers & Models** reference explains what each integration needs and what it supports. Available models depend on your connected accounts or APIs you bring to the table. You can start with a focused task and adjust the settings as you go; you do not need to choose every model and experiment with thinking levels and settings before trying. [Compare providers and model availability →](https://repoprompt.com/docs/1.6.0/providers/overview/) ### Try it on one real task Start with a question you can evaluate: understand an unfamiliar function, investigate a reproducible bug, or review a small change. A narrow first task makes it easier to see what RepoPrompt adds to your existing workflow. 1. **Open your project** and connect the provider you want to use. 2. **Describe the outcome.** Include the behavior you care about, known constraints, and how you will check the result. 3. **Choose the workflow and location.** Use a separate worktree when you want an isolated checkout. 4. **Inspect and guide the work.** Review the selected context, answer questions, and check the resulting code and test results. [Follow the getting-started walkthrough →](https://repoprompt.com/docs/1.6.0/overview/getting-started/) ### Learn More [![Video preview image](https://img.youtube.com/vi/ncY6cqOCd_Y/maxresdefault.jpg) RepoPrompt 101 Video walkthroughs of key features and workflows](https://youtube.com/playlist?list=PLFg9suyZ1OnLh3Tv5bP6jvWXcKKTlI_4m) [Podcast cover art Rate Limited Podcast AI coding workflows with Eric, Ray Fernando, Adam Larson](https://www.youtube.com/@ratelimitedpod) Some walkthroughs show Classic. Use the current guides below for CE controls and supported workflows. ### Talk to These Docs Use **Copy page** to bring an article into an AI conversation. For the complete documentation, use the LLM index or full documentation export. Include your app version and the task you need help with. ### Documentation table of contents
Browse every guide The current documentation version is **1.6.0** and may refer to versions in the 1.6.x series. :::note RepoPrompt Classic and its `repoprompt-classic` repository are archived. **[Classic 2.1.0 archive](https://repoprompt.com/docs/classic-2.1.0/)** is the documentation archive label: its instructions may describe earlier RepoPrompt Classic releases and are not specific to version 2.1.0. Features, interface labels, and workflows may differ from your installed version; check each guide's context before following it. ::: #### Overview - [Installation](https://repoprompt.com/docs/1.6.0/overview/installation/) - [Getting Started](https://repoprompt.com/docs/1.6.0/overview/getting-started/) - [How It Works](https://repoprompt.com/docs/1.6.0/overview/how-it-works/) - [How It (Really) Works](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/) #### Why RepoPrompt - [Why RepoPrompt](https://repoprompt.com/docs/1.6.0/why-repoprompt/) #### Sessions & Interface - [Overview](https://repoprompt.com/docs/1.6.0/sessions/overview/) - [Session History](https://repoprompt.com/docs/1.6.0/sessions/session-history/) - [Execution Location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/) - [Workflow Templates](https://repoprompt.com/docs/1.6.0/sessions/workflow-templates/) - [Overseer](https://repoprompt.com/docs/1.6.0/sessions/overseer/) - [Interviewer](https://repoprompt.com/docs/1.6.0/sessions/interviewer/) - [Re-Prompter](https://repoprompt.com/docs/1.6.0/sessions/re-prompter/) - [Model Router](https://repoprompt.com/docs/1.6.0/sessions/model-router/) - [Auto Effort](https://repoprompt.com/docs/1.6.0/sessions/auto-effort/) - [Computer Use](https://repoprompt.com/docs/1.6.0/sessions/computer-use/) - [Message Editor](https://repoprompt.com/docs/1.6.0/sessions/message-editor/) - [Model and Effort](https://repoprompt.com/docs/1.6.0/sessions/model-and-effort/) - [Tools](https://repoprompt.com/docs/1.6.0/sessions/tools/) - [Approvals and Paused Sessions](https://repoprompt.com/docs/1.6.0/sessions/approvals/) - [Oracle](https://repoprompt.com/docs/1.6.0/sessions/oracle/) - [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/) - [Prepare and Copy Context](https://repoprompt.com/docs/1.6.0/sessions/context-composer/) - [Image Support](https://repoprompt.com/docs/1.6.0/sessions/image-support/) #### Providers & Models - [Overview and provider directory](https://repoprompt.com/docs/1.6.0/providers/overview/) - [Model availability, effort, tiers, and roles](https://repoprompt.com/docs/1.6.0/providers/models/) #### Agent Mode - [Overview](https://repoprompt.com/docs/1.6.0/agent-mode/overview/) - [Workflow Commands](https://repoprompt.com/docs/1.6.0/agent-mode/workflows/) - [Skills & Slash Commands](https://repoprompt.com/docs/1.6.0/agent-mode/skills/) #### MCP Server - [Overview](https://repoprompt.com/docs/1.6.0/mcp-server/) - [Setup Guide](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/) - [Setup Wizard](https://repoprompt.com/docs/1.6.0/mcp-server/setup-wizard/) - [Tools Reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/) - [App Settings Tool](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-app-settings/) - [Transport Modes](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-transport/) - [Settings & Presets](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-settings/) - [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/) - [Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/) #### Overseer Mode - [Overview](https://repoprompt.com/docs/1.6.0/overseer/) - [Lanes](https://repoprompt.com/docs/1.6.0/overseer/lanes/) - [Linking Sessions](https://repoprompt.com/docs/1.6.0/overseer/linking-sessions/) - [Best Practices](https://repoprompt.com/docs/1.6.0/overseer/best-practices/) #### Worktrees - [Worktrees overview](https://repoprompt.com/docs/1.6.0/worktrees/) - [Create and Use a Worktree](https://repoprompt.com/docs/1.6.0/worktrees/create-and-use/) - [Review and Merge](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/) #### Reference - [Settings Reference](https://repoprompt.com/docs/1.6.0/reference/settings/) #### Changelog - [CE Version 1](https://repoprompt.com/docs/1.6.0/changelog/ce-version-1-0/) #### FAQ - [What Is an Oracle?](https://repoprompt.com/docs/1.6.0/faq/what-is-an-oracle/) - [What Happened to the Paid Version?](https://repoprompt.com/docs/1.6.0/faq/paid-version/) - [How Do I Safely Migrate from Classic to CE?](https://repoprompt.com/docs/1.6.0/faq/migrate-from-classic/) - [Do I need to pay for AI services?](https://repoprompt.com/docs/1.6.0/faq/pay-for-services/) - [Do I Need an API Key?](https://repoprompt.com/docs/1.6.0/faq/api-keys/) - [How Do I Find the ChatGPT Pro Interface?](https://repoprompt.com/docs/1.6.0/faq/chatgpt-pro/) - [Recover Credentials After an Upgrade](https://repoprompt.com/docs/1.6.0/faq/credential-recovery/) - [Why Is My MCP Connection Not Working?](https://repoprompt.com/docs/1.6.0/faq/mcp-troubleshooting/) - [Does RepoPrompt Run on Windows or Linux?](https://repoprompt.com/docs/1.6.0/faq/windows-linux/) - [What Is the Tip Version and Should I Use It?](https://repoprompt.com/docs/1.6.0/faq/tip-version/) - [Who Maintains RepoPrompt CE?](https://repoprompt.com/docs/1.6.0/faq/solo-project/) - [How Can I Contribute?](https://repoprompt.com/docs/1.6.0/faq/contributing/) - [How Do I Report an Issue or Submit a Feature Request?](https://repoprompt.com/docs/1.6.0/faq/report-issue/) - [How can I build the application?](https://repoprompt.com/docs/1.6.0/faq/how-to-build/)
### Code examples: MCP and shell
Compare MCP and CLI examples The following language tabs show the same read-only settings request. Code blocks provide a Copy button. See [App Settings Tool](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-app-settings/) for the current allowlist and [Setup Guide](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/#terminal-access) for terminal installation. **JSON · MCP** Call `app_settings` with: ```json { "op": "get", "key": "ui.appearance_mode" } ``` **Bash · rpce-cli** ```bash rpce-cli -e 'call app_settings {"op":"get","key":"ui.appearance_mode"}' ```
--- ## App Settings Tool (Mcp-server) The `app_settings` MCP tool lets agents read and write an allowlisted set of RepoPrompt's global preferences — appearance, prompt packaging, preferred models and the Oracle roster, Context Builder's agent/model, preset visibility, Code Maps, file scanning, selected Agent Mode preferences, and notifications — without opening the Settings UI. Credentials and workspace-specific profiles are not exposed. :::tip **Companion pages:** Use this page for the MCP/JSON surface. The same arguments can be sent with `rpce-cli` after [CLI installation](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/#terminal-access). See [Settings Reference](https://repoprompt.com/docs/1.6.0/reference/settings/) for the in-app controls. ::: ### When to Use It - Match the user's preferred appearance or prompt packaging before building a copy preset. - Review `mcp.show_model_presets` when configuring Oracle discovery. - Reset `models.planning_model` to `null` so RepoPrompt falls back to defaults. - Temporarily disable Code Maps globally via `code_maps.globally_disabled` during large refactors. - Inspect file-scanning and notification preferences without editing the raw settings document. ### Operations | `op` | Selectors | Purpose | | --- | --- | --- | | `list` | optional `group` | Browse the allowlist catalog. Each entry includes the current value and, for keys that have them, `options_available: true`. | | `get` | exactly one of `key`, `keys`, `group` | Read one or more setting values. Selectors are mutually exclusive. | | `set` | `key` and `value` | Update exactly one setting. `keys` and `group` are rejected on `set`. | | `options` | `key`, optional `agent`, `limit`, `detailed` | List candidate values for keys that advertise `options_available: true`, including model and font-scale settings. | #### Parameters | Parameter | Type | Notes | | --- | --- | --- | | `op` | `list \| get \| set \| options` | Required. | | `group` | string | `ui`, `prompt_packaging`, `models`, `context_builder`, `mcp`, `code_maps`, `file_system`, `agent_mode`, or `notifications`. Used by `list` and as a selector for `get`. | | `key` | string | Fully-qualified key (e.g. `ui.appearance_mode`). Required for `set`; optional selector for `get`. | | `keys` | array of string | Multi-key selector for `get`. Mutually exclusive with `key` and `group`. | | `value` | boolean, number, string, string array, or null | Required on `set`. Match the catalog's declared `type`: the additional Oracle roster uses an array, while `prompt_packaging.prompt_sections_order` uses a string containing a JSON array. | | `agent` | string | For `options` on model settings: filter candidates to a supported CLI backend, such as `claudeCode` or `codexExec`. | | `limit` | integer | For `options`: maximum number of candidates returned (1–200, default 60). | | `detailed` | boolean | For `options`: include descriptions and model metadata in each candidate. | ### Groups The allowlist is organized into nine groups so an agent can browse narrowly before reaching for `set`. If you are not sure about the exact key, type, or allowed values, call `list` first; `set` validates strictly and rejects unknown or out-of-range values without partial application. The returned catalog is the authority for the running build, including any debug-only entries. #### `ui` — Appearance and chrome | Key | Type | Details | | --- | --- | --- | | `ui.appearance_mode` | string enum | `System` \| `Light` \| `Dark`. App appearance mode. | | `ui.show_tooltips` | boolean | Whether RepoPrompt shows app tooltips. | | `ui.enable_keyboard_shortcuts` | boolean | Global keyboard shortcuts. New/changed shortcuts may only take effect after reopening a window. | | `ui.font_scale` | number | An app font-size preset value. Use `list` and `options` for accepted values; arbitrary sizes are rejected. | #### `prompt_packaging` — How prompts are assembled | Key | Type | Details | | --- | --- | --- | | `prompt_packaging.prompt_sections_order` | string containing a JSON array | The wire value is a string, not a native JSON array. Its decoded array must contain each prompt section exactly once. Call `{"op":"list","group":"prompt_packaging"}` first and read `allowed_items` for the canonical section raw values before sending `set`. | | `prompt_packaging.duplicate_user_instructions_at_top` | boolean | Whether user instructions are duplicated at the top of packaged prompts. | | `prompt_packaging.file_path_display_option` | string enum | `Full` \| `Relative`. How file paths are displayed in packaged context. | | `prompt_packaging.selected_files_sort_method` | string enum | `nameAscending` \| `nameDescending` \| `tokenAscending` \| `tokenDescending`. | | `prompt_packaging.include_datetime_in_user_instructions` | boolean | Whether packaged user instructions include the current date/time. | #### Legacy editing preferences The current allowlist has no `editing` group. Classic keys such as `editing.file_edit_format`, `editing.allow_diff_models_to_rewrite`, and `editing.complex_edit_strategy` should not be sent to this tool. Configure the relevant UI workflow instead; the current Oracle send contract offers `chat`, `plan`, and `review` modes. #### `models` — Model selection and inference defaults | Key | Type | Details | | --- | --- | --- | | `models.preferred_compose_model` — **Built-in Chat Model** | string \| null | Preferred Built-in Chat model raw identifier, if set. Advertises `options_available: true`. Set `null` to clear. | | `models.planning_model` — **Oracle Model** | string \| null | Preferred Oracle model raw identifier, if set. Advertises `options_available: true`. Set `null` to clear. | | `models.additional_oracle_models` | string array | Ordered additional Oracle model IDs, with at most four entries. The primary model is configured separately. | | `models.sync_chat_model_with_oracle` — **Sync Built-in Chat with Oracle** | boolean | Whether the Built-in Chat model is kept in sync with the Oracle model. | | `models.temperature` | number | Range `0.0`–`2.0`. Only applied when `models.temperature_enabled` is `true`. | | `models.temperature_enabled` | boolean | Whether the global temperature is sent with model requests. | | `models.custom_planning_prompt` — **Custom Oracle System Prompt** | string | Custom system prompt used by the Oracle. Empty string restores the built-in default. | #### `context_builder` — Context Builder agent & model | Key | Type | Details | | --- | --- | --- | | `context_builder.agent` | string enum | CLI agent used by Context Builder. Call `list` and read `allowed_values` for eligible backend IDs. Writes preserve the backend's remembered model when one exists, or use its default. | | `context_builder.model` | string \| null | Remembered model ID for the selected backend; null clears that slot. An unusable saved backend can read as null; inspect the agent catalog before setting a replacement. `options` normally scopes candidates to the current backend. | #### `mcp` — MCP preset visibility | Key | Type | Details | | --- | --- | --- | | `mcp.show_model_presets` | boolean | Whether MCP model presets are exposed. Internal temporary suppression is separate and is not a durable allowlisted preference. | **Auto-Start** and live listener lifecycle controls remain in the app UI. The Classic `mcp.auto_start` example is not part of the current registry. #### `code_maps` — Global Code Maps toggle | Key | Type | Details | | --- | --- | --- | | `code_maps.globally_disabled` | boolean | When `true`, Code Maps are globally disabled and the MCP `get_code_structure` tool is suppressed. | | `code_maps.non_git_enabled` | boolean | Opt in to Code Maps in non-Git folders. | #### `file_system` — Workspace folder scanning These preferences affect scanning. Local `.repo_ignore` file contents remain repository content, rather than a scalar application setting. | Key | Type | Details | | --- | --- | --- | | `file_system.respect_repo_ignore` | boolean | Honor RepoPrompt-specific ignore rules. | | `file_system.respect_cursorignore` | boolean | Honor `.cursorignore` rules. | | `file_system.global_ignore_defaults` | string | Global ignore patterns separated by newlines; limited to 20,000 characters. | | `file_system.enable_hierarchical_ignores` | boolean | Honor ignore files in nested directories. | | `file_system.skip_symlinks` | boolean | Skip symbolic links; the inverse of the UI's Follow symbolic links option. | | `file_system.show_empty_folders` | boolean | Include empty folders in workspace listings. | #### `agent_mode` — Selected global behavior | Key | Type | Details | | --- | --- | --- | | `agent_mode.show_built_in_workflow_cleanup_guidance` | boolean | Include housekeeping guidance in built-in Agent Mode workflow templates. Custom templates and external workflow instructions are separate. | | `agent_mode.codex_goal_support_enabled` | boolean | Enable Codex goal-support feature configuration. | | `agent_mode.codex_reasoning_summaries_enabled` | boolean | Request Codex reasoning summaries in Agent Mode; separate from reasoning effort. | | `agent_mode.claude_usage_quota_enabled` | boolean | Passive run rate-limit diagnostics; does not connect a Claude account or authorize account usage reads. | | `agent_mode.codex_usage_quota_enabled` | boolean | Observe-only Codex quota display preference. Quota readings are not returned over MCP. | | `agent_mode.usage_limits_display_enabled` | boolean | Display already-enabled usage sources; does not connect a source or change routing. | | `agent_mode.provider_conversation_cleanup_action` | enum | Provider conversation cleanup preference. Discover accepted values from `list`. | | `agent_mode.subagent_default_wait_seconds` | integer enum | Default otherwise-quiet sub-agent wait: `120`, `300`, `600`, `1200`, `1800`, or `3600` seconds. | #### `notifications` — Notification preferences The registry exposes notification descriptor keys as booleans. Call `{"op":"list","group":"notifications"}` for the exact names, descriptions, and values in your build, then use a returned key with `set`. These preferences control app notification behavior; macOS notification authorization is managed by the operating system. See [Notifications settings](https://repoprompt.com/docs/1.6.0/settings/notifications/). ### Examples (MCP JSON) Each example shows the arguments object passed to `app_settings`: The prompt-section order is JSON encoded inside the string-valued `value`. This example uses the section names declared in the application source; compare them with the running catalog's `allowed_items` before changing the order: ```json { "op": "set", "key": "prompt_packaging.prompt_sections_order", "value": "[\"fileMap\",\"fileContents\",\"gitDiff\",\"metaPrompts\",\"userInstructions\"]" } ``` ```text // Browse the full catalog (values always included) { "op": "list" } // Inspect one group { "op": "list", "group": "ui" } // Batch read a few keys { "op": "get", "keys": ["ui.appearance_mode", "mcp.show_model_presets"] } // Toggle a boolean { "op": "set", "key": "ui.show_tooltips", "value": false } // Update an enum { "op": "set", "key": "ui.appearance_mode", "value": "Dark" } // Clear an optional model (null is valid for nullable keys) { "op": "set", "key": "models.planning_model", "value": null } // Change a numeric setting { "op": "set", "key": "models.temperature", "value": 1.25 } // Switch the Context Builder agent (remembered model is preserved) { "op": "set", "key": "context_builder.agent", "value": "codexExec" } // List candidate models for the current Context Builder backend { "op": "options", "key": "context_builder.model" } // Narrow candidates to one CLI backend { "op": "options", "key": "models.planning_model", "agent": "codexExec", "limit": 25 } ``` ### Error Behavior - **Unknown keys:** Rejected with a clear error. Call `list` (or `list` with a `group`) to discover the correct key. - **Wrong types:** Booleans, numbers, strings, and `null` are each validated against the entry's declared `type`. - **Out-of-range values:** Numeric ranges (e.g. `models.temperature` 0.0–2.0) and enum values are enforced. - **No partial application:** Validation fails closed — if any check fails, nothing is written. - **One key per `set`:** Passing `keys` or `group` on `set` is rejected. ### Safety & Deliberately Excluded This surface is intentionally narrow. The following are **not** reachable through `app_settings` and must be managed in the Settings UI: - API credentials and raw provider secrets for any provider. - MCP tool ACLs, auto-start lifecycle controls (`mcp.auto_start`), and agent permission documents. - Workspace approvals and workspace-scoped chat/copy settings. - Agent permission policies, human-only strict approval controls (specifically `agent_mode.codex_hook_approval_strict_mode_enabled`, which is classified in `humanOnlySettingKeys` and explicitly rejected over MCP), and workspace model override dictionaries. Selected durable global Agent Mode preferences are explicitly allowlisted above. - Internal migration flags and settings absent from the catalog. Development builds can expose additional diagnostic entries; do not assume they exist in release builds. If a preference is dangerous, secret, or workspace-specific, it is kept UI-only by design. Agents can still discover what *is* reachable with `op=list`. ### See Also - [Setup Guide](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/#terminal-access) — install terminal access with `rpce-cli`. - [MCP Tools Reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/) — schemas for every MCP tool. - [Settings Reference](https://repoprompt.com/docs/1.6.0/reference/settings/) — the in-app Settings UI equivalents. - [MCP Server Overview](https://repoprompt.com/docs/1.6.0/mcp-server/) — IDE-for-agents framing and capability map. --- ## Connection Management (Mcp-server) RepoPrompt 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 toolbar's MCP icon opens the server popover. The popover identifies the window being configured and provides live listener and connection feedback: | Status | Meaning | | --- | --- | | **Active** | The listener is running and MCP tools are enabled for this window. | | **Waiting for listener…** | Window access is enabled but the listener is not running. | | **Listener active** with tools disabled | The shared listener is available, but this window is not exposing its tools. | | **Inactive** | This window is not exposing tools and the listener is not running. | | Running tool name / **Cancel** | A tool call is in progress; cancellation is available where supported. | The connection badge opens client details. In Settings, **Status Dashboard** opens diagnostics; an error indicator opens contextual error information. Use the window switch to change this window's access. **Force Stop Listener** stops the shared listener for all windows and clients. ### Connection Approval A new external client process can trigger a **Connection Request** overlay showing its identity and executable information when available. Choose **Allow Session** or **Allow Once**, according to the displayed choice, or **Deny**. The current overlay does not offer Classic's name-based **Always Allow** action. A client name alone is not a trustworthy standing identity; review the process information and the connection you initiated. Connection admission, workspace-operation approval, and agent permissions are distinct. Allowing a client to connect does not authorize it to create or delete a workspace, approve an agent shell command, or widen its tools. See [Workspace Approvals](https://repoprompt.com/docs/1.6.0/settings/workspace-approvals/) and [Agent Permissions](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/). ### Multi-Window Context RepoPrompt supports multiple windows, each showing a workspace, behind one shared listener. The current UI provides a per-window MCP access switch. It does not require the old **Multi-Window Mode** setup step from Classic documentation. #### Context Binding Use `bind_context` to discover, inspect, and bind the workspace context for this connection. Start with `op="list"`, then bind by absolute workspace root paths or a returned context UUID. Root matching first looks for an exact set, then an eligible superset; pass workspace roots rather than arbitrary descendant files. ```json {"op":"bind","working_dirs":["/Users/example/Project"]} ``` When a suitable saved workspace is not already open, the app can open it. `create_if_missing=true` allows a new workspace to be requested when no match exists, subject to workspace approval. To pin a compose context rather than following the active tab, bind a `context_id` returned by discovery: ```json {"op":"bind","context_id":"RETURNED-CONTEXT-UUID"} ``` Call `{"op":"status"}` to inspect the current binding. The current global `bind_context` schema does **not** accept `window_id`; use the fields returned by your connection's schema. Compose context IDs and Agent Mode session IDs serve different purposes and must not be substituted for each other. #### Workspace Lifecycle `manage_workspaces` lists saved workspaces and handles workspace creation, switching, hiding, deletion, folders, and compose tabs. `list` excludes hidden workspaces by default; `include_hidden=true` includes them. Hiding keeps a workspace recoverable, while deletion is a separate operation. ```text // List saved visible workspaces { "action": "list" } // Include recoverable hidden workspaces { "action": "list", "include_hidden": true } // Open a saved workspace in a new window { "action": "switch", "workspace": "MyProject", "open_in_new_window": true } // Create a new workspace and switch to it, subject to approval { "action": "create", "name": "NewProject", "folder_path": "/Users/example/NewProject", "switch_to_created": true } // Add a folder to an existing workspace { "action": "add_folder", "workspace": "MyProject", "folder_path": "/Users/example/Shared" } ``` Use exact workspace UUIDs when names are ambiguous. Some lifecycle operations also accept a `window_id`; that is separate from the global context-binding API. ### Tab Management Compose tabs allow parallel work contexts within a single window. MCP clients can manage tabs programmatically: #### Listing Tabs ```text // List tabs in current window { "action": "list_tabs" } // Response includes: // - Tab ID and name // - [active] = Currently visible tab // - [bound] = Tab this MCP connection is pinned to ``` #### Tab Binding A workspace/window affinity can follow the active tab. For operations that need a stable selection and prompt, bind the compose context explicitly before starting. `manage_workspaces` retains these legacy tab operations; prefer `bind_context op=list` and `op=bind context_id=...` for new integrations: ```text // Bind to a specific tab for consistent context { "action": "select_tab", "tab": "Feature-Auth", "focus": false } // 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. ```text // Create a blank background tab and bind this MCP connection to it { "action": "create_tab", "name": "Bugfix", "bind": true, "focus": false } // Fork an existing tab into a new background tab { "action": "create_tab", "mode": "fork", "source_tab": "Feature-Auth", "name": "Feature-Auth Follow-up" } ``` `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 RepoPrompt applies safety checks to prevent destructive or confusing behavior. ```text // Close a non-active tab by name or UUID { "action": "close_tab", "tab": "Bugfix" } // Explicitly allow closing the currently visible tab { "action": "close_tab", "tab": "Bugfix", "allow_active": true } ``` - 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 Oracle History Use `oracle_utils` with `op="sessions"` to find Oracle conversations at workspace or context scope. Supply a context UUID discovered through `bind_context` to narrow the list: ```json {"op":"sessions","context_id":"RETURNED-CONTEXT-UUID","limit":10} ``` During eligible Agent Mode runs, `oracle_chat_log` returns recent Oracle messages; `chat_id` selects a conversation, `limit` bounds the response, and `include_user` controls whether the caller's messages are included. Use `oracle_send` or `ask_oracle`, as advertised, to continue a conversation. The Classic `chats` tool's `action="list"` and `action="log"` examples are not the current contract. #### Context Builder Discovery Tab An external app-backed `context_builder` call normally creates a fresh compose tab for its discovery context. During an Agent Mode run, the tool reuses the current agent tab. Check the returned context and conversation IDs before continuing; do not assume discovery always creates a new tab. ### 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 | Low | According to Workspace Approvals policy | | Add folder | Medium | According to Workspace Approvals policy | | Remove folder | Medium | According to Workspace Approvals policy | | Delete workspace | High | According to Workspace Approvals policy | ### Connection Lifecycle 1. **Server start:** RepoPrompt opens its local bootstrap listener. 2. **Client launch:** The external tool spawns `repoprompt-mcp` with the generated `--backend app` arguments over stdio. 3. **Handshake:** The bridge connects locally and negotiates the tool surface. 4. **Admission:** The app validates the connection and requests approval when required. 5. **Binding:** The client resolves the intended workspace context before repository work. 6. **Active use:** Tool calls and responses flow between the client and the app. 7. **Disconnect:** The client closes, or the listener stops, and session resources are released. ### Reconnection Behavior A lost app connection and a client restart can require a fresh handshake and binding. Reconnection support does not guarantee replay of an interrupted edit, a running model request, or restoration of every window/tab selection. After reconnecting, inspect `bind_context op=status`, refresh the tool list if necessary, and inspect workspace or run state before retrying a mutation. Keep an agent run's returned `session_id` for its control operations, and use its latest snapshot to determine whether the run finished or still needs input. Do not start a duplicate run merely because the external client stopped waiting. ### Troubleshooting Connections #### Connection Not Appearing - Ensure MCP Server is enabled in Settings - Bring RepoPrompt forward and inspect pending connection requests - 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 - Inspect **Status Dashboard** and connection errors before resetting configuration; avoid deleting runtime files while the app is running #### Wrong Window/Tab Receiving Tools - Use `list_tabs` to verify which tab is bound - Use `select_tab` to explicitly bind to the correct tab - Use `bind_context op=status` and rebind the intended workspace roots or context ID :::tip **Pro Tip:** For long-running agent sessions, bind to the intended context using `bind_context` early in the session. This prevents context confusion if tabs are switched during operation. ::: --- ## MCP Server Overview (Mcp-server) ### 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. RepoPrompt CE's MCP server exposes file selection, Code Maps, Context Builder, Oracle conversations, edits, workspace and tab lifecycle, allowlisted app preferences, and policy-controlled Agent Mode session operations. Clients discover the tools available to their connection rather than assuming every tool is always exposed. The app-backed tools are reachable two ways: - **Direct MCP** — persistent connections for agents that natively speak MCP. - **[rpce-cli](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/#terminal-access)** — ephemeral shell invocations for agents and humans that prefer a terminal. Both surfaces let you switch workspaces, create tabs, select files, run Context Builder, consult an Oracle, apply edits, and update allowlisted preferences. Tool toggles, connection policy, workspace access, and Agent Mode permissions still apply. Some capabilities are only advertised inside an eligible Agent Mode or discovery session. #### Quick Access: MCP Controls Click the **MCP Server** indicator in the toolbar for quick access to the server popover. The adjacent lightbulb opens the [Setup Wizard](https://repoprompt.com/docs/1.6.0/mcp-server/setup-wizard/), which recommends model and agent settings. Toolbar controls: a Setup Wizard lightbulb and an MCP server icon Current MCP Server popover showing window access, Auto-Start, Oracle Model Presets, Context Builder, and Quick Setup **Key settings to configure:** - **Window access:** Enable MCP tools for the workspace window you want clients to use. - **Auto-Start:** Request automatic listener startup when you launch RepoPrompt. - **Oracle Model Presets:** Expose named Oracle configurations to external clients. Current source uses `oracle_utils` and `oracle_send`; Agent Mode also provides `ask_oracle`. - **Context Builder:** Review its selected CLI agent and model, and change them in Agent Models. - **Quick Setup:** Install the client integration and optional workflow instructions separately. The popover displays the count of currently advertised tools (typically **21 available** for standard external MCP clients, covering workspace lifecycle, file operations, Code Maps, context curation, Git, Oracle consultations, history, and the agent control plane). An additional set of policy-gated tools (`ask_user`, `ask_oracle`, `oracle_chat_log`, `agent_session_link`, `session_admin`, `become_overseer`, `self_compact`, `share_thoughts`, `set_status`, `wait_for_next_user_instruction`) are dynamically activated during eligible Agent Mode or oversight sessions. This guide follows the current implementation where it differs from Classic tool names. :::tip **Showing 0 tools?** First check that the listener is running and tools are enabled for the target window. Reconnect or restart the external client if it cached an earlier empty list. See [Setup troubleshooting](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/#troubleshooting-setup). ::: #### RepoPrompt as an IDE for Agents Think of RepoPrompt'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 an Oracle for planning, reviewing, and questions with your configured models. Oracle consultation and the agent's subsequent implementation are separate steps. ##### File Editing Create, move, and delete files. Apply search/replace edits or full rewrites with diff previews and applicable approval checks. Review the returned result rather than assuming every requested edit was applied. ##### Workspace Management List, switch, and create workspaces. Manage compose tabs for parallel tasks. Full programmatic control. ##### Multi-Window Support Use multiple windows for different workspaces. Clients discover and bind workspace context through `bind_context`; compose-tab binding keeps a selection and prompt isolated from UI tab changes. ##### 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](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/) for details. ##### App Settings Read and update allowlisted preferences for appearance, prompt packaging, models, MCP preset visibility, Code Maps, file scanning, selected Agent Mode behavior, and notifications through `app_settings`. See [App Settings Tool](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-app-settings/) for the current catalog. Auto-Start and permission policies remain app controls. #### Architecture Overview The MCP server uses a secure, local-only architecture with UNIX socket transport: **Local Socket Transport:** External Client → repoprompt-mcp bridge (stdio) → UNIX Socket → RepoPrompt App The app bridge uses local UNIX sockets, without exposing an MCP TCP listener. Client admission and filesystem permissions protect access. This describes the client-to-app connection: Oracle, Context Builder, and agent requests can still contact the AI providers you configure. #### Compatible Clients RepoPrompt CE provides native one-click configuration for: - **Claude Code** — Anthropic's official coding CLI with deep MCP and skill integration - **Cursor** — AI-native code editor with deeplink MCP installation - **Codex CLI** — OpenAI's CLI agent with isolated prompt and skill discovery - **VS Code** — Visual Studio Code with standard stdio MCP configuration - **OpenCode** — Modern open-source terminal coding assistant - **Claude Desktop** — Anthropic's desktop application - **Any MCP Client** — Any client supporting the open Model Context Protocol standard Compatible clients can also install RepoPrompt's built-in [Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/), providing slash commands for orchestration, deep planning, optimization, code review, refactoring, implementation, bug investigation, and prompt exporting. #### Sibling: rpce-cli Prefer a shell, or running on an agent that doesn't natively speak MCP? The same tools are reachable from [`rpce-cli`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/#terminal-access), 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](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-app-settings/) for the CLI view of the same `app_settings` surface. #### Quick Start: claude-rpce For a preconfigured Claude Code launch, install the `claude-rpce` wrapper from **Settings → MCP Server → CLI Tools**. Use the corresponding debug command name when running a debug build. 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-rpce` 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 RepoPrompt's UI - **Human Oversight:** Approve connections, review edits before applying - **Reviewable Changes:** Inspect tool results, previews, and workspace state as agents work. #### Security Model - External clients pass the app's connection-admission checks; approval can be required for a new client process. - 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 - A shared listener serves window-scoped tools; each window's tool access and the connection's context binding determine where calls run. :::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. ::: --- ## Settings & Presets (Mcp-server) 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. Current MCP Server popover with window status, Oracle presets, Context Builder, and Quick Setup *Note: The screenshots (`mcp-server-popover.png` and `mcp-window-access.png`) are historical captures showing **21 available** tools. RepoPrompt defines **31 total domain tools**: **21 are advertised** to standard external MCP clients (**3 global** tools and **18 window-scoped** tools), while the remaining **10 policy-gated and sub-agent internal tools** are dynamically exposed within eligible Agent Mode and oversight sessions. See [Policy-Gated and Sub-Agent Internal Tools](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#policy-gated-and-sub-agent-internal-tools).* This is the primary location to configure the MCP server, including: - **Server activation** - Enable/disable MCP tools for external clients - **Oracle Model Presets** - Expose named Oracle model configurations to external clients - **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, RepoPrompt requests automatic listener startup on launch. This is useful if you always want MCP available for your AI tools. The target window must also have tools enabled. #### Status Indicator **Active** means the shared listener is running and tools are enabled for this window. **Waiting for listener…** means window access is enabled but the listener is not running. With window access disabled, a running listener can still serve other windows. The connection badge shows attached clients; the window number identifies the window being configured. Window access, Auto-Start, and connection count The full Settings pane also offers **Status Dashboard** for diagnostics and **Force Stop Listener**. Force Stop affects every window and client; use the window access switch to limit only this window. A running tool can expose a **Cancel** action. ### Oracle Model Presets Control which AI models are available to MCP clients when they use the `oracle_send` and `oracle_utils` tools. #### Use Oracle Model Presets for MCP When enabled, configured Oracle presets are exposed to MCP clients, allowing an agent to select from named model configurations. A preset can supply the primary model, additional Oracles, and its mapped Chat Preset. Grouped Oracle requests run their models independently and keep their results separate. When presets are disabled, the current Oracle configuration supplies the default. If no presets are defined, the popover offers the Oracle fallback model choice. If the Setup Wizard temporarily hid presets, **Show presets** restores their exposure without deleting their definitions. Oracle Model Presets with Manage, the model picker, and Show presets #### How Agents Use Presets Use `oracle_utils` with `op="models"` to discover model choices, then `oracle_send` to consult an Oracle. A `model` override is valid only for an explicit `new_chat=true` start. An exact exposed preset UUID or name takes precedence over a raw model identifier; continuing an existing conversation preserves its established configuration. ```json {"op":"models"} ``` The JSON above is passed to `oracle_utils`. A new consultation can then use an exposed preset: ```json {"message":"Review the selected changes for regressions.","mode":"review","new_chat":true,"model":"Review"} ``` Pass the second object to `oracle_send`, substituting a preset name returned by your own connection. Manage definitions in [Model Presets](https://repoprompt.com/docs/1.6.0/settings/model-presets/) or click **Manage** in the popover. Older Classic tool names `list_models` and `chat_send` have been replaced in the current source contract. ### 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 The row summarizes the CLI agent and model used by `context_builder`. Change them in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/), where global settings and workspace overrides are shown explicitly. Supported choices depend on configured providers and the Context Builder selection surface; the model shown in the screenshot is an example. Context Builder agent and model summary [Setup Wizard](https://repoprompt.com/docs/1.6.0/mcp-server/setup-wizard/) recommendations use the same model-selection engine. Discovery configuration is independent of the Oracle models used for the plan, question, or review that follows. #### How context\_builder Works When an MCP client calls `context_builder` with task instructions, RepoPrompt's Context Builder agent: 1. Analyzes the task requirements 2. Explores the codebase to find relevant files 3. Builds a selection toward the configured context budget 4. Returns the selection, or runs the requested plan, question, or review with Oracle context This enables AI agents to automatically gather context without manual file selection. ### Quick Setup The popover's **Install…** menu has three groups: **MCP Server** configures a client connection, **CLI (rpce-cli)** provides terminal access, and **claude-rpce (Claude Code wrapper)** provides a preconfigured Claude Code launcher. **Skills** installs reusable workflow instructions separately. Installing one of these does not install or authenticate the client application itself. #### Install MCP Server Choose a client under **MCP Server** in **Install…**. The Settings pane labels this button **Install MCP…** and places terminal installation actions in its separate **CLI Tools** section. | Option | What it configures | | --- | --- | | **Cursor** | Opens Cursor's MCP installation link with RepoPrompt's generated server configuration. Complete the installation in Cursor. | | **VS Code** | Opens VS Code's MCP installation link with the generated stdio server entry. Complete the client-side setup. | | **Codex CLI** | Configures and enables the server in RepoPrompt's isolated Codex configuration and installs its MCP workflow prompts there. This does not configure every separate Codex installation or its ordinary user home. | | **OpenCode** | Adds the persistent MCP server entry to `~/.config/opencode/opencode.json`. RepoPrompt's runtime agent modes are separate from this persistent connection entry. | | **Claude Desktop** | Adds the server entry to Claude Desktop's configuration. The installer reports failure if Claude Desktop's application-support folder is absent; install and open that client first. | | **Claude Code (per-project)** | Runs Claude Code's MCP installation command in each loaded workspace root. Open the intended project folders first and make sure the Claude Code CLI is installed. | The two **Install to PATH** and **Uninstall from PATH** pairs belong to different commands, as described below. Restart or reconnect the selected client if it does not discover its new MCP configuration immediately. Install menu with six MCP client choices, rpce-cli PATH actions, and separate claude-rpce wrapper PATH actions #### CLI Installation (rpce-cli) Under **CLI (rpce-cli)**, **Install to PATH** installs the managed `rpce-cli` command in `/usr/local/bin` for terminal access to RepoPrompt's MCP tools. This enables scripting, automation, and interactive codebase exploration. macOS can request administrator authorization to write that location; the directory must be on your shell's PATH to invoke the command by name. **Uninstall from PATH** removes that managed terminal command. It does not uninstall RepoPrompt CE or remove MCP configurations already added to external clients. Debug builds use `rpce-cli-debug`, so use the command name displayed by the running build. ```bash rpce-cli -e 'call get_file_tree {"type":"roots"}' rpce-cli -e 'call workspace_context {"include":["selection","tokens"]}' ``` #### claude-rpce Wrapper Under **claude-rpce (Claude Code wrapper)**, **Install to PATH** installs a managed launcher in `/usr/local/bin`. It runs an already-installed Claude Code CLI with RepoPrompt's MCP configuration, strict MCP configuration mode, and the built-in Read, Write, Edit, Glob, and Grep tools disabled. This directs those file operations through RepoPrompt's tools. The wrapper's **Uninstall from PATH** removes its managed launcher, not Claude Code itself or the separate `rpce-cli` command. Debug builds use `claude-rpce-debug`. The wrapper requires the Claude Code CLI and a running RepoPrompt app with MCP tools enabled. **Why use claude-rpce?** - **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 ```bash # Instead of running: claude # Run: claude-rpce # This automatically: # - Points to RepoPrompt's MCP config # - Enables strict MCP mode (ignores other configs) # - Disables Claude's built-in Read, Write, Edit, Glob, Grep tools ``` :::info **Prerequisite:** RepoPrompt must be running with MCP Server enabled for `claude-rpce` to work. ::: #### Skills Menu **Skills** installs reusable workflow prompts: `/rp-orchestrate`, `/rp-deep-plan`, `/rp-optimize`, `/rp-review`, `/rp-refactor`, `/rp-build`, `/rp-investigate`, `/rp-oracle-export`, and `/rp-reminder`. Choose a destination based on which client should discover them and whether they should apply across projects or only within the loaded project folders. | Menu group and option | Scope and destination | | --- | --- | | **Shared (.agents/skills) → Global (~/.agents/skills)** | Installs shared skill directories under your home folder for clients that discover this convention, including Codex and other compatible agents. | | **Shared (.agents/skills) → Per-project (.agents/skills)** | Installs shared skills in each loaded workspace root's `.agents/skills` folder. Use this to keep instructions project-specific. | | **Claude Code (.claude/commands) → Per-project** | Installs Claude Code workflow skills for the loaded roots. The menu retains the older `.claude/commands` label; the current implementation writes `.claude/skills//SKILL.md` and migrates legacy flat command files. | | **RepoPrompt Codex (isolated prompts) → Global** | Installs workflow prompt files in the `prompts` directory of RepoPrompt's isolated Codex home. Global here means that isolated environment, not every external Codex installation. | Each destination submenu offers **MCP skills**, **rpce-cli skills** (or the running build's CLI name), and **Uninstall**. The MCP variant instructs an agent to call RepoPrompt tools directly. The CLI variant instructs it to use the installed terminal command and uses skill names with a `-cli` suffix. Choose the variant that matches how your client accesses RepoPrompt; installing a CLI variant does not install the executable for you. **Uninstall** removes RepoPrompt-managed MCP and CLI workflow files from the chosen destination, leaving unrelated skills alone. Per-project install options require loaded workspace folders and are disabled or report **Open a folder first** when none are available. The grey section labels and **Works with Codex and other agents** text are descriptions, not additional actions. Skills menu showing global and per-project shared skills, per-project Claude Code skills, and global prompts in RepoPrompt's isolated Codex environment This installs workflow instructions as skill folders or prompt files for the chosen destination; it does not connect a client, authenticate a provider, or expand tool permissions. If the client has already loaded its instruction files, refresh its picker or restart it. See [Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/) for the current command catalog. #### Copy JSON Copies the MCP server configuration to your clipboard for manual installation in any MCP-compatible client: ```json { "mcpServers": { "RepoPromptCE": { "command": "/path/to/repoprompt-mcp", "args": ["--backend", "app"] } } } ``` :::info **Note:** After installing, restart the client application if the integration isn't detected immediately. ::: ### Advanced Settings The Settings pane contains **CLI Tools** and expandable **JSON Configuration** sections beyond the popover. CLI rows report **Installed**, **Not installed**, **Needs update**, or **Exists but not managed**, with actions appropriate to that state. Debug builds use their separate debug command names. Use **Status Dashboard** for connection diagnostics and active-client inspection. Individual tool enablement is documented in [MCP Tools settings](https://repoprompt.com/docs/1.6.0/settings/tools/). Workspace context routing is described in [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/). See [Transport & Security](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-transport/) and [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/) for details. --- ## Setup Guide (Mcp-server) Get RepoPrompt CE's MCP server connected to your preferred AI tool. The server enables external agents to use RepoPrompt's context building, code intelligence, editing, and workspace capabilities. ### Quick Setup 1. Open a workspace in RepoPrompt CE, then click the toolbar's **MCP Server** icon or open **Settings → MCP Server**. 2. Enable MCP tools for that window. **Active** confirms both a running listener and enabled window access; **Waiting for listener…** means the window is enabled but the listener is not ready. 3. Under **Quick Setup**, open **Install…** (shown as **Install MCP…** in Settings) and choose your client. 4. Restart or reconnect that client if it does not discover the integration immediately. Respond to any connection request shown in RepoPrompt. 5. Discover and bind the intended workspace before running repository tools. MCP window status and Auto-Start controls ### Client-Specific Instructions The installer generates configuration for the CE app you are running. Use it instead of carrying an old Classic executable path into the new client configuration. #### Cursor Open **Quick Setup → Install… → Cursor**. RepoPrompt opens Cursor's MCP installation link with its generated command configuration. Complete the client-side installation, then reconnect or restart Cursor. Approve the connection in RepoPrompt if requested. #### Claude Code Choose **Claude Code (per-project)** from the Install menu with the intended workspace folders loaded. The installer configures those projects. Alternatively, copy the generated JSON and add its server entry using your client's MCP configuration workflow. Restart the client when necessary and verify that it discovers RepoPrompt CE's tools. #### Codex CLI Choose **Codex CLI** from the Install menu. RepoPrompt updates the Codex MCP configuration with the generated app bridge and its supported timeout settings. Restart or reconnect Codex after installation. Use the installer rather than a hand-written `codex.toml` example from an older guide. #### Other Supported Clients The current Install menu also offers **VS Code**, **OpenCode**, and **Claude Desktop**. OpenCode installation targets its CLI configuration; Claude Desktop installation reports if the application is not found. Client installation and provider authentication are different operations: installing MCP does not sign a CLI agent in to its AI service. #### Other MCP Clients Copy the JSON with the copy button beside **Skills**, or expand **JSON Configuration** in Settings. Add the generated server entry to your client's MCP server configuration. The client launches the bundled `repoprompt-mcp` bridge over stdio, and the bridge connects to the app locally. ### Configuration Format The generated app-backed configuration has this shape. The command below is a placeholder; replace it with the exact absolute path copied from the running app. ```json { "mcpServers": { "RepoPromptCE": { "command": "/absolute/path/copied/from/RepoPrompt/repoprompt-mcp", "args": ["--backend", "app"] } } } ``` The `--backend app` arguments explicitly select the running app backend. The command normally uses a managed user-space link, with a bundled executable path as a fallback. CE release and debug builds have distinct identities. Always copy the configuration for the build you intend to connect to. ### Connection Approval When an external client needs approval, RepoPrompt shows a **Connection Request** overlay with its client and, when available, executable information. The current implementation offers **Allow Session** or **Allow Once**, depending on whether an executable identity is available, and **Deny**. Review the actual client process before approving. The older Classic instructions about an **Always Allow** choice do not describe this overlay. Connection approval admits the client; it does not approve every workspace mutation, file edit, or agent operation. Those actions remain subject to their own policies. See [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/). ### Verifying the Connection Check that the intended RepoPrompt window reports **Active** and that the connection badge shows an attached client. In the external client, ask the agent to discover available tools, call `bind_context` with `op="list"`, and bind the intended workspace roots. Then request `get_file_tree` or a `workspace_context` snapshot. ```json {"op":"bind","working_dirs":["/Users/example/Project"]} ``` This JSON is an arguments object for `bind_context`, not a complete client configuration. Use exact workspace root paths; see [context binding](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/#context-binding) for tab-specific isolation. ### Terminal Access In Settings, the **CLI Tools** section installs **rpce-cli** for shell access and **claude-rpce** as the Claude Code wrapper. Debug builds use **rpce-cli-debug** and **claude-rpce-debug**. Follow the row's **Install** or **Update** action, then use the command name it displays. The app must be running with MCP access enabled for app-backed calls. For example, after installing the release CLI, `rpce-cli -e 'call get_file_tree {"type":"roots"}'` calls the same repository tool from a shell. The CLI supports JSON arguments; it does not use the obsolete `rp-cli tree` and `rp-cli context --all` examples from Classic documentation. ### Workflow instructions Use **Quick Setup → Skills** to install MCP or CLI workflow instructions for your client. The installer writes skill folders or prompt files, depending on the destination, for commands such as `/rp-orchestrate` and `/rp-build`. It does not install the server connection itself. See [Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/) for destinations, variants, and the complete command catalog. Quick Setup with Install, Skills, and copy-configuration controls ### Troubleshooting Setup Use the [MCP Troubleshooting FAQ](https://repoprompt.com/docs/1.6.0/faq/mcp-troubleshooting/) to distinguish connection failures, missing tools, wrong context bindings, and model-service errors. #### Client can't find repoprompt-mcp Re-copy the configuration from the installed CE app and check that its command path exists. Avoid pointing a CE client at an old Classic app or a different debug build. If the CLI Tools row reports **Needs update**, use **Update** before reconnecting. #### No approval dialog appears Check window access and listener status first. Bring RepoPrompt forward and look for a pending connection request. Inspect **Status Dashboard** and any error indicator in Settings before changing configuration. A client that was never launched or has the wrong executable path cannot reach the approval step. #### Connection keeps dropping Restart the external client after confirming the app and listener are running. Re-copy configuration after changing app builds. The app bridge uses UNIX sockets; the current setup has no user-facing **Filesystem transport** switch, and firewall or VPN changes are not the first troubleshooting step. #### Tools not appearing in client Check [MCP Tools](https://repoprompt.com/docs/1.6.0/settings/tools/) and the target window's access switch. Disabled tools, global Code Maps suppression, and connection policy can reduce the advertised list. Reconnect or restart a client that cached an earlier list; the screenshot's **21 available** is not a fixed count for every build or session. Once connected, explore the [Tools Reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/), use the [Setup Wizard](https://repoprompt.com/docs/1.6.0/mcp-server/setup-wizard/) for model recommendations, or read [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/) for workspaces and compose tabs. --- ## Tools Reference (Mcp-server) This reference follows the current RepoPrompt CE source contracts. Tools are organized by category; ordinary tool toggles live in [MCP Tools settings](https://repoprompt.com/docs/1.6.0/settings/tools/). Some tools are additionally limited to Agent Mode, discovery, or an authorized control relationship. Your connection's live schema determines which tools and arguments are available. The MCP settings status displays **21 available** tools for standard external client connections. RepoPrompt defines **31 total domain tools** (`MCPDomainToolCatalog.swift`): - **21 advertised tools** exposed to standard external MCP clients, consisting of **3 global tools** (`app_settings`, `bind_context`, `manage_workspaces`) and **18 window-scoped tools** (`agent_explore`, `agent_manage`, `agent_run`, `apply_edits`, `context_builder`, `file_actions`, `file_search`, `get_code_structure`, `get_file_tree`, `git`, `history`, `manage_selection`, `manage_worktree`, `oracle_send`, `oracle_utils`, `prompt`, `read_file`, `workspace_context`). - **10 policy-gated and sub-agent internal tools** (`ask_user`, `ask_oracle`, `oracle_chat_log`, `agent_session_link`, `session_admin`, `become_overseer`, `self_compact`, `share_thoughts`, `set_status`, `wait_for_next_user_instruction`) that are reserved for and dynamically activated within eligible Agent Mode and cross-session oversight contexts. See [Policy-Gated and Sub-Agent Internal Tools](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#policy-gated-and-sub-agent-internal-tools). ### Tool catalog at a glance These short descriptions follow the built-in Settings catalog shown in the reference screenshot. The detailed sections below explain current arguments, limitations, and behaviors; use the schema advertised by your connected build for the exact contract. | Tool | What it does | | --- | --- | | [`agent_explore`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#agent_explore) | Starts short-lived, read-only Explore agents for focused codebase probes. Each child gets a fresh session and context. | | [`agent_manage`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#agent_manage) | Lists agents, sessions, and workflows; reads logs and handoffs; creates, resumes, stops, or cleans up eligible sessions. | | [`agent_run`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#agent_run) | Starts and controls Agent Mode sessions, including waiting for input, steering, responding, and cancellation. | | [`app_settings`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#app_settings) | Reads or updates the allowlisted RepoPrompt preferences. Settings outside the allowlist are not exposed. | | [`apply_edits`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#apply_edits) | Applies a whole-file rewrite, one literal replacement, or a batch of literal replacements. Choose exactly one mode. | | [`bind_context`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#bind_context) | Discovers, inspects, and binds the workspace context for this MCP connection. | | [`context_builder`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#context_builder) | Explores the codebase, selects relevant files, and builds task context within a token budget. | | [`file_actions`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#file_actions) | Creates, moves, or deletes files. Paths are absolute; deletion moves items to Trash. | | [`file_search`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#file_search) | Searches file paths, contents, or both, with regex, extension, path, and exclusion filters. | | [`get_code_structure`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#get_code_structure) | Returns root-local Code Map structure for files, folders, or the current selection. | | [`get_file_tree`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#get_file_tree) | Generates a project directory tree or lists loaded root folders. | | [`git`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#git) | Inspects Git status, diffs, history, file versions, and blame without committing or pushing. | | [`history`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#history) | Searches Agent Mode session history across saved workspaces and reads bounded transcript excerpts. | | [`manage_selection`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#manage_selection) | Manages selected files and their representation as full content, line slices, or Code Maps. | | [`manage_workspaces`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#manage_workspaces) | Manages workspaces, folders, and Compose tabs across RepoPrompt windows. | | [`manage_worktree`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#manage_worktree) | Manages Git worktrees and session bindings, and supports previewing or applying session-bound merges. | | [`oracle_send`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#oracle_send) | Starts or continues an Oracle conversation for chat, planning, or review. | | [`oracle_utils`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#oracle_utils) | Discovers Oracle model choices or lists Oracle conversations; it does not send messages. | | [`prompt`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#prompt) | Reads or changes shared prompt text, and lists or selects copy presets. | | [`read_file`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#read_file) | Reads a workspace file in full or by line range. | | [`workspace_context`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#workspace_context) | Builds, renders, or exports the current workspace context and its selected components. | The descriptions in this catalog explain purpose, not permission. A tool being listed or enabled does not grant workspace approval, connect a provider, or bypass a tool's validation rules. ### Changes from Classic | Classic example | Current source contract | | --- | --- | | `chat_send` | `oracle_send` for external consultations; `ask_oracle` inside eligible Agent Mode sessions. | | `list_models` | `oracle_utils` with `op="models"`. | | `chats` list/log | `oracle_utils op="sessions"`; eligible Agent Mode runs can use `oracle_chat_log`. | | Initial routing through select_tab | Prefer `bind_context` discovery and binding. Legacy compose-tab lifecycle actions remain available. | | Fixed five-minute agent waits | Configurable sub-agent default wait, with explicit per-call timeouts. | | App settings editing or auto-start keys | Use the current [allowlist](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-app-settings/); obsolete keys are rejected. | ### Context Binding #### `bind_context` List, inspect, and bind the workspace context used by this MCP connection. `op` is `list`, `status`, or `bind`. Bind with absolute `working_dirs` workspace roots or a `context_id` returned by discovery. `create_if_missing` requests creation when no suitable workspace exists, subject to approval. The current global schema does not accept `window_id`. ```json {"op":"bind","working_dirs":["/Users/example/Project"]} ``` Use a returned `context_id` when a stable compose-tab context is required. See [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/#context-binding). ### 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: \[{start\_line, end\_line, description}\]} | | `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. With op=set, full and codemap_only replace the corresponding selection, while slices replaces slices for the specified files and preserves unrelated full files and slices. Manual codemap_only, promote, or demote operations disable automatic codemap management. Use the returned selection to check the final representation. #### `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, Code Maps, and token counts in a single call. Default includes are `prompt`, `selection`, `code`, and `tokens`; full file contents and the selected-file tree are opt-in. Additional operations are `snapshot`, `export`, `list_presets`, and `select_preset`. Use `path` for export and returned preset identities for selection; `copy_preset` overrides rendering or token-calculation presets. #### `prompt` Get or modify the shared prompt/instructions text. | Parameter | Description | | --- | --- | | `op` | get \| set \| append \| clear \| export \| list_presets \| select_preset | | `text` | Text for set/append operations | | `path` | Output file for export | | `preset` | UUID, kind, or name for select_preset; requires an explicitly bound tab | | `copy_preset` | Optional export rendering override | #### `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) | An external app-backed call creates a fresh compose tab and runs discovery toward the context budget. During Agent Mode, it reuses the current agent tab. A `question`, `plan`, or `review` response adds Oracle analysis and returns conversation information for follow-up. Continue with the Oracle tool advertised to your connection, using the returned `chat_id`. `export_response=true` can write generated analysis to a shareable file. App-backed analysis also accepts an exposed `oracle_preset` to select its Oracle roster independently of discovery. Direct-headless execution uses a separate `context_pack_ref` contract for a persisted frozen package and rejects `oracle_preset`. Runtime depends on repository size, task scope, provider latency, and analysis type. ### 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 term or path pattern. Required. | | `mode` | `auto` (default), `path`, `content`, or `both`. Auto detects path versus content search from the pattern. | | `regex` | Regex is auto-detected by default. Set `false` for literal content matching or glob-style path matching; set `true` to force regular expressions. | | `context_lines` | Number of surrounding lines to include for content matches. | | `whole_word` | Match complete words only. | | `count_only` | Return match counts without match content. | | `max_results` | Maximum results to return (default: 50). | | `filter` | Optional `extensions`, `exclude`, and `paths` constraints. `paths` limits search to loaded workspace roots or subfolders. | Regex mode supports groups, lookarounds, and anchors. Literal mode treats special characters as text; in path mode, `*`, `?`, and `**` remain path wildcards. Large responses can be capped, with excess results omitted and the count reported. #### `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`). Reuse exact returned workspace paths. For an explicit root-qualified path, use `//`. Current read and edit resolution does not guess by basename or suffix. A worktree-bound session can show logical paths while reading from its bound checkout; inspect worktree_scope when returned. #### `get_code_structure` Get root-local Code Maps for explicit files/directories or the current selection, with optional dependency expansion. | Parameter | Description | | --- | --- | | `paths` | Optional seed files or directories; omit for the current selection. | | `expand` | `uses`, `used_by`, or `both`; omit for seeds only. | | `depth` | Relationship depth 1–4; default 1 when expansion is requested. | | `signatures` | Include signature text; default true. False requests graph-only output. | | `size` | `small`, `medium` (default), or `large`. | Inspect per-root results in mixed workspaces. `updates_pending` data can still be usable; if output reports truncation, retry with a larger `size`. Classic's `scope` and `max_results` examples are not the current schema. Global Code Maps disabling suppresses this tool. #### `file_actions` Create, delete, or move files. | Parameter | Description | | --- | --- | | `action` | create \| delete \| move | | `path` | Absolute file or folder path for every action. | | `content` | File content (for create) | | `new_path` | Absolute destination path for move. | | `if_exists` | error (default) \| overwrite | All create, delete, and move paths must be absolute, including in a single-root workspace. Create makes missing parent directories and selects the new file; `if_exists` defaults to `error`, while `overwrite` permits replacing an existing file. Delete moves the item to the macOS Trash, where it remains recoverable until Trash is emptied. Move fails if the destination exists and transfers the file's selection state. The optional operation_id is a correlation identifier, not a deduplication or replay-safety token. #### `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 {search, replace, all} for multiple edits | | `rewrite` | Complete file content for full rewrite | | `all` | Replace all occurrences (default: false) | | `verbose` | Include diff preview in response | | `on_missing` | For rewrite only: error (default) or create. | Rewrite, single search/replace, and an edits array are mutually exclusive request modes. Supply exactly one. An optional operation_id is echoed as correlation information; it does not make a repeated edit safe to replay. Applies validated edits with applicable approval checks. Use diff previews and returned status to confirm results. Workspace paths use literal-first exact resolution: reuse returned paths unchanged, or use `//` for explicit root qualification. Basename and suffix guessing are not supported. Approved external read paths remain read-only. :::tip **CLI usage:** `apply_edits` requires JSON format via `rpce-cli`: ```bash rpce-cli -e 'call apply_edits {"path":"file.ts","search":"old","replace":"new"}' rpce-cli -c apply_edits -j edits.json # From .json file (auto-detected) rpce-cli -c apply_edits -j @edits.json # From file (explicit @) echo '...' | rpce-cli -c apply_edits -j @- # From stdin ``` Use valid JSON with the intended literal search and replacement text, and inspect validation errors rather than relying on input repair. ::: ### Oracle & Model Tools #### `oracle_send` Start or continue Oracle conversations for questions, planning, or review using the configured context and models. | Parameter | Description | | --- | --- | | `message` | Your message to send | | `new_chat` | Set true to force a new conversation; otherwise a missing chat_id resumes the selected or most recent eligible conversation. | | `mode` | chat \| plan \| review | | `model` | Exposed preset name/UUID or available raw primary model override; valid only with explicit new_chat=true. | | `chat_id` | Specific chat to continue | | `export_response` | Write the response to a shareable file and return its export information. | **Modes:** - **chat:** General conversation - **plan:** Architectural planning without immediate edits - **review:** Code review with git diff context from selected files An exact exposed preset identity wins over a raw model ID and supplies the complete Oracle roster and mapped Chat Preset. A raw override replaces the primary while retaining configured additional Oracles. Continuation preserves the established conversation configuration and rejects model overrides. Oracle consultation is separate from the agent applying file edits. #### `ask_oracle` During eligible Agent Mode runs, consult an Oracle in the current agent context with `message`, optional `chat_id`, `new_chat`, `mode`, and `export_response`. Omit chat_id or set new_chat=true to start; otherwise continue that conversation. Current source also allows a primary `model` override on a new conversation and rejects it on continuation. Use the tool actually advertised to your connection. #### `oracle_utils` Read-only helpers for model choices and Oracle conversation discovery. | Parameter | Description | | --- | --- | | `op` | models \| sessions | | `context_id` | Narrow sessions to a context UUID returned by bind_context. | | `scope` | workspace \| tab; context_id infers the narrowed scope. | | `limit` | Bound the session list. | With `op="models"`, list model choices and exposed presets relevant to Oracle sends. Use a returned identity rather than guessing a model or preset name. With `op="sessions"`, discover conversations to inspect or continue. #### `oracle_chat_log` During eligible Agent Mode runs, recover recent Oracle messages after compaction or while continuing a consultation. Supply optional `chat_id`, `limit` of 1–50 messages (default 8), and `include_user` (default false). This reads history without sending a new turn. ### Git Tools #### `git` Safe, token-efficient git abstraction for MCP agents. Also supports Jujutsu (jj) repositories natively. See [Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/#git-integration) for review-oriented usage. | 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 \| hide \| unhide \| 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 for supported lifecycle operations; separate from bind_context. | | `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. #### `manage_worktree` List, inspect, create, and bind Git worktrees for Agent sessions, or preview and apply a session-bound merge. Management operations are `list`, `show`, `create`, `bind`, `select`, and `unbind`; merge operations are `preview`, `apply`, `status`, `continue`, and `abort`. Use returned worktree IDs and an explicit session_id when routing does not resolve an active Agent session. Preview is non-mutating; apply requires its operation_id and the applicable confirmation or routed UI approval. Continue and abort require confirmation outside routed UI flows. See [Worktrees](https://repoprompt.com/docs/1.6.0/worktrees/). The source must be clean and committed, and the target must be clean. For the human review card, stale previews, and conflict recovery in the target checkout, see [Review and Merge](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/). ### App Settings #### `app_settings` Read and update allowlisted global preferences for appearance, prompt packaging, models, Context Builder, MCP preset visibility, Code Maps, file scanning, selected Agent Mode behavior, and notifications. Credentials, tool ACLs, permission policies, and workspace model override dictionaries are excluded. | Parameter | Description | | --- | --- | | `op` | `list` \| `get` \| `set` \| `options` | | `group` | `ui`, `prompt_packaging`, `models`, `context_builder`, `mcp`, `code_maps`, `file_system`, `agent_mode`, `notifications`. 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, string array, or null, matching the catalog's declared type. The additional Oracle roster is an array; `prompt_packaging.prompt_sections_order` is a string containing a JSON array, not a native array. | | `agent` | For options: filter to a supported CLI backend, such as claudeCode or codexExec. | | `limit` | For `options`: maximum number of candidates returned (1–200, default 60). | | `detailed` | For `options`: include descriptions and model metadata in each candidate. | Call list first to discover the actual keys and types in the running build. Obsolete Classic editing and auto-start keys are not part of the current registry. **Examples:** ```bash # Browse the catalog (values always included) { "op": "list" } # Inspect one group { "op": "list", "group": "ui" } # Batch read { "op": "get", "keys": ["ui.appearance_mode", "mcp.show_model_presets"] } # Toggle a flag { "op": "set", "key": "ui.show_tooltips", "value": false } # Clear an optional model { "op": "set", "key": "models.planning_model", "value": null } # Switch the Context Builder agent (remembered model is preserved) { "op": "set", "key": "context_builder.agent", "value": "codexExec" } # List candidate values for a setting that advertises options_available { "op": "options", "key": "models.planning_model", "agent": "codexExec" } ``` **See the standalone** [App Settings Tool](https://repoprompt.com/docs/1.6.0/mcp-server/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 RepoPrompt's Agent Mode sessions. ::: #### `agent_run` Session-based control surface for long-running Agent Mode runs. Each start returns a session_id for poll, wait, steer, respond, and cancel. Use agent_manage for durable session history and metadata. Discover authoritative role mappings in its task_labels response; an omitted start model_id resolves through the pair role. Explicit model/effort targets come from the live catalog. Start-only worktree arguments can establish an isolated checkout before provider startup. When Model Router is enabled, new starts with an omitted model_id or a role label can be routed across configured sub-agent targets. A compound model_id or explicit model_parameters pins the target and bypasses that automatic routing. A wait timeout bounds the waiting call; inspect the returned status and keep monitoring an active run rather than starting a duplicate. **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`, optional `timeout` | Blocks until input is needed or a terminal/interesting state is reached. A multi-session wait returns when the first session reaches such a state. Default is the configured sub-agent wait, initially 120 seconds. Timeout=0 polls immediately. 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 the existing session, injecting into an active run or starting its next run after completion. Optional wait=true or timeout_seconds waits for a result using the configured default when no explicit timeout is given. Use respond for waiting_for_input. Start always creates a new session. | | `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:** Depending on state and operation, responses can include session_id, status, status_text, assistant_text, transcript_item_count, failure_reason, session identity and parentage, and available agent/model information. Use the current snapshot's interaction_id and advertised response choices rather than reusing an older pending interaction. **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:** 1. Call `agent_run op=start message="..."` → receive `session_id` 2. Call `agent_run op=wait session_id="..."` → waits up to the configured duration or explicit timeout until input is needed or the run reaches an interesting state 3. When `status=waiting_for_input`, call `agent_run op=respond` with the returned `interaction_id` and an appropriate `response` 4. 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` | optional `roles_only` | List task_labels role mappings and exact agent/model/effort targets. roles_only=true omits the full explicit target catalog. | | `list_sessions` | `limit`, `state` | List live and persisted sessions, returning session IDs. Agent Mode callers are scoped to their spawned sessions. Filter by advertised state values; MCP-originated sessions are identified in the response. | | `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 up to 256 unique valid MCP-originated session UUIDs. User-created and active sessions are protected. Validates the array before mutation and reports per-ID outcomes; inspect partial, cancellation, and retry results. | | `extract_handoff` / `handoff` | `session_id` | Export handoff XML for a live or persisted session. Use output_path for a file; file-content snapshots require an active live source context. | | `list_workflows` | — | List available agent workflows. | **Session IDs:** Use returned full UUIDs. Within agent_manage, use list_sessions for metadata and get_log for faithful transcript XML with turn pagination. The separate history tool has a bounded get_session operation for historical search results. **Workflow runs:** To start a workflow-backed run, use agent_run op=start with workflow_id or workflow_name and a message. Then use its returned session_id for wait, respond, and other run-control operations. #### Agent Control Plane Examples ```bash # Discover available agents and workflows agent_manage op=list_agents agent_manage op=list_workflows # List recent sessions, filter by state agent_manage op=list_sessions limit=10 agent_manage op=list_sessions state=failed # Read a session transcript agent_manage op=get_log session_id="" limit=5 # Stop a running session agent_manage op=stop_session session_id="" # Clean up old MCP-originated sessions agent_manage op=cleanup_sessions session_ids=["",""] # Start a run and control it agent_run op=start message="Investigate the auth flow" agent_run op=wait session_id="" agent_run op=wait session_id="" timeout=10 # Steer and wait for result in one call agent_run op=steer session_id="" message="Now fix it" wait=true # Respond to a pending approval agent_run op=respond session_id="" interaction_id="" response="accept" # Respond to a question agent_run op=respond session_id="" interaction_id="" response="Use the staging API" # Start a workflow-backed run agent_run op=start workflow_id="" message="Add logout support" # Then use agent_run to wait/respond on the returned session_id # Orchestrate: start multiple agents in parallel, wait for the first to finish agent_run op=start model_id="engineer" message="Task A" detach=true # → session_id_1 agent_run op=start model_id="engineer" message="Task B" detach=true # → session_id_2 agent_run op=wait session_ids=["",""] timeout=60 # Poll all agents at once for a dashboard view agent_run op=poll session_ids=["","",""] # Use the orchestrate workflow for automatic planning and delegation agent_run op=start workflow_name="orchestrate" message="Refactor auth into separate module" ``` :::tip **Tool Availability:** Individual tools can be enabled or disabled in **MCP Tools settings**. Disabled tools are withdrawn from the advertised list. Agent control tools are also gated by connection policy and may not appear on every connection. ::: ### Policy-Gated and Sub-Agent Internal Tools In addition to the 21 advertised tools above, RepoPrompt defines **10 policy-gated and sub-agent internal tools** that are omitted from the standard external catalog and activated dynamically within eligible Agent Mode and authorized cross-session oversight contexts: | Tool | Brief Description | | --- | --- | | [`ask_user`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#ask_user) | Prompts the user with structured questions, optional suggested answers, and configurable timeouts. | | [`ask_oracle`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#ask_oracle) | Consults the configured Oracle model directly from an eligible Agent Mode session. | | [`oracle_chat_log`](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#oracle_chat_log) | Reads recent Oracle conversation history (`limit` 1–50) during an Agent Mode run without sending a new turn. | | `agent_session_link` | Manages cross-window and cross-session communication links, steering, model targeting, and auto-wake snoozing. | | `session_admin` | Administers sessions within a user-granted delegation scope, including session tree inspection, organization, worktree binding, and merge coordination. | | `become_overseer` | Requests promotion of the calling session to an overseer role to coordinate sibling sessions. | | `self_compact` | Requests self-compaction or context inspection (`op="context"` or `"compact"`) of the agent's own session context. | | `share_thoughts` | Publishes reasoning thoughts or plan progress to the session timeline. | | `set_status` | Updates the human-visible status indicator on the session card. | | `wait_for_next_user_instruction` | Signals that the agent has completed its turn and is waiting for the next user instruction. | ### Exploration, History, and Session Coordination #### `agent_explore` Launch short-lived read-only exploration children for narrow codebase probes. Operations are start, poll, wait, and cancel. Supply message or a batch of messages, save the returned session IDs, and use session_id or session_ids for monitoring. The role is always Explore, with no custom model/workflow selection, session reuse, steering, or responding. Explore children cannot edit, consult Oracles, or recursively delegate. Start-only worktree controls can isolate their reads. #### `history` Search saved Agent Mode transcripts across workspaces with list_sessions, search, time, and bounded get_session operations. Window context does not automatically restrict history to one workspace; pass a workspace filter when needed. Search first, then read a small turn window using the returned session ID and turn location. Narrow truncated scans by workspace, dates, or session rather than requesting a whole transcript. #### `ask_user` Ask structured questions, each with stable id and question fields and optional suggested answers. Title and context frame the interaction. The optional timeout_seconds overrides the global Question Timeout. Inspect timed_out, skipped, and answers keyed by question ID. Availability depends on the session's interaction policy. #### Oversight tools For the interface and ordinary task workflow, see [Overseer Mode](https://repoprompt.com/docs/1.6.0/overseer/), including [Lanes](https://repoprompt.com/docs/1.6.0/overseer/lanes/) and [Linking Sessions](https://repoprompt.com/docs/1.6.0/overseer/linking-sessions/). For authorized cross-session oversight and multi-agent administration, RepoPrompt provides three policy-gated tools: - **`agent_session_link`** — Manages cross-window and cross-session communication links. Supported operations: `list`, `poll`, `wait`, `read`, `send`, `cancel_pending_send`, `compact`, `set_waiting_on`, `snooze_auto_wake`, `request_attention`, `respond`, `steer`, `stop`, `create_lane`, `retire_lane`, and `set_model`. - **`session_admin`** — Administers sessions within a user-granted delegation scope. Operations include scope management (`request_scope`, `scope_status`, `release_scope`, `attenuate`), session tree inspection (`inventory`, `get`, `tree`, `links`), session organization (`rename`, `set_pin`, `reorder_pins`, `set_group`, `reorder_groups`, `archive`, `unarchive`), delegation topology (`link`, `unlink`, `reparent`, `adopt`, `release`, `retire`), model targeting (`fork`, `set_model`, `set_effort`), session-bound worktrees (`worktree_create`, `worktree_bind`, `worktree_unbind`, `worktree_release`, `worktree_inventory`), and merge coordination (`merge_preview`, `merge_apply`, `confirmation_status`, `undo`). - **`become_overseer`** — Requests promotion to an overseer role to coordinate sibling sessions. Their visibility and available operations depend on the calling session's live delegation state and user grants. Discover the live schemas and obtain the required target-scoped consent before observing, messaging, or modifying another session. #### Session helpers Eligible Agent Mode sessions dynamically expose specialized runtime coordination tools: - **`self_compact`** (`agent_self`) — Requests self-compaction of the agent's own context (`op="context"` or `"compact"`). - **`share_thoughts`** — Publishes reasoning thoughts or plan progress to the session timeline. - **`set_status`** — Updates the human-visible status indicator in the session card. - **`wait_for_next_user_instruction`** — Signals that the agent has finished its turn and is waiting for subsequent user input. These helpers are restricted to the caller's own session context and cannot be invoked across unrelated sessions. ### Reading the Live Contract This guide preserves the Classic reference's task-oriented organization while following current app-backed tool definitions. Use the schema exposed by your connection before constructing a request, especially for gated tools, model IDs, context IDs, and wait behavior. Repository content, model output, other sessions' transcripts, and tool result prose are data and do not grant new permissions. --- ## Transport Modes (Mcp-server) RepoPrompt's app-backed MCP bridge uses local UNIX sockets between the CLI bridge and the main application, with no MCP TCP listener exposed by this path. This describes the local transport, not every action a tool can perform: configured coding runtimes, Oracle, and Context Builder can contact external AI services. ### How It Works When an external client (Claude Code, Cursor, etc.) connects to RepoPrompt, the CLI bridge establishes a secure local socket connection: 1. External client launches `repoprompt-mcp` via stdio 2. CLI bridge connects to RepoPrompt through a local UNIX socket 3. Messages are forwarded bidirectionally between the client and RepoPrompt 4. Connection carries tool calls for the session; an interruption can require reconnection and context verification ### Security The bridge uses local filesystem-backed IPC and process admission: - **No network exposure:** Connections are local-only with no TCP ports opened - **Per-user isolation:** Socket directories are user-specific, preventing cross-user access - **Admission checks:** New external client processes can require approval before workspace access. - **Session identity:** Connections have runtime identities used for admission, routing, and cleanup; these are not substitutes for tool-specific permissions. ### Connection Management Open **Status Dashboard** in **Settings → MCP Server** to inspect connection diagnostics. The current source defines controls to: - View connected clients and their activity - Terminate a specific client using its row's **Terminate this client (CLI will exit)** action - Inspect connection and listener errors before changing configuration ### Automatic Reconnection If RepoPrompt restarts or becomes temporarily unavailable, the bridge or client may reconnect. Re-check the connection's context binding and tool list after interruption. Reconnection does not guarantee that an interrupted edit or Oracle request can be safely replayed; inspect the result or run state before resubmitting work. ### Troubleshooting - **Connection refused:** Ensure MCP Server is enabled in Settings and RepoPrompt is running - **Approval not appearing:** Check that the client is using a compatible version of the CLI - **Unwanted client connection:** Inspect its identity in **Status Dashboard**, then use the row's terminate action if you intend to make that client's CLI exit :::tip **Local bridge:** No MCP TCP port is opened by this app-backed path. That does not make model execution offline: configured CLI agents, Context Builder, and Oracle consultations may contact external AI services. ::: ### Generated Backend Selection Use the app-generated command and `args: ["--backend", "app"]` for the UI-backed integration. A direct-headless backend is a separate execution mode; it is not a transport toggle and does not imply the same window context or UI behavior. The current server UI does not offer Classic's **Filesystem transport** fallback or a **Multi-Window Mode** switch. Older configuration structures can contain legacy transport preferences, but they are not instructions to change firewall, VPN, or local-network permissions for this socket bridge. ### Window Access and Shared Listener The listener is shared, while MCP tool access is controlled per window. Disabling a window's tools is different from stopping the listener. **Force Stop Listener** in Settings shuts down the listener for every window and client; use the per-window access switch when only that window should stop exposing tools. See [Settings & Presets](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-settings/) for the controls and [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/) for context binding and reconnection checks. --- ## Setup Wizard (Mcp-server) The Setup Wizard recommends a configuration based on your available providers and the app's best-practice profiles. It helps align Oracle models, Context Builder, MCP preset exposure, and sub-agent role defaults. It configures model choices; installing the external MCP client connection remains a separate step in [Setup Guide](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/). ### Open the Wizard Click the toolbar's lightbulb to open **Setup Wizard**. The neighboring server icon opens the MCP Server popover. A yellow lightbulb indicates active recommendations. Toolbar lightbulb for Setup Wizard beside the green MCP server icon The intro lists recommendations, provider status, and a **Best Models by Use Case** reference. **Start Wizard** reviews the recommendations step by step. **Quick Apply All** applies eligible, unsatisfied recommendations that have not been muted. Setup Wizard intro with one Context Builder recommendation, provider status, best-model reference, Quick Apply All, and Start Wizard The screenshots capture particular model choices, connected providers, and a four-step walkthrough from an earlier build. Recommendations change with the app's catalog, provider availability, settings, and provider filter. See [Models → Recommendations and screenshots](https://repoprompt.com/docs/1.6.0/providers/models/#recommendations-and-screenshots) for how to interpret these examples. The number and order of steps also vary: satisfied or muted recommendations can be omitted, while an available role-defaults review can still be shown. ### Check the Settings Scope Read the **Agent Models** label near the heading and footer before applying a recommendation. **Global settings** means the workspace inherits the global Agent Models profile, so changes affect that profile. **Workspace — [name]** means the wizard targets that workspace's overrides. The wizard follows the effective Agent Models scope; it is not always creating workspace-local changes. MCP preset exposure has its own global scope. A recommendation to hide or show presets changes what MCP can discover without deleting the saved presets. Use [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/) to inspect inheritance, workspace overrides, Oracle models, and role defaults. ### Choose Providers for Recommendations Open **Providers** to choose which provider families the recommendation engine may consider. The screenshot includes Codex CLI, Claude Code, Cursor CLI, Grok Build, and OpenAI API. Unchecked providers are excluded from the next recommendation calculation. Providers for Recommendations popover with five checked provider families, Reset, and Apply Choose **Apply** to recompute recommendations using the selected set, or **Reset** to restore all providers. This filter shapes recommendations; it does not install a provider, authenticate an account, disconnect an integration, or change which provider a manually selected session can use. Provider readiness and the selection filter are separate facts. ### Review Context Builder The Context Builder step shows a recommended agent, model, and explanation. Context Builder explores your codebase and selects files toward a context budget before the requested follow-up analysis. Its discovery model is distinct from the Oracle model used for a plan, review, or answer. Context Builder recommendation showing the selected Codex discovery model and its explanation **Apply & Next** saves the recommendation to the displayed settings scope and advances. **Skip** advances without applying it. **Back** returns to an earlier step. The recommendation in the screenshot is not a model you must choose; configure a supported, authenticated provider that fits your account and task. Change the discovery model later in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/); question behavior and context budgets live in [Context Builder settings](https://repoprompt.com/docs/1.6.0/settings/context-builder/). Complete Context Builder recommendation step with Back, Skip, overflow menu, and Apply & Next controls ### Skip or Mute a Recommendation Skipping leaves the current settings as they are. To dismiss a recurring recommendation, open the step's overflow menu and choose **Mute this recommendation**. The intro also offers a dismissal control beside active recommendations. Muting suppresses that recommendation in the wizard; it does not apply the recommended value. Muted differences can appear under **Dismissed Recommendations**, with **Restore** to make them eligible for review again. This is separate from **Show presets** in the MCP popover, which restores preset exposure. Full wizard footer with Skip, the overflow menu, Apply & Next, and Mute this recommendation ### Review Agent Role Defaults The role-defaults step shows the recommended CLI agent and model for each task label. External callers use these roles when launching agents without pinning an exact compound model target. The current `agent_run` contract resolves an omitted `model_id` through the `pair` role; clients can discover the authoritative role mappings with `agent_manage op="list_agents"` and its `task_labels` response. | Role | Intended work | | --- | --- | | **Explore** | Fast, read-only exploration and codebase mapping. | | **Engineer** | Balanced engineering work. | | **Pair** | Interactive pair programming with a higher-capability model (default when `model_id` is omitted in `agent_run`). | | **Design** | Architecture, design critique, and creative problem solving (produces Markdown design/review documents under `docs/`). | Agent Role Defaults step with Explore, Engineer, Pair, and Design model choices and a Configure button Use **Configure…** to inspect or adjust the role configuration, then **Next** to continue. The model names shown are examples, not permanent defaults for every installation. An explicit model target from the live agent catalog can pin a different provider/model/effort combination. ### Summary and Next Steps The Summary shows the resulting Oracle and role configuration, including settings that already matched. **All Set!** can therefore appear without applying a change during this walkthrough. Check the summary and choose **Done** to close it. Wizard Summary showing an already-matching Oracle and role configuration, followed by Context Builder and MCP next steps Try Context Builder from the Compose view to curate context, or connect an external client and invoke `context_builder` over MCP. Consult the [Tools Reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/) for the current names and parameters rather than using tool names from older Classic guides. Complete Summary step showing the matched configuration, next steps, Back, and Done ### When No Recommendations Are Needed If the effective configuration already matches the selected best-practice profile, the wizard can report **Your setup looks good!** and offer **Close**. Some builds present this as **Setup Status** with provider status, reference models, and any dismissed recommendations. It confirms the recommendation check; it does not prove that an external client is installed or connected. Setup Wizard reporting no recommendations, with provider status and the best-model reference Use the [MCP Server popover](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-settings/) to verify window access and connections, and [Setup Guide](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/) to install the client integration. --- ## Workflow Commands (Mcp-server) RepoPrompt's workflow instructions guide an external coding agent through a process: understanding a task, finding relevant code, planning, delegating, implementing, or reviewing. Commands such as `/rp-build` select those instructions; they are not additional MCP tools or server-enforced execution pipelines. Depending on the installation target, the instructions are packaged as on-disk skills or prompt files. A **skill** is the discoverable package; the **workflow instructions** are the procedure it contains. The MCP connection supplies the tools that the procedure can request. Install these separately from the MCP server configuration through **Quick Setup → Skills**. Then use your client's skill or slash-command picker to find commands such as `/rp-orchestrate`, `/rp-deep-plan`, and `/rp-build`. The picker and invocation syntax depend on the client; `/repo` is not a universal command that every integration provides. Quick Setup Skills menu entry beside client installation and copy configuration ### Installing workflow instructions The **Skills** menu offers shared global or per-project `.agents/skills`, Claude Code integration, and RepoPrompt's isolated Codex prompts. Select the **MCP** variant when the agent uses native MCP tools, or the **CLI** variant when it calls `rpce-cli`. CLI variants use the corresponding `-cli` skill names (such as `/rp-orchestrate-cli` or `/rp-deep-plan-cli`). Install the CLI executable as well when choosing that variant. | Menu Group and Option | Scope and Destination | Variant and Invocation | | ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Shared (.agents/skills) → Global** | `~/.agents/skills//SKILL.md` | Shared convention for Codex CLI and compatible agents across all projects. | | **Shared (.agents/skills) → Per-project** | `/.agents/skills//SKILL.md` | Installs in each loaded workspace folder for project-isolated workflows. | | **Claude Code (.claude/commands) → Per-project** | `/.claude/skills//SKILL.md` | Installs modern Claude Code skills in each loaded root and migrates legacy flat command files. | | **RepoPrompt Codex (isolated prompts) → Global** | `~/.repoprompt/codex/prompts/.md` | Installs workflow prompts in RepoPrompt's isolated Codex environment. | Each destination submenu offers **MCP skills**, **rpce-cli skills** (or the running build's CLI name), and **Uninstall**. The MCP variant instructs an agent to call RepoPrompt tools directly. The CLI variant instructs it to use the installed terminal command (`rpce-cli`). Choose the variant that matches how your client accesses RepoPrompt. :::note[Skills and Agent Mode Workflows] Installed workflow instructions, Agent Mode's workflow templates, and Copy/Chat Workflow Presets are distinct configuration surfaces. The server connection alone does not install the external instruction files. Use [Agent Workflows](https://repoprompt.com/docs/1.6.0/settings/agent-workflows/) for the in-app Workflow picker and [Workflow Presets](https://repoprompt.com/docs/1.6.0/settings/workflow-presets/) for copy and built-in chat packaging. ::: ### How Workflow Commands Work The installed implementation, planning, review, and investigation workflow templates instruct the coding agent to use repository discovery, explore-agent delegation, and the appropriate Context Builder/Oracle calls. Their templates direct workflows such as `/rp-build` and `/rp-orchestrate` through steps like these: 1. **Workspace verification** — The agent verifies that the target repository is bound and loaded before initiating any planning or tool execution. 2. **Surface mapping & reconnaissance** — The agent contextualizes the prompt into actual codebase nouns, optionally fanning out parallel read-only `explore` agents for targeted reconnaissance. 3. **Context curation via Context Builder** — A specialized research model explores the codebase, selecting files within a token budget using full content for key files and codemaps for reference files. 4. **Analysis & specification** — An advanced analysis model receives the curated context and produces an architectural plan, review, or investigation report. 5. **Delegated execution or implementation** — The agent acts on the result: either directly implementing changes with `apply_edits` or orchestrating specialized sub-agents (`pair`, `engineer`, `design`) with clean context boundaries. The intended separation keeps the coordinator focused while sub-agents or Context Builder handle the heavy reading. These are workflow instructions, not an MCP-enforced execution order: the host application and its coding agent control whether and in what order tools are invoked, subject to available tools and permissions. ### Available Commands RepoPrompt installs a comprehensive suite of workflow commands. External agents discover these as slash commands matching their installed variant (`/rp-` for MCP, `/rp--cli` for terminal CLI): #### 1. Orchestrate (`/rp-orchestrate`) **Plan, decompose, and delegate complex tasks across multiple agents.** ```text /rp-orchestrate ``` - **Arguments:** `task` (required) — Description of the complex task to plan, decompose, and delegate. - **Primary Roles:** Orchestrator (coordination), `pair` (default for complex multi-file work), `engineer` (clear/well-scoped items), `design` (UI, layout, polish, text), `explore` (narrow reconnaissance). - **Core Philosophy:** The orchestrator coordinates, plans, and verifies; it does **not** implement code directly or perform deep reading itself. Sub-agents execute each work item in fresh context windows to prevent context exhaustion and hallucination. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms the target codebase is loaded and identified before planning. - **Phase 1: Contextualize the Task** — Translates user instructions into concrete codebase nouns (modules, filenames, patterns). Dispatches a narrow `explore` agent if ambiguous, then calls `context_builder` with `response_type: "plan"` and `export_response: true` to generate an architectural plan file. - **Phase 2: Decompose into Work Items** — Breaks the plan into up to 5 discrete, ordered work items with explicit "done when" criteria, file boundaries, dependencies, and verification steps. - **Phase 3: Dispatch (Verify-then-Dispatch Loop)** — Dispatches fresh sub-agents for each work item. Sub-agents read the exported plan file via `read_file` as read-only context. Alternatively, tightly coupled items can steer an existing agent. The orchestrator updates the plan file via `apply_edits` as items are completed. - **Phase 4: Monitor and Verify** — Verifies each completed item against its acceptance criteria, runs tests, and produces a final rollup of completed work and known follow-ups. --- #### 2. Deep Plan (`/rp-deep-plan`) **Deep planning workflow that produces a polished, ready-to-execute plan document without implementation.** ```text /rp-deep-plan ``` - **Arguments:** `topic` (required) — Description of what to plan (feature, refactor, migration, redesign). - **Sole Deliverable:** A polished, executable specification document at `docs/plans/-.md`. - **Core Philosophy:** Strictly planning only. Explore agents map seams and external research; Context Builder generates the implementation specification baseline; a design agent performs an independent critique; the orchestrator retains authorial ownership, ensuring lossless consolidation and verified references. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms workspace readiness. - **Phase 1: User Involvement Decision (Required First Interactive Action)** — Uses `ask_user` to prompt the user for their preferred involvement level: - **Up front** — Grounded interview before broad exploration begins (pauses in Phase 1.5). - **Mid-flow** — Review the draft before the design agent critique (pauses in Phase 5). - **Hands-off** — Complete the full plan autonomously, then refine interactively (pauses in Phase 7). _(Note: If Up front or Mid-flow is chosen, a subsequent timeout on `ask_user` halts the run rather than guessing.)_ - **Phase 1.5: Grounded Interview** _(only if Up front)_ — Dispatches 1–2 narrow ambiguity scouts, then asks 2–4 code-grounded questions before proceeding. - **Phase 2: Map the Seams** — Fans out parallel explore agents across three distinct lanes: in-workspace seams (always), external research (APIs/libraries/RFCs), and prior art (`docs/plans/`, commit history). - **Phase 3: Scaffold the Plan File** — Creates `docs/plans/-.md` seeded with Goal, Background (distilled evidence), Open Questions, and References. - **Phase 4: Context Builder Plan Pass** — Calls `context_builder` with `response_type: "plan"` and `export_response: true`. Builds a coverage ledger of all implementation-bearing facts, interfaces, error cases, and verification requirements. - **Phase 5: Mid-flow Check-in** _(only if Mid-flow)_ — Pauses to ask 2–4 targeted draft ambiguity questions via `ask_user`. - **Phase 6: Bounded Completeness and Design Critique** — Dispatches a `design` agent to evaluate the draft against the codebase and original Context Builder export, writing a focused review under `docs/reviews/`. - **Phase 7: Fidelity-Preserving Editorial Polish** — Integrates critique findings, verifies every symbol/link/line reference, removes transcript narration, and ensures the document is directly executable. - **Phase 7.5: Final Fidelity Check & Cleanup** — Walks the coverage ledger to confirm no supported detail was dropped, then safely deletes the temporary export file. --- #### 3. Optimize (`/rp-optimize`) **Iterative performance optimization loop run as a delegation-first orchestration.** ```text /rp-optimize ``` - **Arguments:** `target` (required) — Metric, scope, and stop criterion (e.g., `"reduce p95 latency of PathMatcher.match under PathMatchingTests"`). - **Core Philosophy:** Performance work only improves what can be measured. Gathers evidence outward from callers, inputs, and shared infrastructure; gates all instrumentation behind debug flags; preserves causality with one attributed change per serial loop; and records all runs in a persistent scoreboard. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms the target repo is loaded. - **Phase 1: Surface Mapping & Bottleneck Scouting** — Fans out parallel `explore` agents across five areas: bottleneck candidates around target callers and inputs, target & call graph, prior perf work (benchmarks/traces), conventions (sanctioned test/bench commands in AGENTS.md), and scope boundaries. - **Phase 2: Plan Setup with Context Builder** — Runs `context_builder` (`response_type: "plan"`, `export_response: true`) to define the metric, debug-gated instrumentation strategy in a secondary support file, baseline procedure, ranked first-pass candidates, and the scoreboard scaffold. - **Phase 3: Land Instrumentation & Baseline** — Dispatches a `pair` agent to land debug-only instrumentation, verify release builds strip it, take 3–5 baseline samples, and initialize `prompt-exports/optimize--runs.md`. - **Phase 4: The Optimization Loop (Serial)**: - **4a. Plan next optimization** — Uses Context Builder with the scoreboard in selection to plan one single change. - **4b. Dispatch optimize-and-harden** — Dispatches one `pair` agent to implement the change, run tests, re-measure, and append a new row to the scoreboard. - **4c. Verify via scoreboard** — Compares results against the variance band and confirms test passage. - **4d. Consult Oracle on next step** — Prompts the Oracle (`oracle_send` or `ask_oracle`) with the updated scoreboard to decide whether to continue or stop. - **Termination:** Exits when the Oracle signals diminishing returns, the target metric is met, or the hard 5-iteration cap is reached. - **Phase 5: Final Rollup** — Summarizes starting vs. final metric deltas, landed optimizations, reverted attempts, and state of instrumentation. --- #### 4. Review (`/rp-review`) **AI-powered code review combining Git diffs and branch comparisons with architectural codebase understanding.** ```text /rp-review [scope] ``` - **Arguments:** `scope` (optional) — Comparison scope: `'uncommitted'` (default), `'staged'`, `'back:N'` (last N commits), or a branch/commit range like `'main...HEAD'`. - **Core Philosophy:** Surface-level reviews catch typos; deep reviews catch subtle architectural regressions, security oversights, broken error paths, and API contract violations. Combines Git diff inspection with RepoPrompt's semantic context. **Workflow Steps:** - **Step 0: Verify Workspace** — Confirms the target repository window. - **Step 1: Survey Changes** — Runs `git op="status"`, `git op="log"`, and `git op="diff" detail="files"` to inspect modified files and commit history. - **Step 2: Determine Scope** — Infers or confirms the comparison target (e.g. comparing current branch against `main` or merge-base). - **Step 3: Deep Review via Context Builder** — Calls `context_builder` with `response_type: "review"`, supplying diff files and comparison scope. Context Builder gathers relevant surrounding types and architecture, invoking the review model to evaluate correctness, security, breaking changes, and edge cases. - **Step 4: Clarify Findings** — Optionally continues the conversation via `oracle_send` (or `ask_oracle`) in the returned chat session to explore remediation steps or investigate specific findings. --- #### 5. Refactor (`/rp-refactor`) **Refactoring assistant that analyzes code organization, identifies duplication and complexity, and safely implements improvements.** ```text /rp-refactor [target] ``` - **Arguments:** `target` (optional) — Files, directory, or module to analyze (e.g., `'Sources/Auth'`, `'the networking layer'`). - **Core Philosophy:** Strictly preserves external behavior while improving readability, cohesion, and testability. Uses explore agents to scout before planning, and verifies tests after every individual change. **Workflow Steps:** - **Step 0: Verify Workspace** — Confirms repository binding. - **Step 1: Scope & Analyze** — Dispatches parallel `explore` agents to map types, dependencies, and duplication across the target area, then runs `context_builder` with `response_type: "review"` informed by those findings. - **Step 2: Plan** — Runs `context_builder` with `response_type: "plan"` and `export_response: true` to generate an incremental, risk-assessed refactoring plan. - **Step 3: Decompose & Dispatch** — Breaks the refactoring plan into discrete work items and dispatches `pair` or `engineer` sub-agents to implement changes step by step. - **Step 4: Verify** — Runs project tests after each step, spot-checks diffs for semantic preservation, and confirms that public API contracts remain unchanged. --- #### 6. Plan & Build (`/rp-build`) **End-to-end implementation workflow for new features, bug fixes, and significant codebase additions.** ```text /rp-build ``` - **Arguments:** `task` (required) — Description of the feature or task to implement. - **Core Philosophy:** Avoids shallow implementations by requiring orientation and deep context gathering before touching code. Context Builder generates the architectural blueprint; the agent then executes changes directly using RepoPrompt's editing tools. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms workspace context. - **Phase 1: Quick Scan** — Runs lightweight directory tree (`get_file_tree`) and targeted searches (`file_search`, `get_code_structure`) to map user instructions to exact codebase components. - **Phase 2: Context Builder** — Calls `context_builder` with `response_type: "plan"` using the reformulated prompt. Context Builder curates full files and codemaps into context, returning an actionable implementation plan. - **Phase 3: Consult Oracle (Optional)** — If the plan leaves concrete ambiguities, consults the Oracle (`oracle_send`) to resolve specific questions before editing. - **Phase 4: Implement Directly** — Applies changes iteratively using `apply_edits` (single search/replace, edits array, or full rewrite) and `file_actions`, verifying results against diff previews and running relevant unit tests. --- #### 7. Investigate (`/rp-investigate`) **Systematic, hypothesis-driven bug and root-cause investigation.** ```text /rp-investigate ``` - **Arguments:** `issue` (required) — Description of the bug, crash, regression, or research topic. - **Core Philosophy:** Read-only source inspection, with findings, traces, and hypotheses written to an investigation report. The current template explicitly prohibits source-code changes; it gathers concrete evidence before forming conclusions and separates external fact-finding from workspace context. **Workflow Phases:** - **Phase 0: Workspace Verification** — Confirms workspace readiness. - **Phase 1: Initial Assessment & Triage** — Reads error logs, crash reports, or issue descriptions, forms initial hypotheses, and creates `docs/investigations/-.md`. - **Phase 1.5: External Fact-Gathering** _(conditional)_ — Dispatches parallel `explore` agents for facts outside the workspace (git history/blame archaeology, web searches, external documentation), recording results in `## Background / Prior Research`. - **Phase 2: Broad Context Gathering** — Runs `context_builder` with instructions referencing the investigation report to discover relevant source files and populate context. - **Phase 3: Deep Investigation** — Dispatches a `pair` investigator to trace code paths, test hypotheses, and record concrete findings under `## Investigator Findings`. - **Phase 4: Selection Curation & Oracle Synthesis** — Curates the file selection to include newly surfaced files and line slices, then calls Oracle (`oracle_send` or `ask_oracle`) to synthesize cross-component insights. - **Phase 5: Final Report Synthesis** — Finalizes the report with confirmed root causes, supporting line-level evidence, and proposed remediation steps. --- #### 8. ChatGPT Export (`/rp-oracle-export`) **Builds optimized codebase context and exports a self-contained, ChatGPT-ready prompt file.** ```text /rp-oracle-export ``` - **Arguments:** `problem` (required) — Description of the question, plan, or review to export. - **Core Philosophy:** Extracts the real underlying task, selects the optimal files within token limits, and exports a clean markdown prompt to `prompt-exports/` ready to be copied into ChatGPT or other external models for a second opinion. **Workflow Steps:** - **Step 0: Workspace Verification** — Confirms repository context. - **Step 1: Determine Intent & Scope** — Classifies the prompt intent into **Question** (specific bounded query), **Plan** (architectural/design problem without diffs), or **Review** (git diff / branch comparison). - **Step 2: Choose Context Path** — - _Fast Path_: Used only when the scope is already tiny, concrete, and file-local. - _Deep Path (Default)_: Uses `context_builder` with `response_type: "clarify"` to curate optimal full files, slices, and codemaps within token budgets. - **Step 3: Review and Export** — Verifies prompt text and token counts with `workspace_context`, then exports a unique markdown prompt file under `prompt-exports/-export.md`. --- #### Utility & Helper Commands ##### Tools Reminder (`/rp-reminder`) A token-efficient prompt (available as `/rp-reminder` or `/rp-reminder-cli`) that reminds agents to use RepoPrompt's specialized MCP tools (`file_search`, `read_file`, `get_file_tree`, `get_code_structure`, `apply_edits`, `file_actions`, `git`, `manage_selection`, `workspace_context`, `context_builder`, `oracle_send`, `ask_user`, `agent_run`, `agent_manage`) instead of generic shell commands like `grep`, `cat`, `sed`, `find`, or `ls`. | Task | Recommended MCP Tool | Avoid Shell Alternatives | | ---------------------------- | -------------------- | -------------------------------- | | Search paths/content | `file_search` | `grep`, `find`, `Glob` | | Read file (whole or sliced) | `read_file` | `cat`, `head`, `tail` | | Project directory tree | `get_file_tree` | `tree`, `ls -R` | | Code signatures & structure | `get_code_structure` | Reading entire source files | | Edit file contents | `apply_edits` | `sed`, custom rewrite scripts | | Create / move / delete files | `file_actions` | `touch`, `mv`, `rm` | | Git status / diff / blame | `git` | Shelling out to raw git commands | --- ### Context Builder Response Types The workflow commands above leverage the `context_builder` MCP tool. You can also invoke Context Builder directly with different response types: - **`clarify`** _(default)_ — Builds curated file context only. Returns selected files, slices, and codemaps without running follow-up analysis. - **`plan`** — Generates a comprehensive architectural and implementation plan grounded in actual codebase patterns. - **`question`** — Answers complex architectural or code questions using deep contextual understanding. - **`review`** — Generates an in-depth code review evaluated against Git diffs and surrounding system architecture. Use `export_response: true` on any analysis response type (`plan`, `question`, `review`) to write the generated response to a shareable markdown file. The returned `oracle_export_path` and `oracle_export_instruction` allow seamless hand-off to child agents or persistent project records. ### Git Integration The `git` tool provides safe, token-efficient git operations for MCP agents: `status`, `diff`, `log`, `show`, `blame`, and snapshot diff artifacts. It also natively supports Jujutsu (`jj`) repositories. For complete tool arguments, comparison specs, and worktree options, see the [Git reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#git). ### Custom Skills Beyond the supplied workflow commands, you can write your own workflow instructions and package them as skills for a compatible external host to discover. The instructions can describe specialized testing, migrations, or project-specific procedures; the host determines how they are invoked and followed. Learn how to create and install custom skills in [Skills & Slash Commands](https://repoprompt.com/docs/1.6.0/agent-mode/skills/). :::tip[Getting Started] After setting up the MCP connection, open your client’s skill or slash-command picker to discover the installed commands. For more detail on each workflow and the Context Builder pipeline, see [Agent Mode Workflow Commands](https://repoprompt.com/docs/1.6.0/agent-mode/workflows/). ::: --- ## Best Practices (Overseer) An overseer works best when it has a clear goal, a small set of independently useful tasks, and explicit rules for bringing the results together. Give it enough authority to coordinate the work you intend, and keep the review points visible in the conversation. ### Divide work by deliverable Choose lanes with distinct outcomes: an investigation report, an implementation in a specified checkout, a focused regression review, or documentation of a completed change. Give each a completion criterion and identify dependencies. Ask the overseer to summarize who owns each task before overlapping implementation starts. Use [execution locations](https://repoprompt.com/docs/1.6.0/sessions/execution-location/) and worktrees to separate simultaneous edits. Conversation isolation does not prevent two agents from changing the same file in a shared checkout. Tell the overseer how results should be compared or integrated and who should resolve conflicting changes. Start with a small group. More lanes add usage, coordination work, and possible conflicting assumptions. Use a short read-only exploration task when you need one narrow answer rather than a durable session. ### Choose how updates wake the overseer Status updates are attached to the overseer's next turn even when routine automatic waking is disabled. The wake controls decide whether updates can also start additional model turns: Overseer wake controls and their effects Control | Use and limitation Auto-wake on all updates | Enables routine follow-up turns for selected linked sessions. It is on by default and saved for the overseer session. Lane Auto-wake | Selects an individual lane for routine wake behavior. Snooze status Auto-wake… | Temporarily defers that lane's routine status wakes. Routine wake-ups no more often than | Sets a minimum interval across routine oversight wakes. Deferred updates remain queued. Wake when idle for | Adds a wake after the chosen idle interval while overseeing another session, even without an update. Each wake uses a model turn. Wake now | Processes pending updates immediately when the overseer is able to accept a turn. An explicit attention request from an exactly linked session can bypass the routine master switch, lane selection, snooze, and routine interval without changing those settings. **Wake now** also bypasses the routine interval. Use **Unlink** to end the relationship when you need to prevent further purposeful attention through that link. Automatic turns can generate more updates, so even one relationship can sustain repeated activity. Sessions that oversee each other can keep waking one another. Prefer a clear coordination direction and enable periodic waking only for work that needs it. A busy overseer finishes its current and already-accepted work before taking eligible update-driven follow-up work. ### Review results and approvals An **Idle** row means the session is not working; it does not prove the task met its acceptance criteria. Ask the overseer to identify evidence, remaining risks, and unfinished work. Open the lane's transcript and inspect key diffs or tool results before accepting a consequential conclusion. Oversight can handle eligible one-time approvals, but session-wide permission grants, secret inputs, hook trust, and merge reviews remain with you. The optional **Auto-approve read-only commands** switch is off by default and applies only to a restricted set of simple commands on managed lanes. It does not approve arbitrary shell work, setup scripts, or all Git operations. ### Finish and recover deliberately Retire completed lanes only after their work is inactive and reviewed. Retirement stashes the session without deleting it or integrating its changes. Unlink independently created sessions when their coordination purpose ends. If a row is unavailable or a saving warning appears, inspect the session and resolve the displayed condition. Use **Retry saving** where offered. Avoid asking the overseer to allocate another lane just because a previous response was incomplete; first determine whether the earlier session exists and has begun work. For setup and relationship direction, revisit [Overview](https://repoprompt.com/docs/1.6.0/overseer/), [Lanes](https://repoprompt.com/docs/1.6.0/overseer/lanes/), and [Linking Sessions](https://repoprompt.com/docs/1.6.0/overseer/linking-sessions/). --- ## Lanes (Overseer) A **lane** is a separate top-level Agent session created by an overseer for a defined piece of work. It has its own conversation, provider/model selection, and task state, and is linked to its creator so the overseer can coordinate it. Use lanes for work you want to inspect and continue as ordinary sessions rather than treating every task as a short-lived probe. ### Create lanes from the coordinating session Start an eligible session, open its oversight control, and choose **Enable overseer mode**. Then ask the agent to create lanes with names and clear responsibilities. You can describe the roles in ordinary language: > Create an implementation lane for the cancellation fix and a review lane to inspect it independently. Give each a clear completion criterion. Confirm their execution locations before editing shared files. The agent can choose an available role mapping—**Explore**, **Engineer**, **Pair**, or **Design**—or an explicit supported model. Role mappings come from [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/); they are model choices for lane creation, not blanket approval to use every tool. A lane can be created without starting work, or with an initial task and optional workflow. A session with an eligible existing oversight relationship can already create lanes through that relationship. The separate **Enable overseer mode** activation is useful when starting without links; you do not need to unlink working relationships just to create lanes. The current lane limit is **12 per overseer**. Availability, workspace admission, and applicable delegation limits can reduce what can be created. A refusal does not mean another lane should be allocated blindly; inspect existing sessions and any saving warning first. ### Give every lane an independent job Define its deliverable, scope, and stopping point. “Investigate why cancellation leaves a stale row and report evidence” is a useful investigation. “Fix everything” makes ownership and completion harder to assess. Specify the intended workspace when work spans projects. Lane creation needs an unambiguous open workspace destination. A created lane is a top-level session, so do not assume it inherits the safety profile of an MCP sub-agent or a separate checkout. Inspect its permissions and [execution location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/). Use worktrees for concurrent edits that may overlap. Lanes created by an overseer cannot activate themselves as overseers. Keep the coordinating plan in the parent conversation and let the lane concentrate on its assigned result. ### Follow progress and continue work The oversight popover shows the lane's state, identity, location information, and recent activity. Open it directly to inspect messages or tool cards. The overseer can read progress, send more instructions, handle eligible pending interactions, and stop a run within the granted relationship. For an idle managed lane, the overseer can adjust an available model within the same provider for the next turn. This does not change the model in the middle of an active task or switch it silently to another provider. Ask for a fresh session when a different execution environment is required. ### Retire a finished lane Ask the overseer to retire a lane it created after its work and relevant descendants are inactive. Retirement unlinks and stashes the lane; it does not delete the conversation or merge its changes. Inspect the result, record remaining follow-ups, and integrate the repository work separately. **Unlink** can end oversight without retiring the session. **Delete** in session management is a separate, permanent action. If lane creation or retirement reports an incomplete save, use the existing session identity and resolve the saving condition before asking for a replacement. See [Linking Sessions](https://repoprompt.com/docs/1.6.0/overseer/linking-sessions/) to coordinate conversations that were created independently of the overseer. --- ## Linking Sessions (Overseer) Link existing sessions when work is already underway and you want one agent to coordinate it. The direction matters: an **overseer** receives authority over an **overseen session**. Linking A to oversee B does not automatically make B an overseer of A. ### Link from the composer 1. Open the intended overseer's session and its oversight popover. Start a first message if the session is still an empty composer. 2. In the target session's sidebar controls, copy its **Session ID**. 3. Return to the overseer and enter that ID under **Oversee a session**, or choose **Paste from Clipboard**. 4. Inspect the target preview. Choose **Retry** if the session has just loaded and availability needs refreshing. 5. Choose **Oversee session**, read the confirmation naming both conversations, and choose **Allow oversight** only for the intended relationship. Oversight popover with Session ID, Paste from Clipboard, Retry, and Oversee session The sidebar also offers **Oversee** and **Link overseer** entry points. **Oversee** chooses which session the current row will oversee; **Link overseer** chooses who will oversee that row. Session-ID sheets support selecting a session that is not convenient to find in the visible list. ### Understand the confirmation The confirmation explains that the overseer can read the target's status and conversation, send instructions, steer or stop its run, answer questions and eligible one-time approval requests, compact context, and receive updates. This is active coordination, so link conversations whose work you intend the overseer to direct. **Don't ask again** suppresses repeated confirmation dialogs after an accepted choice. It does not expand the relationship to every session or bypass runtime eligibility. Session-wide approvals, hook trust, merge reviews, and secret inputs remain your responsibility. Not every session is eligible. An unavailable candidate can be loading, closing, controlled by another agent, or otherwise unsuitable for the requested role. Follow the displayed reason. **Sessions changed. Please choose again.** means the selection is stale; choose the target again rather than assuming the old preview is still valid. ### Read relationship marks The sidebar uses a filled eye for an overseer, an outline eye for an overseen session, and a combined mark when a session has both roles. Tooltips name the relationships: **Overseeing**, **Overseen by**, and, for lanes, **Created by**. The popover also lists outbound and inbound relationships so you can inspect who controls whom. Saved relationship information can be restored when the relevant sessions are available, but the live dashboard determines what can currently be used. Check **Unavailable** rows, saving warnings, and recovery notices after reopening workspaces or restarting the app. ### Unlink and recover Use **Unlink** from either end to revoke the relationship. Unlinking does not delete the conversation, roll back file changes, or automatically cancel a turn already in progress. Inspect any running task separately if it should stop. The popover can offer a short-lived **Undo** for the most recent unlink. Read its result: the original relationship must still be eligible. Closing the popover or another unlink can end that recovery opportunity. Turning off routine Auto-wake does not revoke access or block every explicit attention request. Unlink when the purpose of the relationship has ended. See [Best Practices](https://repoprompt.com/docs/1.6.0/overseer/best-practices/) for wake behavior and coordination limits. --- ## Overseer Mode (Overseer) Overseer Mode lets one Agent session coordinate other sessions. The overseer can follow their progress, read their conversations, give follow-up instructions, and help resolve questions within the authority you granted. You can keep working from one coordinating conversation while specialist sessions handle separate parts of a larger task. ### Why use this if you are new to RepoPrompt? An ordinary RepoPrompt session works with a coding agent on a task. When a project grows beyond one focused conversation, you may want an investigation in one session, implementation in another, and an independent review in a third. Without coordination, you have to carry status and instructions between them yourself. An overseer provides a coordinating conversation for that work. You describe the goal and boundaries, let it assign or follow separate tasks, then review its conclusions. You can still open every session and inspect its messages and tool activity. Start with one or two clearly separated tasks; you do not need a large group of agents to benefit. If you are learning the composer first, see [Sessions & Interface](https://repoprompt.com/docs/1.6.0/sessions/overview/). In particular, choose [execution locations](https://repoprompt.com/docs/1.6.0/sessions/execution-location/) deliberately: separate conversations can still share the same checkout. ### Open the oversight control The composer toolbar includes an oversight control between **Workflow** and **Interview**. Open it to enable Overseer mode, add an existing session, inspect relationships in both directions, and manage wake behavior. The captured control uses a branching symbol; newer interfaces identify oversight roles with eye marks and counts. Oversight popover with session-scoped activation and controls for adding an existing session by ID Use a loaded, user-owned top-level Agent session. If the composer has never sent a message, send an initial coordinating request first. For example: “Help coordinate an implementation and independent review. First establish the tasks and checkouts with me.” An unavailable control explains whether the session is still loading or is ineligible. ### Choose how to begin **Create managed lanes.** Choose **Enable overseer mode**, then ask the coordinating agent to create named lanes for defined tasks. A lane is a separate top-level Agent session created for this overseer and linked to it. Activation alone grants no access to your existing conversations. See [Lanes](https://repoprompt.com/docs/1.6.0/overseer/lanes/). **Link existing sessions.** Choose a session through the sidebar oversight menus or paste its session ID into **Oversee a session**. Review the confirmation naming the overseer and target. This is useful when several conversations already contain work you want coordinated. See [Linking Sessions](https://repoprompt.com/docs/1.6.0/overseer/linking-sessions/). The explicit **Enable overseer mode** activation lasts for that session until its binding or ownership changes or the app restarts. Linking and saved relationship recovery have their own lifecycle; check the current popover rather than assuming an earlier activation grants access after a restart. ### What the overseer can do For a properly linked target, the confirmation describes access to status and conversation, instructions, steering, stopping the current run, applicable questions and one-time approvals, context compaction, and updates that can wake the overseer. Session-wide approvals, hook trust, merge reviews, and secret inputs stay with you. An overseer can coordinate work across RepoPrompt windows, but it does not combine every session into a single conversation or automatically merge their file changes. Review results and integration decisions in the target checkout. ### Keep coordination visible The dashboard distinguishes **Idle**, **Running**, **Waiting for input**, and **Unavailable**. Open a session to inspect its actual result; an idle state alone does not prove its goal is complete. Pending updates and **New** indicators help you spot changes since the overseer last handled them. Automatic wake controls can start additional model turns, consume usage, and produce further updates. Configure them around the task's needs, and use **Unlink** to end a relationship when coordination is finished. [Best Practices](https://repoprompt.com/docs/1.6.0/overseer/best-practices/) explains work boundaries, wake settings, result review, and recovery. --- ## Getting Started (Overview) Welcome to RepoPrompt Community Edition! If you have never used RepoPrompt before, think of it as a **context coordinator and mission control** for AI coding agents. When you give a large feature request to a single coding agent in a terminal, it often spends half its working memory searching for files, reading irrelevant code, and losing track of requirements. RepoPrompt prevents this by breaking engineering work into a clear pipeline: **discover the right files → write an architectural plan → delegate scoped tasks to specialized sub-agents → verify the results**. After [installing RepoPrompt CE](https://repoprompt.com/docs/1.6.0/overview/installation/) and opening a project folder (**File → Open**), follow this starting workflow to take a task from an initial prompt to verified code delivery. --- ### Starting Workflow #### Before Step 1: Connect the coding runtime and Oracle Use [Providers & Models](https://repoprompt.com/docs/1.6.0/providers/overview/) to connect and authenticate the coding runtime you intend to use. Optionally configure the Context Builder discovery choice and Oracle analysis model in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/), using a connected provider for each. The [Setup Wizard](https://repoprompt.com/docs/1.6.0/mcp-server/setup-wizard/) can help with those choices. #### Step 1: Describe the Task in a Prompt Every workflow begins with a prompt describing _what_ you want to build or fix and _how_ to verify it. Because RepoPrompt has a dedicated discovery phase, you do not need to manually hunt down and attach every file in your repository before you start. 1. **Confirm your workspace is open:** In RepoPrompt (or via MCP using `bind_context` / `get_file_tree`), make sure your project folder is loaded as the active workspace. 2. **Choose the execution location:** In Agent Mode, open **Work locally** and select the workspace checkout, a new worktree, or an existing worktree. Choose before sending so the task starts in the intended checkout. See [Execution Location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/). 3. **Choose an entry workflow:** - **Inside RepoPrompt (Agent Mode):** Select a **What are we building?** workflow card or use the **Workflow** selector above the editor. **Orchestrate** coordinates multi-step work; **Plan & Build** structures research, planning, and implementation. Your message is wrapped in the selected template. See [Workflow Templates](https://repoprompt.com/docs/1.6.0/sessions/workflow-templates/). - **From an external terminal/IDE agent (via MCP):** Run `/rp-orchestrate ` or `/rp-build ` after installing RepoPrompt's [Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/). 4. **Contextualize the request:** If your prompt uses high-level product terms (like _"improve login validation"_), the orchestrator first runs a quick scan or dispatches a read-only `explore` scout to translate your request into actual codebase nouns (exact module names, types, and file paths). #### Step 2: Curate Relevant Code with Context Builder Steps 2 and 3 are stages of **one** `context_builder` request with `response_type: "plan"` and `export_response: true`. The request first launches a discovery coding agent to explore the repository and assemble a focused file selection toward the configured context budget, then runs the Oracle planning follow-up. Do not run discovery once here and repeat it for Step 3. Other workflows and routine turns can use direct repository tools without running Context Builder: 1. **Navigate the repository:** The discovery agent inspects the project directory tree (`get_file_tree`) and runs regex or path searches (`file_search`) to locate candidate files. 2. **Map APIs with Code Maps:** It calls `get_code_structure` to read **Code Maps** — compact summaries of classes, structs, function signatures, and dependency relationships (`uses` and `used_by`) — without loading thousands of lines of implementation bodies. 3. **Build the selection (`manage_selection`):** It curates the active selection using three representation modes: - **Full files (`full`):** For core files that will be directly modified. - **Line slices (`slices`):** For specific line ranges in large files where only one function or handler matters. - **Code Maps (`codemap_only`):** For surrounding dependencies (automatically added for related files) so the planner knows exact API signatures at a fraction of the token cost. #### Step 3: Draft the Execution Plan with the Oracle In the same request started in Step 2, Context Builder hands the curated context to the **Oracle** for the planning follow-up. No second `context_builder` call is needed: 1. **Deep architectural reasoning:** Because the discovery agent filtered out all search clutter, the Oracle starts with a clean context window containing only the file tree, relevant full files, line slices, and Code Maps. 2. **Export a shared source of truth:** The Oracle drafts a step-by-step execution plan and writes it to a shared Markdown file (such as `Plan.md`, a file under `docs/plans/`, or an exported artifact path returned in `oracle_export_path`). 3. **Establish shared alignment:** This exported plan file acts as the **shared source of truth** across the entire workflow. Instead of pasting a massive prompt into every sub-agent, each worker reads `Plan.md` via `read_file` to understand the architecture and its specific assignment. #### Step 4: Decompose the Plan into Scoped Tasks Next, the **Orchestrator** reviews `Plan.md` and breaks the work into discrete, ordered work items (typically up to 5 work items per pass). To keep sub-agents from stepping on each other, each work item explicitly defines: - **Scoped file boundaries:** The exact files the sub-agent is permitted to modify and the reference files it should inspect. - **Role assignment:** Which sub-agent role fits the task: - `pair` (the default role when `model_id` is omitted) for complex, multi-file implementation - `engineer` for clear, well-bounded coding tasks - `design` for UI, layout, or Markdown specification reviews - `explore` for fast, read-only codebase reconnaissance - **Acceptance criteria ("Done when"):** Concrete build or test commands that prove the work item is finished. #### Step 5: Execute Sequential and Parallel Work Branches With the work items defined and anchored to `Plan.md`, the orchestrator executes them using two patterns depending on whether tasks depend on each other: ##### Sequential Branch: Steer Through Dependent Tasks When tasks must happen in a strict order because each step builds on the previous one — for example: 1. **Implement the auth service** 2. **Add API validation** 3. **Wire up middleware** The orchestrator uses a single deep reasoning session and **steers** it from one task to the next: 1. It launches a sub-agent (`agent_run op="start"`) for Task 1 and waits for completion (`agent_run op="wait"`). 2. After verifying Task 1's edits, the orchestrator calls `agent_run op="steer"` on the _same_ `session_id` to inject Task 2, and then Task 3. 3. **Why steer?** Steering keeps the agent's context warm when the next task is tightly coupled to the code it just wrote, while the orchestrator checks progress between every step. ##### Parallel Branch: Dispatch Across Providers with Multi-Wait When tasks are independent and touch separate file boundaries — for example: - **Codex CLI** sub-agent: _Implement backend logic_ - **OpenCode CLI** sub-agent: _Explore codebase_ (read-only reconnaissance via `agent_explore` or `model_id="explore"`) - **Google Antigravity** sub-agent: _Update configuration files_ The orchestrator runs them concurrently across your connected CLI providers: 1. It starts each sub-agent in detached mode (`agent_run op="start" detach=true`), collecting their `session_id` values into an array. 2. It monitors all active workers at once using **multi-wait**: ```json { "op": "wait", "session_ids": ["", "", ""] } ``` 3. **How multi-wait works:** A multi-session `wait` blocks until the **first** sub-agent finishes its turn or pauses to ask a question (`status: "waiting_for_input"`), returning `winner_session_id` and `pending_session_ids`. The orchestrator immediately handles that agent's result or answers its question (`agent_run op="respond"`), then resumes waiting on the remaining sessions. #### Step 6: Verify Adherence to the Plan As sequential and parallel branches complete their work, they converge back at the orchestrator for verification before the task is marked done: 1. **Inspect actual changes:** The orchestrator runs `git op="status"` and `git op="diff"` (and reads modified sections with `read_file`) to confirm every sub-agent stayed within its assigned file boundaries and followed `Plan.md`. 2. **Run the appropriate checks:** Ask it to verify the combined changes using the project's permitted test and build commands. A completed coding-agent turn does not itself prove that those checks passed. 3. **Update the shared plan and continue:** As each work item passes verification, the orchestrator marks it complete in `Plan.md` using `apply_edits`. If any check fails or a gap is found, it dispatches or steers a targeted fix, repeating the cycle until the entire plan is verified and complete. --- ### Where to Go Next - **Understand the pipeline in depth:** Read [How It Works](https://repoprompt.com/docs/1.6.0/overview/how-it-works/) for a friendly guide to why Context Builder's Explore → Curate → Handoff pipeline outperforms standard agent loops. - **Connect your providers:** Choose the account and runtime described in the [Providers & Models directory](https://repoprompt.com/docs/1.6.0/providers/overview/), then follow its connection guide. - **Try built-in workflows:** Explore all 8 workflows in [Agent Workflow Commands](https://repoprompt.com/docs/1.6.0/agent-mode/workflows/). - **Integrate isolated work:** Follow [Review and Merge](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/) when results live in separate worktrees. --- ## How It (Really) Works (Overview) In [How It Works](https://repoprompt.com/docs/1.6.0/overview/how-it-works/), we introduced the three-stage **Explore → Curate → Handoff** pipeline, and in [Why RepoPrompt](https://repoprompt.com/docs/1.6.0/why-repoprompt/), we outlined the top failure modes of standard coding agents. This page goes under the hood of the RepoPrompt Community Edition source code to explain *why* standard AI coding workflows break down on real production repositories — and the exact mechanisms RepoPrompt implements to solve those failure modes. Here's our "Secret Sauce" with a deep, deep dive into why senior software engineers are using RepoPrompt. --- ### 1. Reliable, Useful Results ("Context Over Convenience") Modern coding agents optimize for _convenience_: you type a one-line prompt, and the agent immediately starts running shell commands and editing files. On small scripts, this feels magical. On real codebases, raw convenience is the primary cause of hallucinated APIs, architectural drift, and broken edge cases. #### The "Agent Orientation" Problem & Effective Context Windows Frontier models advertise massive context windows (200,000 to 1,000,000+ tokens), but empirical research and production benchmarks show a sharp gap between an **advertised context window** and an **effective context window**: - **The 64k–128k Sweet Spot:** As of fall of 2026, most frontier models reason quite reliably inside the **64,000 to 128,000 token** range for agentic coding. Beyond that threshold, reasoning quality degrades proportionally to context length — a phenomenon known as **context rot**. Providers train LLMs with exceptionally long context windows that helps various applications, but coding is not one of them. - **Attention Dilution & "Lost in the Middle":** Transformer attention follows a U-shaped curve. Models attend strongly to tokens at the very beginning and very end of the prompt, while accuracy drops significantly (often by 30% or more) for constraints and code buried in the middle. - **Burning the Budget on Orientation:** When an unguided agent starts a task, its context window is already loaded with harness system prompts, tool JSON schemas, and project rules (`AGENTS.md` / `CLAUDE.md`). It then spends 20 to 40 turns running `grep` and reading unrelated files just to orient itself. By the time the agent finishes **orientation**, its context window is already past the effective reasoning sweet spot — forcing it to design and implement the solution with degraded intelligence. #### How RepoPrompt Solves It in Code RepoPrompt enforces a **Context Over Convenience** architecture: 1. **Strict Token Budgeting (`ContextBuilderSettingsValues.swift`):** Context Builder enforces configurable token targets (`analysisTokenBudget = 120,000` tokens by default when generating a plan, review, or answer; `contextTokenBudget = 160,000` tokens for context-only packaging, adjustable across `40,000...200,000` tokens) and automatically reserves `1,500` tokens for wrapper metadata (`adjustedBudget = max(0, runBehavior.tokenBudget - 1500)`). Most complex problems in large repositories fit cleanly inside ~120k tokens when properly curated. 2. **Non-Opinionated Discovery (`SystemPromptService.discoverPrompt`):** If a discovery agent forms an opinion about _how_ to solve the bug while searching, it will only select files that support its first guess. RepoPrompt's discovery system prompt explicitly instructs the discovery agent to remain factual and non-opinionated: > _"Don't assume a solution: Select context that enables different approaches, not just your imagined solution."_ 3. **100% Reasoning on the First Turn:** By delegating orientation to the Discovery Agent and handing only the curated result to the Oracle or implementation agent, the reasoning model spends 100% of its effective attention budget solving the problem rather than hunting for files. --- ### 2. Advanced Context Engineering Basic prompt engineering asks _"How should I phrase my instructions?"_ **Advanced Context Engineering** asks _"What exact structural representation of the repository should occupy the model's working memory on this turn?"_ In RepoPrompt's codebase (`PromptAssemblyBuilder.swift` and `PromptPackagingService.swift`), context is assembled as a deterministic, multi-layered artifact rather than an append-only chat log: #### Multi-Resolution Code Representation Through `PromptPackagingService.generatePartitionedFileBlocks`, RepoPrompt partitions selected workspace files into two structural zones — `` and `` — using three levels of granularity: | Representation | How RepoPrompt Renders It | Token Engineering Purpose | | :------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | | **Directory Tree + Code Maps** (``) | `combinedFileMapContent` merges the ASCII file tree (`+` marks files with Code Maps) with Tree-sitter structural extractions (`CodeMapService`) showing types, method signatures, and `uses`/`used_by` relationships. | Gives the model a bird's-eye architectural map of the subsystem at roughly 5–10% of the token cost of full source files. | | **Auto-Codemap Dependency Graph** (`WorkspaceCodemapSelectionGraph`) | When you or an agent select files in `full` or `slices` mode, `WorkspaceCodemapBindingEngine` automatically attaches Code Maps for referenced dependency files. | Prevents hallucinated function calls or parameter mismatches on neighboring modules without manual selection. | | **Line Slices & Full Files** (``) | `SliceAssemblyBuilder` and `renderSliceFileBlock` extract specific line ranges (with `Lines start-end (description)` headers and `...` separators), while core edit targets are included in full. | Eliminates hundreds of lines of irrelevant boilerplate from large files while preserving exact line numbers for `apply_edits`. | #### Instruction Sandwiching (`PromptAssemblyBuilder.swift`) To counter the U-shaped **"Lost in the Middle"** attention curve across 60k–160k token prompts, `PromptAssemblyBuilder` orders sections deterministically: 1. **File Tree & Code Maps** (`.fileMap`) 2. **File Contents & Slices** (`.fileContents`) 3. **Git Diffs** (`.gitDiff`) 4. **Meta Prompts** (`.metaPrompts`) 5. **User Instructions** (`.userInstructions`) When **Duplicate User Instructions at Top** (`prompt_packaging.duplicate_user_instructions_at_top`) is enabled, `PromptAssemblyBuilder.build()` emits `` at the **very beginning** of the assembled payload _and_ again at the **very end**. Even when 100,000 tokens of source code sit in the middle, both peaks of the transformer's attention curve remain anchored to your exact requirements. #### Structured Prompt Enhancement & Load-Bearing Clarification Before handoff, Context Builder can transform rough prompts via `PromptEnhancementMode` (`SystemPromptService.promptSection`): - **`Rewrite` (`.fullRewrite`, default):** Replaces vague instructions with a structured specification containing ``, ``, ``, ``, and ``, plus a `` tag used to automatically title the Compose tab. - **`Augment` (`.augment`):** Preserves your original wording verbatim and appends a `` block mapping selected files, relationships, patterns, and open ambiguities. - **`Preserve` (`.preserve`):** Modifies only the file selection and leaves the prompt text untouched. Similarly, in the Agent Mode composer, the built-in **Re-prompter** (`AgentRepromptGuidance.swift` and `AgentRepromptStreamParser.swift`) structures rough notes into `Objective`, `Requirements & Constraints`, `Relevant Context`, and `Validation / Done Criteria` without inventing unverified repository facts — and if a critical product decision is missing, it surfaces **at most one load-bearing question** (`<<>>`) before execution begins. --- ### 3. Model Context vs. Tool Context A critical distinction in modern agent engineering is the separation between **Model Context** and **Tool Context**: - **Model Context** is the curated working memory of the problem: system instructions, architectural plans, relevant source files, type signatures, and diffs. - **Tool Context** is the operational residue of tool use: MCP JSON schemas injected into the system prompt (**schema bloat**) and the raw stdout/stderr logs, search hits, and file dumps returned by dozens of tool calls (**response bloat**). When Tool Context and Model Context share the same buffer, every failed search and 500-line file inspection permanently pollutes the model's reasoning space and invalidates prompt caches. #### How RepoPrompt Separates Them 1. **Selection Is the Single Source of Truth for the Oracle:** When an agent consults the Oracle (`ask_oracle` or `oracle_send`), the Oracle **never** receives the coding agent's messy tool-call transcript. It receives _only_ the curated workspace selection (`manage_selection`) and the Oracle conversation history. 2. **Fast-Lane Auto-Selection (`MCPReadFileAutoSelectionCoordinator.swift`):** In Agent Mode, whenever the coding agent calls `read_file` or `file_search`, `MCPReadFileAutoSelectionCoordinator` records a lightweight selection intent (`.full` or `.slices`) on a non-blocking fast lane. The moment an explicit consumer (`ask_oracle`, `workspace_context`, or `manage_selection`) runs, RepoPrompt drains the high-water mark (`drainThroughGeneration`) so the Oracle's Model Context automatically includes every file and slice the agent inspected — without carrying over the agent's intermediate search commands. 3. **Suppressing Redundant Native CLI Tools (`ClaudeCompatibleToolPolicy` & `CLIPathInstaller.swift`):** - The `claude-rpce` wrapper (`CLIPathInstaller.swift`) launches Claude Code with `--strict-mcp-config` and `--disallowedTools Read,Write,Edit,Glob,Grep`, forcing all file navigation and editing through RepoPrompt's token-efficient MCP tools. - Inside integrated Agent Mode (`ClaudeCodeIntegrationConfiguration.swift`), RepoPrompt disallows native `Write`, `Edit`, `Glob`, `Grep`, `Agent`, `Task`, `EnterWorktree`, and related native tools. Native `Read` is retained in Agent Mode **strictly for non-text binary assets** (images, screenshots, PDFs), while all text and source code reads are routed through `RepoPrompt__read_file`. - During Context Builder discovery (`discoverDisallowedTools`), `Bash` and native `Read` are also disallowed so the discovery agent stays strictly inside read-only RepoPrompt MCP primitives. 4. **Preloaded Tools vs. Lazy Tool Loading (`ClaudeAgentToolPreferences.swift`):** By default, RepoPrompt preloads its compact 21-tool catalog (`claudeCodeToolSearchEnabled = false`, setting `ENABLE_TOOL_SEARCH="false"`) so agents do not burn extra turns discovering tools; users who connect many third-party MCP servers can toggle **Lazy Tool Loading** on in Settings to defer schema loading. 5. **Configurable System Prompt Delivery (`ClaudeCodePromptDelivery.swift`):** Because different models and tasks respond differently to system-level vs. user-level framing, Claude Code CLI settings expose **Sys Prompt Packaging** (`Replace System Prompt`, `User Message (Keep Native)` wrapped in ``, or `User Message (No Native)`). --- ### 4. Agents Operating Over Multiple Turns and Longer Time Horizons Single-session coding agents degrade over long time horizons (30+ turns) because errors compound: a slight misunderstanding in turn 5 becomes a broken interface in turn 20 and a failing test suite in turn 35. RepoPrompt enables multi-hour, long-horizon engineering through **delegation-first orchestration** and a **cross-session oversight control plane**. #### Coordinator vs. Worker Separation (`/rp-orchestrate`) In `WorkflowPrompt+Orchestrate.swift` and `docs/architecture/agent-orchestration-guidance.md`, the orchestrator is strictly a **Coordinator**: - **Right-Sized Sub-Agent Work Items:** Anything spanning more than ~30 lines or touching more than 2 files is delegated to a fresh sub-agent (`agent_run op="start"`). The ideal sub-agent task touches **1–4 files**, addresses **one coherent concern**, and has explicit acceptance criteria. - **Fresh Context Per Work Item:** Each worker sub-agent starts with a clean context window, reads the exported architectural plan (`Plan.md`), completes its scoped files, and returns a concise summary. When the worker finishes, its 30 turns of implementation tool calls are discarded rather than polluting the orchestrator. - **The Phase Gate Invariant:** Parallel sub-agents are instructed **not** to run full-repository builds or test suites concurrently (which causes build-lock contention and noisy failures). Instead, workers complete their scoped edits, and the orchestrator runs the build and test gate **once at the phase boundary**. - **Anti-Interference Rule:** While a delegated sub-agent is running, the orchestrator is forbidden from calling `steer` to hurry it or editing overlapping files in the same scope. #### Capability-Scoped Control Plane (`AgentModeMCPToolPolicy.swift`) To prevent runaway recursive agent spawning, `AgentModeMCPToolPolicy` enforces strict hierarchy boundaries: - Top-level sessions can spawn sub-agents (`agent_run`) and read-only reconnaissance scouts (`agent_explore`) and monitor them in parallel with `session_ids` **multi-wait**. - Nested sub-agents have `agent_run`, `agent_manage`, `agent_session_link`, `session_admin`, and `become_overseer` withheld by default. - For cross-window and multi-session administration, a session can request promotion via `become_overseer` or a user-approved **Delegation Scope** (`DomainDelegationScopeAuthority` / `session_admin`), where every authority check verifies live consent, generation counters, and provenance-based membership proofs (`DelegationMembershipProjector`) before allowing an overseer to inspect, steer, bind worktrees, or retire sibling sessions. #### Event-Driven Auto-Wake & Snooze (`AgentModeViewModel+OversightAutoWake.swift`) When an overseer monitors long-running target sessions via `agent_session_link`, it does not need to burn tokens polling in a loop. RepoPrompt implements an event-driven **Auto-Wake** subsystem divided across four disjoint state owners: 1. **Link Authority (`DomainAgentSessionLinkAuthority`):** Manages user-granted directional links, leases, and cursors. 2. **Passive Reducer (`AgentSessionLinkPassiveStatusNotices`):** Coalesces target status transitions and non-lossy attention requests. 3. **Claim / Receipt Context (`AgentSessionLinkPromptContext`):** Freezes the exact `` XML batch delivered to the provider. 4. **Wake Coordinator (`AgentModeViewModel+SessionLinkAutoWake`):** Determines whether an idle overseer tab may start an automatic follow-up turn right now. Two subtle concurrency invariants in the source code keep long-horizon oversight reliable: - **Snooze Suppresses Admission, Never Delivery:** While an overseer is actively blocked inside an `agent_session_link(op="wait")` call, RepoPrompt records a snooze for those `(overseer, target)` pairs so the wait return itself delivers the update without triggering a duplicate auto-wake turn. However, any notice _already admitted_ to the queue is never filtered out at drain time — ensuring no child completion or question is ever silently stranded. - **The `.cancelledBeforeDispatch` Tombstone Fence:** If you send a manual chat message to the overseer while an asynchronous auto-wake `Task` is already scheduled, your message synchronously drains the queued oversight updates and attaches them inline. RepoPrompt writes a `.cancelledBeforeDispatch(generation)` tombstone into `pendingDispatchByOverseer` so the already-scheduled background task wakes up, sees the tombstone, and exits cleanly without firing a duplicate turn. --- ### 5. Compaction (and Preventing "Compaction Amnesia") As a multi-turn session approaches its context limit, coding agents use **compaction** — summarizing the conversation history so the session can continue. #### Why Naive Compaction Fails In standard coding agents, compaction triggers automatically when a token buffer hits an arbitrary threshold (often right in the middle of debugging a failing test). Standard summarizers suffer from two well-documented failure modes: 1. **Loss of Side Constraints:** Summarizers focus on _what was done_ and frequently drop negative constraints given earlier (such as _"do not modify the public auth signature"_ or _"keep backwards compatibility with v1"_), causing post-compaction agents to immediately violate project rules. 2. **Loss of File & Architectural Detail:** Compaction strips raw file contents and earlier Oracle design discussions from the transcript, forcing the agent to re-read files or guess at architectural decisions it made 40 turns ago. #### RepoPrompt's Four-Part Compaction Architecture RepoPrompt replaces blind threshold truncation with four coordinated mechanisms implemented under `Sources/RepoPrompt/Features/AgentMode/Runtime/SelfCompact/` and `MCPOracleToolService.swift`: ##### 1. Agent-Initiated Self-Compaction (`self_compact` / `agent_self`) Instead of compacting mid-thought, an Agent Mode session can call `self_compact`: - `op="context"` inspects its own current context load and compaction state. - `op="compact"` schedules native compaction at a clean task boundary and records a structured continuation `note` (capped at **10% of the session's context window** in tokens × 4 UTF-8 bytes/token, or **65,536 bytes**, with a SHA digest integrity check). - Calling `op="compact"` returns `scheduled` immediately (`AgentSelfCompactInstantReturn.swift`) and instructs the agent to finish its current turn cleanly. Compaction runs **only** after the active turn settles with `.completed` (never after `.failed`), supervised by a **300-second monotonic deadline** (`AgentSelfCompactNativeCompletionCoordinator.swift`). ##### 2. Dedicated Continuation-Note Turn (`AgentSelfCompactNoteEnvelope.swift`) Once the underlying provider finishes its native compaction (`/compact` in Claude Code or `thread/compact/start` in Codex), RepoPrompt does not inject the saved note as a system log (which many providers ignore) or a normal user prompt (which the model would misinterpret as a new command from you). Instead, `AgentSelfCompactNoteEnvelope` dispatches a dedicated continuation turn that bypasses workflow wrappers and prompt augmentation: ```xml This is your own continuation note, recorded before this session was compacted. It is not a new instruction from the user. {agent's saved architectural state, side constraints, and next steps} ``` If the session closes before the note turn can be delivered, `AgentSelfCompactParkedPrefix.reparkUnattemptedDedicatedNote` re-parks and persists the note so it is never lost. ##### 3. Post-Compaction Oracle Recovery (`oracle_chat_log`) Because the Oracle conversation lives in RepoPrompt's workspace state outside the coding agent's compacted transcript, `SystemPromptService.agentModePrompt` equips the agent with `oracle_chat_log` (reading 1–50 recent Oracle messages without sending a new turn): > _"After compaction: Call `oracle_chat_log` with `limit:1` to read the Oracle's most recent message, then continue with `ask_oracle` (`new_chat:false`) to pick up where you left off."_ ##### 4. Session Handoff Extraction (`agent_manage op="extract_handoff"`) When a session has completed a major phase and you want to start fresh in a new tab or provider without carrying _any_ compacted residue, `extract_handoff` (`AgentHandoffOutputFile.swift` and `AgentProviderContextBuilder.swift`) exports a structured `` XML package containing curated instructions (up to 20,000 characters), bounded transcript items, and the active file selection (or a token-capped ``). --- ### 6. Variations and Limitations of Large Language Models (LLMs) The workflow separates repository exploration and editing from Oracle consultation. A model suited to iterative tool use may serve a different purpose from one selected to reason over a prepared context package. Compare the capabilities needed by each stage rather than assigning permanent rankings to named model releases. Use the shared [Models reference](https://repoprompt.com/docs/1.6.0/providers/models/) for availability, identifiers, reasoning effort, speed tiers, and choosing models for different tasks. The [provider directory](https://repoprompt.com/docs/1.6.0/providers/overview/) owns connection requirements and official catalog references. #### Role-Based Model Specialization Role labels resolve through the effective Agent Models profile rather than a fixed list of model releases. See [Model roles](https://repoprompt.com/docs/1.6.0/providers/models/#model-roles) for their responsibilities and [Agent Models settings](https://repoprompt.com/docs/1.6.0/settings/agent-models/#sub-agent-role-defaults) for configuring mappings and workspace overrides. Model choice and permission policy remain separate decisions. #### Multi-Oracle Rosters & Reconciliation (`SystemPromptService.multiOracleGuidanceBlock`) Even the strongest single reasoning model has blind spots. In **Settings → Agent Mode → Agent Models**, you can configure **1 Primary Oracle** plus up to **4 Additional Oracles** (`OracleGroupStore`). When an agent calls `ask_oracle` or `oracle_send`, RepoPrompt queries every model in the roster in parallel and returns the primary answer alongside ``. RepoPrompt injects explicit reconciliation rules (`multiOracleGuidanceBlock`) into the calling agent: - Where perspectives **agree**, proceed with higher confidence. - Where perspectives **diverge**, evaluate the trade-offs against the actual codebase rather than blindly following either model. - If a secondary Oracle surfaces a **risk or edge case** the primary model missed, investigate it in the code before proceeding. #### Adaptive Routing, Auto Effort, & Local Usage Balancing Through [Model Router](https://repoprompt.com/docs/1.6.0/settings/model-router/), RepoPrompt can dynamically select the base model and reasoning effort per task (using a decision service such as TypeSafe Jev with a strict 5-second non-retried deadline), while **Usage Balancing** stays 100% local on your Mac to shift eligible new tasks across your connected Claude and Codex subscriptions (`Only near limits`, `Even pace`, or `Use expiring quota first`) so you don't burn through one provider's weekly quota prematurely. --- ### 7. Code Reviews: Diff-Only vs. Codebase-Context Reviews Most AI pull-request reviewers operate in **Diff-Only Mode**: they send your `git diff` patch to an LLM and ask _"Find bugs in this diff."_ #### Why Diff-Only Reviews Fail A raw diff shows _what lines changed_, but hides _how the rest of the repository interacts with those lines_: - **False Negatives (Missed Breakage):** If a commit changes a function's return behavior or deletes a fallback branch, a diff-only reviewer cannot see the five callers in other modules that depended on the old contract. - **False Positives (Hallucinated Bugs):** Diff-only reviewers frequently complain about "missing null checks" or "unvalidated inputs" that are already guaranteed by an upstream caller one hop outside the diff. #### How RepoPrompt Implements Codebase-Context Reviews RepoPrompt's review pipeline (`WorkflowPrompt+Review.swift`, `SystemPromptService.reviewPrompt`, and `GitDiffPrimaryArtifacts.swift`) grounds every code review in the surrounding architecture: 1. **Worktree-Aware Git Inspection (`git` tool):** Supports `status`, `diff`, `log`, `show`, and `blame` across uncommitted changes, staged changes, commit ranges (`back:N`), and merge-base branch comparisons (`main`, `trunk`, `@main:`) with native Git worktree and Jujutsu (`jj`) support. 2. **Materialized Selectable Diff Artifacts (`GitDiffPrimaryArtifacts.swift`):** When `git(op="diff", artifacts=true)` runs (automatically triggered by `context_builder(response_type="review")`), `GitDiffSnapshotStore` writes structured diff artifacts into `_git_data//`: - `MAP.txt` — A summary map of all modified files and line-change counts. - `all.patch` — The combined patch artifact. - `diff/per-file/NNN-.patch` — Individual per-file patches exposed as selectable workspace paths. 3. **Outside-Diff Impact Curation (`reviewDiscoveryGuidanceBlock`):** The discovery agent selects the relevant `.patch` artifacts via `manage_selection` **alongside** the full files, line slices, and Code Maps of the modified files, their upstream callers, downstream callees, and test suites. 4. **Prioritized Contract Evaluation (`SystemPromptService.reviewPrompt`):** The Oracle receives both the exact diff hunks and the surrounding codebase contracts, evaluating **Correctness, Security, API/Contract Breakage, Consistency, and Test Coverage**, and organizing findings into actionable tiers: **Must Fix**, **Should Fix**, **Consider**, and **Positive Notes**. --- ### 8. When RepoPrompt Would Not Be Helpful Engineering tools are defined as much by when _not_ to use them as by when to use them. Because Context Builder discovery, Oracle consultation, and multi-agent orchestration take extra time and tokens to run, RepoPrompt explicitly encodes **Fast Paths** and stop rules directly in its system and workflow prompts (`SystemPromptService.swift`, `WorkflowPrompt+Build.swift`, `WorkflowPrompt+Investigate.swift`, and `WorkflowPrompt+Orchestrate.swift`). Here is when full RepoPrompt workflows or Context Builder pipelines are **not** helpful — and what to do instead: #### 1. Localized, Obvious 1–3 File Edits (Use the Fast Path) If you already know which file needs to change, the edit is confined to **1–3 files**, and there are no architectural unknowns (for example, fixing a typo, adding a straightforward prop to a React component, or updating a single validation regex), running `context_builder` and consulting an Oracle adds unnecessary latency. - **How RepoPrompt handles this:** Both `/rp-build` (`WorkflowPrompt+Build.swift`) and `/rp-investigate` (`WorkflowPrompt+Investigate.swift`) include an explicit **Phase 1 Fast Path** rule: when the target is localized (1–3 files) and unambiguous, the agent is instructed to **skip `context_builder`, `agent_explore`, and Oracle planning**, read the target file directly with `read_file`, and apply the change with `apply_edits`. #### 2. Micro-Tasks Under ~30 Lines (Skip Sub-Agent Orchestration) Spawning a sub-agent (`agent_run op="start"`) requires spinning up a new session, reading the plan file, and reporting back. - **How RepoPrompt handles this:** `WorkflowPrompt+Orchestrate.swift` defines explicit **Sub-Agent Sizing Heuristics**: if a change is **under ~30 lines and touches ≤ 2 files** (such as a single-line fix or a simple symbol rename), the agent should execute it directly or batch it with related work rather than delegating to a sub-agent. #### 3. Routine Turn-by-Turn Agent Exploration (Skip Automatic `context_builder`) If you are already in the middle of an interactive coding session and ask a quick follow-up question about a file you are looking at, launching a full two-stage `context_builder` discovery sub-agent is overkill. - **How RepoPrompt handles this:** Section 3 of `SystemPromptService.agentModePrompt` (`Context Builder — Disabled Unless Explicitly Requested`) explicitly instructs Agent Mode sessions **not** to invoke `context_builder` on routine turns unless you ask for it by name or select a workflow that requires it. Instead, the agent uses lightweight direct calls (`get_file_tree`, `file_search`, `get_code_structure`, `read_file`) that return in milliseconds. #### 4. Standalone Scripts, LeetCode-Style Puzzles, or Zero-Context Tasks RepoPrompt is an architectural context engine for multi-file repositories. If you are writing a self-contained 50-line Python script from scratch, solving an isolated algorithm puzzle, or drafting prose with no codebase dependencies, there are no cross-file contracts, call graphs, or Code Maps to curate — a direct chat with your model is faster and simpler. --- ### Summary Matrix: Problem vs. RepoPrompt Architecture | Failure Mode in Standard Agents | Root Cause | RepoPrompt CE Architectural Solution | | :---------------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Context Rot & Hallucinations** | Agent burns 40+ turns of its 64k–128k effective context window on `grep` and dead-end file reads. | **Non-opinionated Discovery Agent** curates a 120k-token budgeted selection before the reasoning model starts (`ContextBuilderSettingsValues.swift`). | | **"Lost in the Middle" Forgetting** | Transformer attention drops in the middle of long prompts, losing user constraints. | **Instruction Sandwiching** (`PromptAssemblyBuilder.swift`) duplicates `` at the top and bottom of the packaged prompt, paired with Tree-sitter **Code Maps** and **Line Slices**. | | **MCP & Tool Context Bloat** | Verbose tool schemas and raw stdout logs permanently clutter the model's working memory. | **Model vs. Tool Context Separation**: Oracle sees only `manage_selection`; `MCPReadFileAutoSelectionCoordinator` syncs reads asynchronously; `ClaudeCompatibleToolPolicy` blocks redundant native CLI tools. | | **Multi-Turn Drift on Large Tasks** | A single session accumulates conflicting edits and test noise over dozens of turns. | **Coordinator / Worker Split** (`/rp-orchestrate`), **Phase Gate Invariant**, capability-scoped sub-agents (`AgentModeMCPToolPolicy`), and event-driven **Oversight Auto-Wake**. | | **Compaction Amnesia** | Automatic mid-task truncation drops negative side constraints and architectural context. | **Intentional `self_compact`** at turn boundaries, dedicated `` delivery, `oracle_chat_log` recovery, and `` handoffs. | | **Single-Model Blind Spots** | Forcing think-then-act models to edit mid-thought, or relying on one model for every task. | **Tool-less Oracle** paired with tool-native agents, **4 Agent Roles** (`explore`, `engineer`, `pair`, `design`), **Multi-Oracle Rosters** (up to 5 models in parallel), and local **Usage Balancing**. | | **Diff-Only Review Blindness** | Reviewing a git patch in isolation misses broken upstream callers and downstream contracts. | **Selectable Diff Artifacts** (`_git_data/.../MAP.txt`, `all.patch`, per-file patches) combined with curated caller/callee context in `context_builder(response_type="review")`. | | **Over-Engineering Simple Edits** | Running heavy discovery and multi-agent orchestration on a 2-file bug fix wastes time. | Built-in **Fast Path** gates in `/rp-build` and `/rp-investigate` (≤ 3 files), **~30-line threshold** in `/rp-orchestrate`, and disabled-by-default `context_builder` on routine turns. | --- ## How It Works (Overview) If you are a software engineer using RepoPrompt for the first time, the most important concept to understand is **Context Builder Workflows**. Whether you run agents inside RepoPrompt's **Agent Mode** or trigger slash commands (like `/rp-orchestrate` or `/rp-review`) from an external MCP client, Context Builder is the engine that prevents AI coding agents from getting lost in your repository. --- ### Why Standard Coding Agents Get Confused To understand what RepoPrompt does, imagine onboarding to a new engineering team and being assigned a ticket to update user authentication. If a senior teammate helps you, they do not print out all 54 files in the repository and hand you a 10,000-line stack of paper. Instead, they point you to the 5 or 9 files that actually matter — showing you the specific lines in `auth.ts` and `api.ts` where tokens are validated, and giving you a quick summary of the helper functions in `useAuth.ts`, `Header.tsx`, and `Sidebar.tsx`. When you use a standard AI coding agent *without* RepoPrompt, it has no senior teammate: 1. The agent starts with an empty **context window** (its working memory, measured in **tokens**). 2. To orient itself, it runs shell commands like `grep` and `find` and reads whole files one by one. 3. Most of the files it reads turn out to be dead ends, but **every search result and unrelated file stays in its context window**. 4. Even if a model advertises a 200k+ token window, its *effective* reasoning quality drops sharply once its working memory fills past 64k–128k tokens of noisy tool logs. By the time the agent finds the right code, it has very little "thinking budget" left to write a clean solution. RepoPrompt solves this by separating **finding the right code (Discovery)** from **solving the problem (Analysis & Implementation)**. --- ### The Three-Stage Context Builder Pipeline Whenever a Context Builder workflow runs (via the UI or the `context_builder` MCP tool), RepoPrompt executes a three-stage pipeline behind the scenes: **01 Explore → 02 Curate → 03 Handoff**. #### Stage 01: Explore — Agent Navigates the Codebase First, RepoPrompt launches a fast, specialized **Discovery Agent** whose only job is to map the codebase around your task. - **How it navigates:** Rather than using raw shell `grep` or `cat`, the discovery agent uses RepoPrompt's gitignore-aware repository tools: - `get_file_tree` to inspect the directory hierarchy (where files with available Code Maps are marked with `+`). - `file_search` to search file paths, contents, or both using regular expressions and directory filters. - `get_code_structure` to inspect **Code Maps** — root-local structural summaries showing classes, structs, function signatures, and dependency edges (`uses` and `used_by`). - **Neutral fact-gathering:** In RepoPrompt's architecture, the discovery agent is deliberately instructed to be **non-opinionated**. It does not try to design your feature or guess a fix prematurely; it gathers facts, traces callers and callees, and identifies every candidate file across the project. #### Stage 02: Curate — Select Within a Token Budget Suppose your project or subsystem has **54 files**, and the discovery agent's exploration touches 14 of them. Loading every file in full would waste tokens on boilerplate. In Stage 02, the agent narrows and shapes the selection (`manage_selection`) to fit strictly inside RepoPrompt's configured **Token Budget** (for example, curating **9 of 54 files** within the default **120,000-token Analysis Budget** or **160,000-token Context Budget**): - **Full Content (`mode="full"`):** Selected for the primary files where logic needs to be understood line-by-line or edited directly. - **Line Slices (`mode="slices"`):** Selected when a file is large (say, 1,200 lines) but only one function or component matters. The agent selects exact line ranges (such as `auth.ts` lines `5–89` or `api.ts` lines `22–58`) and omits the rest. - **Code Maps Only (`mode="codemap_only"`):** Selected for supporting files and dependencies. In fact, RepoPrompt includes **Auto-Codemap** behavior: when full files or slices are added, related dependency files automatically receive Code Maps so the reasoning model sees their exact API signatures without paying for their implementation bodies. #### Stage 03: Handoff — Structured Prompt for Analysis Once the selection is curated, RepoPrompt assembles a clean, deterministic context package (`workspace_context`). For example, a curated handoff for an authentication task might look like this: | Selected File | Representation / Line Range | Why It Is Included | | :--- | :--- | :--- | | `auth.ts` | `L5–89` (Slice) | Core authentication token logic being modified | | `api.ts` | `L22–58` (Slice) | API request interceptor that consumes auth state | | `useAuth.ts` | `L1–41` (Full / Slice) | React hook exposing session state to components | | `Header.tsx` | `L12–67` (Slice) | UI component rendering the sign-in/sign-out controls | | `Sidebar.tsx` | `L1–34` (Full / Slice) | Navigation gating based on authenticated user role | Depending on the `response_type` requested by the workflow, RepoPrompt also enhances your prompt (rewriting or augmenting vague terms into exact file and symbol names) and performs the handoff: - **`clarify` (Context-Only Handoff):** Returns the curated selection and clarified prompt directly to your agent (or exports a prompt file) so it can begin working immediately. - **`plan`, `review`, or `question` (Oracle Analysis Handoff):** Passes the structured prompt to the **Oracle** — a high-capability reasoning model (or a configured **Multi-Oracle Roster** evaluating up to 5 models in parallel) — which starts with a fresh context window containing zero search noise and returns an architectural plan, code review, or deep answer. Multi-Oracle rosters include automated reconciliation guidance so agents can weigh differing perspectives. --- ### Core Context Builder Workflows RepoPrompt ships included slash commands that wrap this three-stage pipeline into repeatable engineering workflows. You can run these from the **Workflow** dropdown in Agent Mode or type them as slash commands in any connected MCP client: #### 1. Orchestrate (`/rp-orchestrate`) **When to use it:** Large features, multi-file changes, or cross-cutting tasks that are too big for a single agent session. - Runs Context Builder (`response_type: "plan"`, `export_response: true`) to produce a shared architectural plan file. - Decomposes the plan into up to 5 scoped work items with explicit file boundaries. - Dispatches specialized sub-agents (`pair`, `engineer`, `design`, `explore`) across your connected providers in sequence or in parallel, then verifies every change against the plan and test suite. #### 2. Code Reviews (`/rp-review`) **When to use it:** Before opening a pull request, merging a branch, or committing staged changes. - Surveys your repository state using RepoPrompt's read-only `git` tool (`status`, `log`, `diff` against `uncommitted`, `staged`, or a branch merge-base like `main`). - Calls Context Builder (`response_type: "review"`), which publishes your Git diffs **alongside** curated codebase context (callers, interfaces, and related modules outside the diff). - Because the Oracle sees how the rest of the codebase interacts with your diff, it catches subtle breaking changes, missing error handling, and security bugs that diff-only tools cannot see. #### 3. Refactor Code (`/rp-refactor`) **When to use it:** Cleaning up technical debt, splitting a monolithic module, or eliminating duplicated logic without changing how the app behaves. - **Pass 1 (Analyze):** Scouts the target folder with read-only `explore` agents and runs Context Builder in `review` mode to identify structural opportunities and hidden coupling. - **Pass 2 (Plan & Implement):** Runs Context Builder in `plan` mode to design safe, incremental refactoring steps that preserve existing behavior, then dispatches sub-agents to apply edits (`apply_edits`) and run tests after each step. #### 4. Investigate Issues (`/rp-investigate`) **When to use it:** Debugging a tricky crash, tracing a regression, or understanding how an unfamiliar subsystem works. - Follows a hypothesis-driven workflow that writes an investigation report to `docs/investigations/-.md` without changing source code. - Uses `explore` scouts for git blame archaeology and Context Builder to gather cross-file evidence, then consults the Oracle (`oracle_send` / `ask_oracle`) to test hypotheses until the root cause is proven with exact file and line citations. :::tip[Additional Specialized Workflows] RepoPrompt also includes **Deep Plan** (`/rp-deep-plan` for producing standalone specification docs under `docs/plans/` with an interactive interview and `design` critique), **Optimize** (`/rp-optimize` for metric-driven performance loops with a persistent scoreboard), **Plan & Build** (`/rp-build` for single-session feature implementation), and **ChatGPT Export** (`/rp-oracle-export` for exporting self-contained prompts to `prompt-exports/`). ::: --- ### Summary for New Users | Concept | What It Means in RepoPrompt | | :--- | :--- | | **Discovery Agent** | The fast agent in Stage 01 that searches your repo and selects files without writing code. | | **Code Map** | A token-efficient summary of a file's types and function signatures (`get_code_structure`). | | **Line Slice** | A specific range of lines from a file (`manage_selection mode="slices"`), skipping unrelated lines. | | **Oracle** | The deep reasoning model in Stage 03 that receives the curated context to generate plans, reviews, or answers. | | **Sub-Agent Roles** | Task-specific agent profiles: `pair` (default for complex work), `engineer` (scoped coding), `explore` (read-only scouting), and `design` (architecture/UI specs). | ### Next Steps - Read [How It (Really) Works](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/) for an under-the-hood architectural deep dive into compaction, Model Context vs. Tool Context, LLM limitations, and when *not* to use Context Builder. - Follow the step-by-step [Starting Workflow in Getting Started](https://repoprompt.com/docs/1.6.0/overview/getting-started/). - Explore the full [Agent Workflow Commands](https://repoprompt.com/docs/1.6.0/agent-mode/workflows/) and [MCP Workflow Commands](https://repoprompt.com/docs/1.6.0/mcp-server/workflow-commands/) guides. - Learn how to adjust token budgets in [Context Builder Settings](https://repoprompt.com/docs/1.6.0/settings/context-builder/). --- ## Installation (Overview) RepoPrompt 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 RepoPrompt from install through your first orchestrated workflow. Even though this video was done for the Classic Edition, it still applies to the Community Edition: [Watch the Installation video walkthrough](https://youtu.be/G8TLeEdcdAM) ### Manual Download Get the latest version directly from RepoPrompt CE Repository: [Download for macOS](https://github.com/repoprompt/repoprompt-ce/releases) ### Manual Installation 1. Download the most recent `.dmg` file from the link above 2. Open the downloaded file 3. Drag the RepoPrompt CE to your Applications folder 4. Eject the disk image 5. Open RepoPrompt from Applications or Spotlight ### Homebrew Installation You can install the pre-built RepoPrompt CE macOS binaries via Homebrew ```bash brew tap repoprompt/repoprompt-ce brew trust --tap repoprompt/repoprompt-ce brew install --cask repoprompt-ce ``` ### System Requirements - **macOS 14.0 (Sonoma)** or later - Apple Silicon (M1/M2/M3) or Intel Mac - ~50MB disk space ### First Launch 1. Open RepoPrompt from Applications or Spotlight 2. Grant folder access when prompted (required to read your code) 3. Open a workspace: **File → Open** or drag a folder onto the app :::tip **Tip:** Use the CE URL scheme `repoprompt-ce://open//Users/example/Project` to open a project, replacing the example with your folder's absolute path. See [URL Opener](https://repoprompt.com/docs/1.6.0/settings/advanced/#url-opener) for encoded prompts and other parameters. ::: ### Updates When automatic checks are enabled and the updater is configured, RepoPrompt checks for updates in the background. You can also check manually through **Settings → General → Updates**. See [Software Updates](https://repoprompt.com/docs/1.6.0/settings/updates/). ### Platform Availability The documented CE desktop app is macOS-only. Open-source portability work does not itself establish an official release for another platform. See [Does RepoPrompt Run on Windows or Linux?](https://repoprompt.com/docs/1.6.0/faq/windows-linux/). ### Installing Tip Build Tip Builds are official signed and notarized builds from the latest successful protected `main` commit. They offer development changes before the next Stable release. To install one, open RepoPrompt CE and go to **Settings → General → Updates**. Set **Update Channel** to **Tip Builds**, choose **Check for Updates**, and follow the updater's installation prompts when an eligible build is offered. If you have not installed RepoPrompt CE yet, install and launch the current Stable app using the instructions above, then select the Tip Builds channel. The selected channel controls which updates the app offers. To return to Stable, change **Update Channel** back to **Stable**. This may require waiting for a newer Stable release; to return immediately, reinstall the Stable application. See [Software Updates](https://repoprompt.com/docs/1.6.0/settings/updates/) for more about update checks and channel behavior. For the tradeoff between channels, see [What Is the Tip Version and Should I Use It?](https://repoprompt.com/docs/1.6.0/faq/tip-version/). If you want to compile the development source yourself, see [Build Tip code with Xcode](https://repoprompt.com/docs/1.6.0/faq/how-to-build/#build-tip-code-with-xcode). A local Xcode build uses the contributor workflow and is separate from the official signed Tip distribution. --- ## Anthropic API (Providers) Anthropic API provides direct model requests for supported RepoPrompt features such as Oracle and built-in Chat. It is separate from the [Claude Code CLI](https://repoprompt.com/docs/1.6.0/providers/claude-code-cli/) coding-agent integration. ### Connect Use the Anthropic entry in [API Providers settings](https://repoprompt.com/docs/1.6.0/settings/api-providers/#anthropic). Supply an API credential with access to the intended models and validate it. The custom-model field accepts an exact compatible Anthropic identifier; it does not turn an arbitrary label into a supported model. ### Models and availability Use the provider's supported IDs and the choices available through this connection. Model capabilities, context limits, and support status vary. Review [Anthropic's model lifecycle documentation](https://docs.anthropic.com/en/docs/about-claude/model-deprecations) before retaining a saved custom identifier across model retirements. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains shared selection concepts. For RepoPrompt's per-model overrides, see [Model Config](https://repoprompt.com/docs/1.6.0/settings/model-config/); those controls cannot add capabilities absent from the endpoint. ### Account and billing Requests use the Anthropic API account associated with the saved key. A Claude subscription or an authenticated Claude Code runtime does not automatically pay for direct API requests or configure this credential. Check API access and billing on the account that owns the key. --- ## Azure OpenAI (Providers) Azure OpenAI is a direct model connection to your Azure resource. It requires resource-specific configuration and is distinct from the standard [OpenAI API](https://repoprompt.com/docs/1.6.0/providers/openai-api/) connection and [Codex CLI](https://repoprompt.com/docs/1.6.0/providers/codex-cli/) account login. ### Configure the resource In [API Providers → Azure OpenAI](https://repoprompt.com/docs/1.6.0/settings/api-providers/#azure-openai), provide the resource **Base URL**, supported **API Version**, and **API Key**, then validate. Use a version appropriate to that resource and requested functionality; a version shown in a settings screenshot is illustrative. When discovery offers deployments, select the intended deployment or use the supported custom-deployment control. A deployment name belongs to the Azure resource and need not equal a public model ID used by another API. ### Availability and lifecycle Models must be available for your Azure resource, region, and deployment type. Check Microsoft's [model lifecycle and availability guidance](https://learn.microsoft.com/en-us/azure/foundry/openai/concepts/model-retirements) when a deployment changes or stops serving requests. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains deployment identities and the relationship between model capabilities and RepoPrompt controls. Selecting a public model name does not provision an Azure deployment. ### Account and billing Your Azure subscription, resource, deployment, and service terms determine usage and charges. A separate OpenAI API balance or ChatGPT subscription does not automatically pay for calls to this resource. Review billing and quota at the Azure resource used by the connection. --- ## Claude Code Compatible Backend: CC Custom (Providers) CC Custom directs the installed Claude Code runtime to an Anthropic-compatible endpoint you configure. It is distinct from [Custom API](https://repoprompt.com/docs/1.6.0/providers/custom-api/), which connects to an OpenAI-compatible direct model API. ### Configure the route In [CC Custom settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#cc-custom), enable the backend and set its display name, base URL, authentication mode, and credential. Choose the authentication variable expected by the endpoint, save the credential, and use **Test Backend**. The installed Claude executable is required. The endpoint operator determines whether the chosen protocol, authentication, model, and tool behavior are compatible. A saved URL and key are not evidence of a successful request; test the actual route. ### Choose model behavior **No model flag** leaves the model choice to the endpoint and omits Claude model and effort selection. **Claude slot mappings** maps the **Haiku**, **Sonnet**, and **Opus** slots to backend model IDs; all three mappings must be filled before launch in that mode. Use identifiers from the endpoint's own catalog or documentation. See [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for shared identifier and selection concepts. Changing the endpoint or mappings does not make an incompatible model support the Claude runtime's requests. ### Capabilities and billing The route uses the Claude Code integration, but the endpoint's implementation determines the model capabilities and response behavior. Switching between compatible backends and standard Claude Code starts a fresh provider context. The endpoint operator controls billing, privacy, and retention. Use a credential intended for that destination and review its terms. Neither an Anthropic subscription nor an unrelated API account automatically pays for this custom route. --- ## Claude Code Compatible Backend: CC Moonshot (Providers) CC Moonshot uses the installed Claude Code executable with the Kimi coding endpoint and its own credential. It is a separate route from the standard Claude login and from other Claude-compatible backends. ### Configure and test Open [CC Moonshot settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#cc-moonshot), save the Kimi credential, and choose **Test Backend**. The preset base URL is `https://api.kimi.com/coding/`. Advanced controls can change the display name, endpoint, and authentication-variable choice. The Claude executable must be available, but an Anthropic account login is not required for this endpoint route. The credential information control opens the provider's account console. Use the backend test after changing its connection settings. ### Backend-managed models Kimi chooses the model. RepoPrompt supplies neither a `--model` flag nor a Claude Code effort level for this backend. It can therefore appear as one backend choice rather than an exhaustive list of named models. Do not add a model ID copied from the Claude or OpenAI catalog to force a choice this route does not expose. See [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for the distinction between a model identifier, an alias, and backend-managed selection. ### Account and capability boundary The Claude integration supplies its session and tool framework; the compatible endpoint determines actual model behavior and support. Changing between Claude routes starts a fresh provider context so the endpoint and authentication are applied cleanly. Kimi's coding-service account and terms govern access, allowance, billing, and retention. Use the account links in the settings card or the [Moonshot platform](https://platform.moonshot.ai) to inspect the relevant service; an Anthropic subscription does not cover this backend automatically. --- ## Claude Code Compatible Backend: CC Zai (Providers) CC Zai reuses the installed Claude Code executable with Z.ai's Anthropic-compatible endpoint. It needs the Claude executable and a Z.ai credential, but does not require an Anthropic account login for this backend route. The app's default display name is **CC Zai**; a saved custom display name can replace it. ### Configure the backend Open [CC Zai settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#cc-zai), save the credential, inspect the model-slot mappings, and choose **Test Backend**. The test uses the backend's configured endpoint and authentication overrides rather than the standard Claude login. The credential is shared with [Z.AI API](https://repoprompt.com/docs/1.6.0/providers/zai-api/). Changing or deleting it in either settings location affects that saved secret. Endpoint and model configuration remain specific to the relevant integration. ### Model-slot mappings The Claude **Haiku**, **Sonnet**, and **Opus** slots map to backend model IDs. Fill all three slots for mapped-model operation. The slot label alone does not identify the actual model requested from Z.ai. **Reset to GLM defaults** restores the app's preset mappings. Inspect the current fields for their exact IDs rather than relying on a fixed list in documentation. See [Z.ai documentation](https://docs.z.ai/) for model availability and endpoint support, and [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for slot and identifier concepts. ### Capabilities and account boundary The backend uses the Claude Code integration's tool and permission machinery while its endpoint supplies model behavior and usage terms. Test changes to endpoint, authentication mode, or mappings. Switching between standard Claude Code and compatible backends starts a fresh provider context. Z.ai's account or coding-plan terms apply. An Anthropic subscription does not pay for this route, and a shared API credential does not make every Z.ai product's billing or limits identical. --- ## Claude Code CLI (Providers) Claude Code CLI runs coding sessions through the installed `claude` executable. The app may label this provider **Claude Code**. Its integration supports agent conversations, tool activity, context compaction, and RepoPrompt MCP tools. ### Connect and authenticate Install and authenticate Claude Code using its supported login flow. When login is needed, run `claude login` in your terminal, then open [Claude Code CLI settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#claude-code-cli) and choose **Connect**. **Test Connection** rechecks the integration. RepoPrompt's **Sign Out** clears its recorded Claude connection state. Manage the standalone CLI's authentication separately when you need to change that login. This integration is distinct from the [Anthropic API](https://repoprompt.com/docs/1.6.0/providers/anthropic-api/) key configured for direct model requests. ### Models and capabilities The connected runtime supplies model and effort choices. See [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for selection concepts; a label in a captured screenshot is not a permanent default. Claude's permission mode, Bash access, strict MCP scope, and lazy tool loading are configured in its settings. Advanced prompt packaging controls how RepoPrompt delivers Agent Mode instructions. Refer to the [settings controls](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#claude-tools) for their exact effects and when changes apply. ### Compatible backends and accounts [CC Zai](https://repoprompt.com/docs/1.6.0/providers/cc-zai/), [CC Moonshot](https://repoprompt.com/docs/1.6.0/providers/cc-moonshot/), and [CC Custom](https://repoprompt.com/docs/1.6.0/providers/cc-custom/) reuse the Claude executable with different endpoints and credentials. They are separate routes from the standard Anthropic-backed login. Switching between those routes starts a fresh provider context so the endpoint and authentication are applied cleanly. The authentication route determines account usage and billing. A Claude subscription does not automatically cover direct Anthropic API requests or requests billed by a compatible backend operator. --- ## Codex CLI (Providers) Codex CLI is a coding-agent integration with native session control, streaming, compaction, provider tools, and reasoning effort. It runs the agent that performs work in your selected checkout. It is separate from [OpenAI API](https://repoprompt.com/docs/1.6.0/providers/openai-api/) access. ### Connect and authenticate RepoPrompt includes a managed Codex runtime and maintains its sign-in separately from the ordinary standalone Codex home. In [Codex CLI settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#codex-cli), choose **Connect**, then complete **Login with ChatGPT** or the device-code flow. Use **Test Connection** to recheck the integration. Advanced settings can select a custom executable. Runtime selection takes effect on the next app launch, when model availability is refreshed. A version check does not guarantee a custom runtime's compatibility. The settings guide explains executable selection, restoring the included runtime, and signing out. ### Models and capabilities Select from the models and reasoning levels advertised by the active runtime. Available choices depend on the runtime, account, and feature. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains identifiers, aliases, effort, and Fast tiers without assuming a fixed release catalog. Codex tool controls cover Bash, Search, Goals, Reasoning Summaries, Local Memories, and configured MCP servers. [Tools](https://repoprompt.com/docs/1.6.0/sessions/tools/) explains the composer controls; [Codex settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#core-tools-and-runtime-features) documents the individual switches. Eligible direct sessions can also use [Computer Use](https://repoprompt.com/docs/1.6.0/sessions/computer-use/) when its companion and local permission requirements are met. ### Account and usage The account signed into RepoPrompt's managed runtime determines access and allowance. It need not be the account used by a separate terminal installation. CLI access does not save an OpenAI API key or pay for direct API requests. Check the connected account's plan and usage for the route being used. --- ## Cursor CLI (Providers) Cursor CLI connects the installed `cursor-agent` runtime through ACP. RepoPrompt discovers its models and parameters and supplies its MCP integration to the session. ### Connect and authenticate Install the Cursor agent runtime and complete its supported authentication. Open [Cursor CLI settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#cursor-cli) and choose **Connect**. The runtime can request login or use supported credentials such as `CURSOR_API_KEY` or `CURSOR_AUTH_TOKEN`. Use **Test Connection** to recheck access and **Refresh Models** to request the current catalog. **Sign Out** disconnects Cursor in RepoPrompt and clears cached model availability. ### Models and capabilities Select from the model, effort, and speed parameters returned by the connected runtime. Cursor's **Auto** option delegates model selection to Cursor; it is distinct from RepoPrompt's Model Router. See [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for shared selection concepts. Model, effort, and speed controls are locked while an active Cursor run is using them. Its ACP approval controls are documented in [CLI Providers settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#cursor-cli). Available capabilities depend on the runtime and selected model; a connection does not establish unrestricted access to every tool. ### Account and usage Cursor authentication and its account terms determine access and allowance. Connecting this runtime does not configure the same model through a separate API provider or transfer Cursor account entitlement to that API. Check the account and selected runtime route when assessing usage. --- ## Custom API (Providers) Custom API connects a separate OpenAI-compatible model endpoint to supported RepoPrompt features. It is distinct from [CC Custom](https://repoprompt.com/docs/1.6.0/providers/cc-custom/), which routes the Claude Code coding runtime through an Anthropic-compatible endpoint. ### Configure the connection Open [Custom API settings](https://repoprompt.com/docs/1.6.0/settings/custom-api/) and enter the provider URL, including its API version path where required, and the credential expected by that endpoint. An endpoint that requires no authentication can use an empty key. Leave **Preferred Model ID** blank to discover models. If the endpoint cannot list models, supply its exact compatible model ID instead. Validation with a preferred model sends a short test completion request, so it contacts the provider rather than merely checking the field format. The settings reference describes output-token limits, model enablement, the Content-Type option, credential handling, and removal. Validate changes before relying on the route. ### Models and compatibility The endpoint operator determines available models and protocol behavior. OpenAI compatibility does not guarantee support for every streaming, tool, image, or reasoning feature. Follow the endpoint's documentation and [Models](https://repoprompt.com/docs/1.6.0/providers/models/) when choosing an identifier and capabilities. Per-model overrides in [Model Config](https://repoprompt.com/docs/1.6.0/settings/model-config/) can adapt supported request behavior; they cannot implement missing endpoint functionality. ### Account and billing The endpoint's operator controls billing, quotas, privacy, and retention. A credential or subscription for another service does not establish entitlement here. Confirm the destination before saving credentials; the app can request consent before sending them to a non-HTTPS endpoint. --- ## DeepSeek (Providers) DeepSeek provides direct API access for supported RepoPrompt model features. Configure the credential through [API Providers → DeepSeek](https://repoprompt.com/docs/1.6.0/settings/api-providers/#deepseek), validate it, and select an available model or supported custom identifier. ### Models and availability Use the [DeepSeek model-list documentation](https://api-docs.deepseek.com/api/list-models/) for current API identifiers and the connection's discovered choices for actual availability. A model ID can change its backing release or retire; a name captured in a screenshot is not a permanent default. Check the selected model's capabilities and limits for the feature you intend to use. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains how model IDs, context capacity, effort, and output settings differ. A per-model override cannot add functionality the provider does not implement. ### Account and billing Requests are associated with the account owning the DeepSeek credential. Review its current [API pricing](https://api-docs.deepseek.com/quick_start/pricing/) and account usage rather than relying on a price or free quota copied into a guide. RepoPrompt does not add a markup or transfer allowance from another provider. The [settings reference](https://repoprompt.com/docs/1.6.0/settings/api-providers/#deepseek) explains validation, model selection, and credential removal. Removing the key in RepoPrompt does not close the provider account. --- ## Devin CLI (Providers) Devin CLI runs coding sessions through the installed `devin acp` runtime. Devin manages its authentication and internal tools; RepoPrompt supplies the session interface and supported integration. ### Prepare the runtime Install and authenticate Devin using its own supported tools. Open [Devin CLI settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#devin-cli) to inspect runtime availability and request **Refresh Models**. The availability indicator describes installation, not a guarantee that authentication or every model request will succeed. ### Models and permission behavior Choose from the runtime's discovered models. Devin can encode thinking choices in model identifiers rather than exposing a separate native effort level. Follow the returned choices and the [Models guide](https://repoprompt.com/docs/1.6.0/providers/models/), not names copied from another provider's menu. The selected permission mode applies to newly started processes. The settings reference describes **Provider Default**, **Normal**, **Accept Edits**, **Smart**, and **Full Approval**, including which actions can run automatically. This integration does not expose Devin's autonomous mode. A permission mode is specific to the runtime. It does not establish the same sandbox guarantees as similarly named choices on other providers. Inspect the current session's tools, permissions, and execution location before assigning file changes. ### Account and usage Devin's authenticated account and product terms determine allowance and charges. Manage that account through Devin's own authentication tools. Connecting another CLI provider or direct API account in RepoPrompt does not grant Devin access. --- ## Fireworks AI (Providers) Fireworks AI supplies direct API model access for supported RepoPrompt features. Configure its credential in [API Providers → Fireworks AI](https://repoprompt.com/docs/1.6.0/settings/api-providers/#fireworks-ai), validate it, and inspect the discovered model choices. ### Models and capabilities Use the [Fireworks model library](https://fireworks.ai/models) to investigate available models. Selection in RepoPrompt depends on what the connected API account and serving configuration expose. A published library entry does not automatically establish access through every account or endpoint. Choose a model suitable for the intended feature and confirm its actual limits. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains the shared availability and identifier concepts. Keep the exact selection with the connection instead of copying an assumed model default into workflow instructions. ### Account and billing The Fireworks account, selected model, and serving option determine usage charges. Consult [Fireworks pricing](https://fireworks.ai/pricing) and the account's billing controls for current terms. A subscription or credential from another AI provider does not supply allowance for this API route. The settings page owns the field and button descriptions for validation, discovered choices, changing a credential, and deleting it. An empty model list should be investigated through that connection rather than treated as a complete statement of the provider's public catalog. --- ## Gemini API (Providers) Gemini API connects supported RepoPrompt features directly to Google's model API. It uses the **Gemini** entry in API Providers and is separate from the [Google Antigravity](https://repoprompt.com/docs/1.6.0/providers/google-antigravity/) coding-agent runtime and its ACP authentication. ### Connect and select a model Configure and validate the key in [API Providers → Gemini](https://repoprompt.com/docs/1.6.0/settings/api-providers/#gemini). Use the custom-model field where provided to save a compatible model identifier. The settings reference describes the field and its save control. Google's [Gemini API model catalog](https://ai.google.dev/gemini-api/docs/models) is the reference for current IDs, capabilities, and lifecycle status. Stable, preview, and retired selections can differ, and availability depends on the account and integration. Do not assume a similarly named model in another Google product is exposed through this API route. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains identifier and capability selection. A per-model setting cannot grant access to a missing model or add unsupported image, streaming, or reasoning behavior. ### Account and billing The API credential and Google's applicable account terms determine usage limits and charges. A separate Google subscription or Antigravity login does not automatically configure or pay for these API requests. Check the API account's current terms and usage rather than relying on a fixed free-tier claim in documentation. --- ## Google Antigravity (Providers) Google Antigravity is a coding-agent integration using a managed ACP runtime. It is distinct from saving a [Gemini API](https://repoprompt.com/docs/1.6.0/providers/gemini-api/) key for direct model requests. ### Install and connect Open [Google Antigravity settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#google-antigravity) and choose **Install Runtime**. Use **Update Runtime** for an existing installation and **Test Connection** to check support and refresh model discovery. Google authentication is requested through ACP when needed. An installation indicator means the runtime is available; it does not establish that login is complete or that selectable models were returned. Follow the authentication request and inspect the connection result before starting a task. ### Models and capabilities The connected runtime supplies its supported model choices and session capabilities. Use that catalog rather than assuming it matches the direct Gemini API catalog. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains the shared availability and parameter concepts. Antigravity uses its ACP session modes and manages its runtime capabilities. Its CLI Providers card has no separate sign-out or inline permission picker. Review the available [Direct Agent permission controls](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/#direct-agents) for the installed runtime instead of applying another provider's permission descriptions to it. ### Account and usage The authenticated Google account and runtime's service terms determine access and allowance. A Gemini API key or a separate Google subscription does not, by itself, establish access through this managed runtime. Check the actual login and runtime state when troubleshooting availability. --- ## Grok Build (Providers) Grok Build connects the installed `grok` runtime to Agent Mode. It is a coding-agent integration with model discovery and provider-native shell and editing capabilities. Direct [Grok / xAI API](https://repoprompt.com/docs/1.6.0/providers/xai-api/) model access is a separate integration. ### Connect and authenticate Make the Grok runtime available, authenticate with `grok login` or configure the API credential supported by the integration, then open [Grok Build settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#grok-build). Choose **Connect** and inspect the model-discovery result. **Test Connection** rechecks access; **Sign Out** disconnects Grok Build in RepoPrompt and clears cached availability. ### Models and permissions Use models discovered from the connected runtime. A model visible in xAI's public API catalog does not automatically identify the same selection in the coding runtime. See [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for discovery and identifier guidance. Grok's launch approval choice applies to newly started processes. Its Full Access option starts the runtime with always-approve behavior for shell and editing tools. The [settings reference](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#grok-build) explains the exact launch controls. Grok's own rules can also affect approval behavior; do not treat its modes as identical to Codex's sandbox levels. ### Account and usage The route used by the runtime determines the account and usage terms. When the integration supplies an xAI API key, requests using that credential are billed to the corresponding API account. Check whether a run is using account login or an API credential before assuming that one account plan covers it. --- ## Groq (Providers) Groq is a direct API provider configured with its own credential. **Groq** and **Grok (xAI)** are different services and settings entries; credentials and model selections do not transfer between them. ### Connect and select a model Use [API Providers → Groq](https://repoprompt.com/docs/1.6.0/settings/api-providers/#groq), validate the key, and inspect the discovered models. The [Groq model catalog](https://console.groq.com/docs/models) describes the hosted models, while [deprecation notices](https://console.groq.com/docs/deprecations) identify retirement changes. Actual availability depends on the connected account and integration. Use the current returned identifier instead of assuming a model hosted by another service has the same ID or capabilities here. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains that distinction and the separate roles of context limits, effort, and output controls. ### Account and billing Requests use the Groq account associated with the saved credential. The provider controls its usage terms, quotas, rate limits, and charges. RepoPrompt cannot guarantee that a particular account or hosted model has free allowance. The [settings reference](https://repoprompt.com/docs/1.6.0/settings/api-providers/#groq) describes credential and discovered-model controls. If the list changes after a refresh, check both connection access and the provider's lifecycle notices before reusing an older saved ID. --- ## Local Models: Ollama and LM Studio (Providers) The local-model integration connects RepoPrompt to a model server you run, such as Ollama or LM Studio. You install the server and obtain its models separately; saving a URL in RepoPrompt does not install or start either service. ### Prepare and connect Start the model server and make the intended model available there. Open [API Providers → Local Model Settings](https://repoprompt.com/docs/1.6.0/settings/api-providers/#local-model-settings), enter its URL, and choose **Validate & fetch models**. After discovery succeeds, select a model. Common local ports are **11434** for Ollama and **1234** for LM Studio. Use the actual address configured by your server rather than assuming a default port proves the service is running. The settings guide explains refreshing discovery and resetting the saved configuration. ### Models and capabilities Model availability comes from the connected server. Browse [Ollama's model library](https://ollama.com/library) or inspect the models installed in LM Studio, then confirm what the server exposes to RepoPrompt. Capabilities and practical context limits depend on the model, server, and hardware. See [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for selection concepts. A local-server connection does not automatically provide the coding-agent runtime or feature set of a CLI provider. ### Local resources and hosted routes Inference that actually runs locally has no hosted per-token API bill from RepoPrompt, but uses your computer's memory, processing, storage, and electricity. A server configured to call a cloud model or remote endpoint can have separate provider charges and data practices. Check where the chosen request runs before treating it as local. --- ## Models (Providers) Choose models from the connection you intend to use. RepoPrompt combines built-in catalog information with model discovery where the integration supports it. The connected model picker determines what is selectable in that feature; a provider's public catalog alone does not establish availability in your account or runtime. This guide is the shared reference for model concepts. Use the [provider directory](https://repoprompt.com/docs/1.6.0/providers/overview/) for connection-specific setup and catalog links, [Model and Effort](https://repoprompt.com/docs/1.6.0/sessions/model-and-effort/) for the session controls, and [Agent Models settings](https://repoprompt.com/docs/1.6.0/settings/agent-models/) for configured defaults and workspace overrides. ### Availability and discovery A CLI runtime can expose a different model set from the same company's direct API. API access can also depend on region, account permissions, deployment, or the endpoint operator. Refresh or test the relevant connection when a model is missing; changing a model's display label cannot make an unsupported model available. Some integrations discover models. Others accept an exact custom model identifier, a deployment choice, or a backend that chooses its own model. OpenRouter requires registering the fetched models you want to expose. Custom API can use discovered models or a preferred model ID. Follow the individual provider guide for the supported route. ### Names, identifiers, aliases, and presets The human-readable label in a picker can differ from the identifier sent to a runtime or API. Reuse the choice returned by that connection instead of guessing an identifier from a screenshot or another provider's catalog. An **alias** or **Auto** choice delegates some selection to the provider. It may not identify one fixed underlying model and does not necessarily qualify for every automatic-effort feature. A **deployment name** identifies an Azure resource deployment rather than universally naming a public model. An **Oracle Model Preset** is a named configuration. It can contain a primary model, additional Oracles, and a mapped Chat Preset. It is not itself a model identifier. Claude-compatible backends can instead map the Claude **Haiku**, **Sonnet**, and **Opus** slots to endpoint model IDs, or omit the model flag and let the backend decide. ### Reasoning effort Effort chooses among reasoning levels advertised for the selected model. Labels such as **Low**, **Medium**, and **High** are examples, not a universal set or a standardized quantity across providers. Some runtimes expose thinking parameters or encode thinking choices in the model ID; others offer no separate effort control. More effort can increase latency and usage. Compare results on the work you actually need rather than assuming the highest level is always appropriate. Effort, maximum output length, and context capacity are separate controls: raising one does not necessarily raise the others. An effort choice applies to a turn. [Auto Effort](https://repoprompt.com/docs/1.6.0/sessions/auto-effort/) can choose before eligible user turns on an explicitly selected supported model. It does not retune effort between tool calls in an active turn. [Model Router](https://repoprompt.com/docs/1.6.0/sessions/model-router/) chooses a model and initial effort for eligible new tasks. Those guides own the features' eligibility, privacy, and fallback behavior. ### Speed and service tiers A **Fast** variant or API service tier changes the service route or speed/cost behavior where supported. It is separate from reasoning effort and can consume allowance or credits differently. A lightning symbol is not a universal quality rating. Choose tiers supported by the actual connection. OpenAI's API service-tier controls, a CLI runtime's Fast option, and OpenRouter routing are different mechanisms; their settings do not automatically carry across providers. Consult the relevant provider page and account's current terms. ### Model roles RepoPrompt uses model choices in several places: | Choice | Responsibility | | --- | --- | | **Session execution model** | Runs the coding agent and its permitted tools. | | **Oracle roster** | Provides consultations for plans, reviews, or answers using prepared context. | | **Context Builder agent and model** | Explores the repository and assembles relevant context. | | **Re-prompt model** | Rewrites a draft before the execution agent receives it. | | **Agent role defaults** | Map task labels to configured provider/model choices. | For discovery, consider latency, reliable repository-tool use, and the amount of context the agent must inspect. For implementation, consider instruction following and reliable editing and tool use. For Oracle planning or review, consider reasoning over the complete prepared package. These are task requirements, not permanent rankings of named model releases. The **Explore**, **Engineer**, **Pair**, and **Design** role labels resolve through the effective [Agent Models profile](https://repoprompt.com/docs/1.6.0/settings/agent-models/#sub-agent-role-defaults). Explore suits focused investigation, Engineer implementation, Pair interactive work, and Design architectural discussion or critique. A role mapping is not a sandbox policy or a universal guarantee of read-only behavior. Dedicated exploration tools and permission settings impose their own restrictions. ### Recommendations and screenshots Use the app's current Setup Wizard and available-model controls to evaluate recommendations for your connected providers. Available choices and recommendations can change when the runtime, catalog, account, or app version changes. Screenshots capture one interface state. Their model names, selected effort, token capacities, and provider counts are illustrative, not promised defaults. General guides therefore emphasize providers, capabilities, and selection procedures instead of maintaining exhaustive named model lists. For an exact model ID, capability, retirement, or price, use the official catalog linked from the provider's page and verify availability through your connection. When documentation must discuss a particular release, identify the app version or review date and keep that claim with the relevant provider reference. Historical changelogs retain the model names necessary to describe their release. --- ## OpenAI API (Providers) OpenAI API connects supported RepoPrompt model features directly to an API account. It is separate from the [Codex CLI](https://repoprompt.com/docs/1.6.0/providers/codex-cli/) runtime and RepoPrompt-managed ChatGPT sign-in. ### Connect Validate a credential in [API Providers → OpenAI](https://repoprompt.com/docs/1.6.0/settings/api-providers/#openai) to fetch available models. The settings page documents API service tiers, tier-specific model variants, and the optional custom base URL. For an independently configured OpenAI-compatible service, use [Custom API](https://repoprompt.com/docs/1.6.0/providers/custom-api/). For an Azure resource deployment, use [Azure OpenAI](https://repoprompt.com/docs/1.6.0/providers/azure-openai/). Compatibility with the OpenAI protocol does not establish the same account, model IDs, or service terms. ### Models and capabilities The [OpenAI API model catalog](https://platform.openai.com/docs/models) is the provider reference for model identifiers and capabilities. Actual selection depends on the API account, endpoint, and integration support. A model available through a CLI or subscription product is not necessarily available through this API connection. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains effort and service tiers. Use [Model Config](https://repoprompt.com/docs/1.6.0/settings/model-config/) for supported streaming, API-routing, and temperature overrides; these do not grant access to unavailable models. ### Account and billing The API project and credential determine request charges and quotas. A ChatGPT subscription or Codex login does not automatically fund API calls. Inspect the relevant API account and service tier when assessing usage. --- ## OpenCode CLI (Providers) OpenCode CLI connects coding sessions through Agent Client Protocol (ACP). The app may label it **OpenCode**. Its available models come from the providers configured in OpenCode, which can differ from the direct API connections configured in RepoPrompt. ### Connect and authenticate Make the `opencode` runtime available and configure the intended providers in OpenCode. Authenticate there as needed, for example with `opencode auth login`. Open [OpenCode CLI settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#opencode-cli), choose **Connect**, and inspect the discovered-model summary. **Test Connection** rechecks access. Signing out in RepoPrompt clears its connection and cached availability; manage OpenCode's credentials through OpenCode itself. ### Models and capabilities RepoPrompt discovers the runtime's model choices and supported parameters. Use the current picker rather than copying model IDs from another connection. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains why provider aliases, effort parameters, and direct API models are not interchangeable. Interactive sessions use ACP and provider tools alongside RepoPrompt's integration. Headless discovery uses a separate managed tool configuration. The provider's [ACP Session Mode controls](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#opencode-cli) govern approval behavior for supported requests; do not assume that another provider's sandbox or MCP switches have identical effects here. ### Account and usage The upstream providers configured in OpenCode determine authentication, model availability, quotas, and charges. Some configurations can offer free access, but RepoPrompt does not establish the terms of that access. Review the provider route selected in OpenCode when comparing usage or troubleshooting a missing model. --- ## OpenRouter (Providers) OpenRouter is a separate API route for models served through your OpenRouter account. It has its own settings page rather than a row in the direct API-provider pane. A model available through OpenRouter can have a different identifier, route, availability, and price from a direct connection to its originating provider. ### Connect and register models Open [OpenRouter settings](https://repoprompt.com/docs/1.6.0/settings/openrouter/), validate an API key, and fetch the catalog. Search the fetched models and register the choices you want to appear in RepoPrompt. Fetching the catalog does not automatically register every entry. The settings reference owns the descriptions of registered-model removal, catalog refresh, custom headers, and output limits. Removing a registration hides that selection in RepoPrompt; it does not remove the model from the provider's service. ### Model metadata OpenRouter's [model API](https://openrouter.ai/docs/api/api-reference/models/get-models) is the provider reference for IDs, context information, modalities, and pricing metadata. Use the current account-accessible catalog and exact returned identifier. A similarly named model on another route is not necessarily interchangeable. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains these naming and capability distinctions. Request settings and headers cannot add a capability the selected model or route lacks. ### Account and billing Your OpenRouter account and selected service route determine charges and allowance. An account or subscription with the model's originating provider does not automatically fund OpenRouter requests. Review the actual route and account when assessing usage, privacy, and retention. --- ## Providers & Models (Providers) Start here to choose and connect a provider. Each integration's page is the reference for its account requirements, model discovery, capabilities, and limitations. [Models](https://repoprompt.com/docs/1.6.0/providers/models/) explains identifiers, aliases, reasoning effort, speed tiers, and choosing models for different roles. A **provider** supplies an agent runtime or model service. A **model** is a choice available through that connection. The same company can offer separate CLI and API products with different authentication, billing, and capabilities. For example, connecting Codex CLI does not configure OpenAI API access, and signing into Claude Code does not save an Anthropic API key. ### Provider comparison Choose the connection that matches the work and account you intend to use. The summaries below wrap naturally on narrow screens; open an individual guide for setup and limitations. ### Coding agents These ten integrations run coding-agent sessions. Configure their controls in [CLI Providers settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/). The app can abbreviate **Claude Code CLI** to **Claude Code** and **OpenCode CLI** to **OpenCode**. 1. **[Codex CLI](https://repoprompt.com/docs/1.6.0/providers/codex-cli/)** — included or custom runtime with RepoPrompt-managed ChatGPT sign-in. 2. **[Claude Code CLI](https://repoprompt.com/docs/1.6.0/providers/claude-code-cli/)** — installed Claude runtime with Anthropic authentication. 3. **[OpenCode CLI](https://repoprompt.com/docs/1.6.0/providers/opencode-cli/)** — ACP runtime using providers configured in OpenCode. 4. **[Cursor CLI](https://repoprompt.com/docs/1.6.0/providers/cursor-cli/)** — Cursor runtime with discovered models and provider parameters. 5. **[Grok Build](https://repoprompt.com/docs/1.6.0/providers/grok-build/)** — installed Grok runtime with login or a configured API key. 6. **[Google Antigravity](https://repoprompt.com/docs/1.6.0/providers/google-antigravity/)** — managed ACP runtime with Google authentication. 7. **[Devin CLI](https://repoprompt.com/docs/1.6.0/providers/devin-cli/)** — Devin ACP runtime with its own authentication and permission modes. 8. **[Claude Code Compatible Backend: CC Zai](https://repoprompt.com/docs/1.6.0/providers/cc-zai/)** — Claude runtime routed to Z.ai with model-slot mappings. 9. **[Claude Code Compatible Backend: CC Moonshot](https://repoprompt.com/docs/1.6.0/providers/cc-moonshot/)** — Claude runtime routed to Kimi, which manages the model choice. 10. **[Claude Code Compatible Backend: CC Custom](https://repoprompt.com/docs/1.6.0/providers/cc-custom/)** — Claude runtime routed to an Anthropic-compatible endpoint you configure. ### API and local services Direct model connections primarily serve Oracle, built-in Chat, and other supported model features. They do not by themselves install a coding-agent runtime. The **API Providers** pane contains ten direct API or local configurations: - [Anthropic API](https://repoprompt.com/docs/1.6.0/providers/anthropic-api/) - [OpenAI API](https://repoprompt.com/docs/1.6.0/providers/openai-api/) - [DeepSeek](https://repoprompt.com/docs/1.6.0/providers/deepseek/) - [Fireworks AI](https://repoprompt.com/docs/1.6.0/providers/fireworks-ai/) - [Grok / xAI API](https://repoprompt.com/docs/1.6.0/providers/xai-api/) - [Groq](https://repoprompt.com/docs/1.6.0/providers/groq/) - [Z.AI API](https://repoprompt.com/docs/1.6.0/providers/zai-api/) - [Gemini API](https://repoprompt.com/docs/1.6.0/providers/gemini-api/) - [Azure OpenAI](https://repoprompt.com/docs/1.6.0/providers/azure-openai/) - [Local models: Ollama and LM Studio](https://repoprompt.com/docs/1.6.0/providers/local-models/) [OpenRouter](https://repoprompt.com/docs/1.6.0/providers/openrouter/) and [Custom API](https://repoprompt.com/docs/1.6.0/providers/custom-api/) are additional routes with their own configuration pages. Use [API Providers settings](https://repoprompt.com/docs/1.6.0/settings/api-providers/) for the direct-provider fields and controls. ### Choose and switch providers Connect the intended runtime or service, complete its authentication, and test the connection. Then choose from the models that connection actually offers. A provider's published catalog can be broader than what your account, runtime, region, or deployment exposes. Use [Model and Effort](https://repoprompt.com/docs/1.6.0/sessions/model-and-effort/) to operate the session picker. Configure Oracle, Context Builder, and role defaults in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). Those choices serve different purposes and can use different connections; see [Model roles](https://repoprompt.com/docs/1.6.0/providers/models/#model-roles). ### Accounts and billing RepoPrompt CE is free and does not add a provider markup. The selected account and route determine usage charges and quotas. A CLI subscription does not automatically pay for API calls, and an API credential does not establish access to a separate CLI subscription product. Each provider page explains the relevant distinction and links to its catalog where applicable. For the short billing answer, see [Do I need to pay for AI services?](https://repoprompt.com/docs/1.6.0/faq/pay-for-services/). For changing model catalogs and screenshots, follow the [Models guide](https://repoprompt.com/docs/1.6.0/providers/models/#recommendations-and-screenshots) rather than treating a captured model name as a permanent default. --- ## Grok / xAI API (Providers) The **Grok (xAI)** entry connects supported RepoPrompt model features directly to the xAI API. It is separate from [Grok Build](https://repoprompt.com/docs/1.6.0/providers/grok-build/), which runs a coding-agent CLI. It is also unrelated to the separately configured [Groq](https://repoprompt.com/docs/1.6.0/providers/groq/) service. ### Connect and choose models Validate the xAI credential in [API Providers → Grok (xAI)](https://repoprompt.com/docs/1.6.0/settings/api-providers/#grok-xai) and inspect the discovered models. Use the provider's [model catalog](https://docs.x.ai/developers/models) and [release notes](https://docs.x.ai/developers/release-notes) for current identifiers and service changes. Available choices depend on API account access and integration support. Do not assume that a Grok Build runtime model name is interchangeable with a direct API ID. See [Models](https://repoprompt.com/docs/1.6.0/providers/models/) for availability and naming concepts. ### Credentials and billing The configured API key can also be used by integrations that support the Grok API-key route, including Grok Build. The presence of that runtime does not change the billing boundary: requests authenticated with the key are associated with its xAI API account. Check which route a task is using before comparing allowance or charges with a separate account-login product. The [settings reference](https://repoprompt.com/docs/1.6.0/settings/api-providers/#grok-xai) describes key validation and model controls; the Grok Build guide covers runtime setup. --- ## Z.AI API (Providers) Z.AI provides direct API model access for supported RepoPrompt features. It is distinct from [CC Zai](https://repoprompt.com/docs/1.6.0/providers/cc-zai/), which runs the Claude Code runtime through Z.ai's compatible coding endpoint. ### Connect and choose models Use [API Providers → Z.AI](https://repoprompt.com/docs/1.6.0/settings/api-providers/#zai) to save and validate the credential and choose a supported custom model where offered. Refer to [Z.ai's documentation](https://docs.z.ai/) for the current model catalog and API support. Use an identifier available through the actual connection rather than a fixed model release listed in a screenshot. ### Shared credential, distinct routes This saved credential is shared with CC Zai. Changing or deleting it in either settings location affects the same secret. Saving it also makes the compatible backend available when its runtime prerequisites and configuration are satisfied. Direct API model selection and the CC Zai Claude-slot mappings are separate configurations. A shared key does not mean they expose identical models, endpoints, or capabilities. See [Models](https://repoprompt.com/docs/1.6.0/providers/models/) and the CC Zai guide before changing those mappings. ### Account and billing Z.ai's terms for the account, endpoint, and product determine allowance and charges. Check which route is being used rather than assuming that a coding plan and a general API call share the same allowance. RepoPrompt does not add a provider markup. --- ## Settings Reference (Reference) Open Settings with `⌘+,` or from the gear icon. :::tip[Settings pages] The new Settings section follows the app’s navigation. Start with [Overview](https://repoprompt.com/docs/1.6.0/settings/overview/) or [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/) for detailed controls, or use [Search Settings](https://repoprompt.com/docs/1.6.0/settings/search-settings/) to find a page. These pages supersede the corresponding summaries below. ::: :::tip **Scripting these settings:** A subset of preferences is reachable from MCP and `rpce-cli` through `app_settings`, including appearance, prompt packaging, models, MCP preset visibility, Code Maps, file scanning, selected Agent Mode behavior, and notifications. See [App Settings Tool](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-app-settings/) for the current allowlist and [Setup Guide](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-setup/#terminal-access) for terminal access. The UI and tool share the underlying store for allowlisted keys. Credentials, permission policies, and workspace model overrides remain outside this tool; Classic editing and auto-start key examples no longer describe its registry. ::: ### 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 Use the [Providers & Models reference](https://repoprompt.com/docs/1.6.0/providers/overview/) for the supported integrations, account requirements, and model availability. [CLI Providers settings](https://repoprompt.com/docs/1.6.0/settings/cli-providers/) documents connection buttons and configuration controls. #### 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 --- ## Approvals and Paused Sessions (Sessions) A paused coding session can be waiting for a tool decision, an edit review, project-hook trust, or an answer to a question. Read the active card before changing permission settings or sending another task. Different cards authorize different actions; a provider's tool approval does not stand in for every RepoPrompt review. ### Tool approval An approval card shows **Needs your approval**, the requested operation, and available details such as the command or working directory. Read the proposed action and its scope. - **Approve** accepts the current request where supported. - **Decline** refuses the request and lets the runtime handle that outcome. - A session-approval option, when offered, has a broader scope than one request. - **Approve & Remember** accepts the proposed execution-policy amendment supplied with the request. Inspect that proposal before choosing it; it is not merely a second label for one-time approval. The available choices depend on the provider and request. A separate **Permission Approval** card does not offer remembered decisions through this interface. For default provider modes and the separate MCP sub-agent policy, see [Tools](https://repoprompt.com/docs/1.6.0/sessions/tools/) and [Agent Permissions](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/). ### Apply Edits Review This card shows the file path and a proposed unified diff. Read the additions and deletions before choosing **Accept**. To choose **Reject**, enter a **Rejection reason** first; rejection is disabled while that field is empty. Give an actionable reason, such as “Preserve the existing public method signature.” **⌘Return** accepts and **⌘Delete** rejects when the corresponding action is available. If the card says **No diff available**, obtain the information you need before accepting. The **Auto Edit** preference can bypass this separate edit review; it does not establish that generated changes are correct. ### Project Hooks Need Approval Codex can pause its initial turn to review repository-provided hooks. Check the **Execution directory**, hook details, and warnings. No hook is selected by default. Select the hooks you intend to trust and choose **Approve Selected & Continue**, or use **Trust All Shown** only after reviewing the full list. These choices concern project hooks, not general approval of every later tool request. Where available, **Continue Without Hooks** asks for confirmation before continuing without enabling those hooks. Strict hook mode hides this option. If discovery fails, the card offers **Retry**; inspect the displayed error and directory before retrying. ### Other reasons a session is waiting A question needs an answer in its input card. A [worktree merge review or conflict](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/) needs its own integration decision. An overseer can handle eligible one-time requests, but [oversight](https://repoprompt.com/docs/1.6.0/overseer/) does not transfer every approval: hook trust, merge reviews, session-wide grants, and secret inputs remain with you. If the session still appears paused, check the currently displayed blocker and any error after your response. Another pending decision may be shown next; repeated approval is not a general recovery procedure. --- ## Auto Effort (Sessions) **Auto Effort** is the gauge control above the message editor. It chooses reasoning effort before an eligible user turn while keeping the model you selected. Use it when you want effort to respond to the task rather than manually choosing a level for every message. Enable Auto Effort confirmation explaining the excerpt, model ID, effort choices, workflow category, and privacy controls Choose **Enable Auto Effort** after reviewing the disclosure. **Privacy details…** opens its settings; **Cancel** leaves it disabled. The highlighted composer label identifies the decision service, such as **Auto Effort · Jev by TypeSafe**. Newer builds let Auto Effort and Model Router use independently selected services. Composer showing both Model Router and Auto Effort service labels ### Which turns are eligible? The selected supported model must be explicit and advertise multiple effort levels. Auto Effort can apply to an eligible first launch and to follow-up messages sent after the previous turn has settled. Model aliases, default selections, and custom workflows keep manual effort. A start already handled by Model Router retains the effort chosen by routing. Steering an agent while it is already working does not change effort mid-turn. Effort is held through that turn's tool calls. Auto Effort can be enabled independently of Model Router. ### Understand feedback and fallback While a decision is being made, the control can show a busy state. After a service choice, its tooltip reports the chosen effort; directional feedback compares service choices or the initial selected effort. It does not prove that every intervening message used that effort. If the service cannot make a valid decision, RepoPrompt uses the manual effort. You can turn Auto Effort off and select effort directly through [Model and Effort](https://repoprompt.com/docs/1.6.0/sessions/model-and-effort/). Different effort choices can affect latency, usage, and provider caching; savings are not guaranteed. ### What the service receives For each eligible turn, the service receives a short, best-effort-masked excerpt of the message, model ID, supported effort choices, and any built-in workflow category. The workflow template body, attached files, tool output, and earlier conversation are not added. Masking can miss private information in your message. Review the service's privacy details before enabling it. For service configuration, manual fallback, and eligibility details, see [Auto effort settings](https://repoprompt.com/docs/1.6.0/settings/model-router/#auto-effort). --- ## Computer Use (Sessions) **Computer Use** lets an eligible native Codex session interact with desktop applications through a supported companion. Use it for tasks that require the visible interface of another app, such as inspecting a rendered result or following a UI procedure that repository file tools cannot perform. The monitor-shaped control appears in the composer toolbar when the session is eligible. It reports **Computer Use on** or **off** for this chat, with a busy state while a change is being applied. Its presence does not mean every provider or sub-agent can use the desktop. Monitor-shaped Computer Use toggle in the session toolbar ### Prepare an eligible session Computer Use requires a top-level native Codex session with its own tab, the feature enabled, and a supported installed companion from Codex or ChatGPT. RepoPrompt reports when no companion is available. A provider connection alone is not enough to satisfy these requirements. Enable the feature in Codex's [Direct Agent permissions](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/), then enable it locally in the intended chat using the toolbar control. The native `/computer-use` command is another entry point when supported. macOS permissions must be granted manually; enabling the feature does not silently approve operating-system access. ### Give a bounded UI task Describe the application, the starting screen, the outcome, and any limits on what the agent should change. For example: “Open the local preview, inspect the sign-in form at narrow width, and report clipping; leave account settings unchanged.” Be explicit when a task should stop before submitting, purchasing, publishing, or otherwise making an external change. Watch the session's actions and respond to requests for input or approval. Computer Use is an additional way to carry out the task; the selected [execution location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/), tool permissions, and your instructions still matter. ### If the control is unavailable Check that the chat is a direct native Codex session rather than a different provider or an agent-controlled child. Check the feature setting, companion availability, and macOS permissions. Read any displayed configuration error before retrying. If the runtime reports a conflicting Computer Use integration, resolve that configuration rather than repeatedly sending the same request. For a screenshot that you simply want the agent to analyze, use [Image Support](https://repoprompt.com/docs/1.6.0/sessions/image-support/). Attaching an image provides visual input without enabling interactive desktop control. --- ## Context Builder (Sessions) Open the files/stack control at the right of the composer toolbar to review context. Its file count describes the selection, while the usage ring describes context consumption. Hover for the token count, percentage, and source. **Source: Live** identifies live usage information; it is not simply the sum of the selected files. **⌘P** opens the Context Composer by default. Context indicator tooltip showing live usage, token capacity, selected file count, and the Context Composer shortcut ### Selections: inspect what is included The drawer's **Selections** tab lists selected files and Code Maps separately. Filter the selection, change **Sort**, use **Add** for more context, or **Clear** to remove the selection. Each row reports size information and offers preview, copy, additional actions, and removal. Inspect large entries when you want to reduce the package or keep the agent focused. Selections tab with file filtering, sort, Add and Clear, file and Code Map counts, and per-file context sizes Selected context is useful preparation, but it is not an access-control boundary: an agent with repository tools can discover other files permitted by its tools and permissions. Use narrower instructions and the appropriate permission policy when you need to constrain work. ### Prompt: tell the receiving model what to do The **Prompt** tab contains **Receiving-model instructions** for the selected context. Use it to specify the question, scope, constraints, or expected result for the model receiving that package. This is distinct from the Context Builder's discovery task. Prompt tab and Receiving-model instructions heading The drawer can also expose prompt-packaging controls for stored prompts, the file tree, Code Maps, and Git context. Review those before copying or exporting a package; different presets can change its contents and size. For a complete manual workflow, see [Prepare and Copy Context](https://repoprompt.com/docs/1.6.0/sessions/context-composer/), including the difference between selected file context and checked Git changes. ### Context Builder: discover relevant code Choose the **Context Builder** tab. The top line identifies the discovery agent and model. **Prompts** selects additional discovery instructions. In **Task Description**, explain the task and known constraints; let the agent find the relevant code rather than preselecting the whole repository. Context Builder tab with discovery model, Prompts, Task Description, Budget, Run, and analysis follow-up controls **Budget** sets the target size for the package. The help and settings controls explain or adjust the related configuration. Choose **Run** to start discovery. The agent explores the codebase, builds a selection toward that budget, and can improve the prepared prompt according to your settings. A budget is a target for useful context, not a promise that every relevant file will fit. ### Optional analysis follow-up **Analysis follow-up → Auto** can run the selected plan, review, or question after discovery. Choose the analysis model and response type independently of the discovery model. The action button, such as **Generate Plan**, identifies the analysis you can request using the prepared context. Review the resulting selection and answer before using them for implementation. Discovery and analysis can consume separate provider usage. Configure budgets, rewriting behavior, clarification, and follow-up defaults in [Context Builder settings](https://repoprompt.com/docs/1.6.0/settings/context-builder/); choose the discovery runtime in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). --- ## Prepare and Copy Context (Sessions) Use Context Composer when you want to prepare a focused package for an external model or coding agent. It combines your receiving-model instructions with selected code and the packaging options you choose. Copying a package does not send a session message or invoke the receiving model. Open the files/stack control beside the composer or press **⌘P** with the default shortcut. The drawer has **Selections**, **Prompt**, and **Context Builder** tabs. See [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/) for automatic discovery; the steps below cover inspecting and copying the result yourself. ### Choose the code to include In **Selections**, inspect the selected files and Code Maps. Use **Add** to browse more files; the browser can add Code Maps rather than full content. Check the available per-file actions before changing representation: - **Convert to Full File** includes implementation content where that action is available. - **Convert to Codemap** keeps a compact structural representation where supported. - **Clear Slices** removes selected slice ranges; inspect the resulting selection before copying. Full files suit code the receiving model must understand in detail. Code Maps suit supporting types and API surfaces. Slices focus a large file on selected ranges. These representations affect the package, not the coding agent's filesystem permissions. ### Write receiving-model instructions Open **Prompt** and describe the question, constraints, and expected output. For example: “Review the selected authentication changes for regressions. Explain each finding using the surrounding code; do not implement fixes.” These instructions are distinct from the discovery task you give Context Builder. ### Choose packaging **Copy Preset** offers choices including **Standard**, **Plan · Architect**, **Review**, and **Manual**, along with available custom presets. A preset can change what is included; a Review preset alone does not establish which repository or changes you meant to review. Inspect **Prompts**, **File Tree**, **Code Map**, and **Git**. Manual mode uses the current packaging settings. Stored prompt selection and preset editing are covered by [Workflow Presets](https://repoprompt.com/docs/1.6.0/settings/workflow-presets/); section ordering is configured in [Copy Prompt Order](https://repoprompt.com/docs/1.6.0/settings/copy-prompt-order/). In **Git**, confirm the repository **Root** and comparison target. **None** omits Git changes, **Selected** includes checked pending changes, and **All** includes the available pending changes. File context selection and checked Git changes serve different purposes: selecting a source file is not the same as selecting its diff. ### Copy and check the package Choose **Copy Prompt**, then paste into a draft where you can inspect it before submitting. Confirm the instructions, file paths, relevant implementation, and intended Git changes. Reduce irrelevant full files or use narrower context if the receiving model cannot accept the package. The session's live context-usage ring describes runtime usage; it is not simply the size of this exported package. Copying context does not transfer a running conversation's entire history, provider permissions, or tool configuration. If the clipboard action reports **Copy failed**, retry after resolving the error rather than assuming the previous clipboard contents are the new package. --- ## Execution Location (Sessions) The execution-location control sits at the left of the toolbar above the message editor. It usually begins as **Work locally**. This is the filesystem location where the session's agent works, including its repository reads, edits, and shell commands within the applicable permissions. ### Choose where to start Open the control to see **Start in**. Select a location before sending the first message: | Choice | Use it for | | --- | --- | | **Workspace checkout** | Work directly in the checkout already open in the workspace. Edits appear alongside your existing local work. | | **New worktree** | Give the task a separate Git checkout, useful for parallel implementation or an alternative approach. | | **Existing worktrees** | Continue in an already-created checkout. Read the branch, worktree name, and path before choosing. | Start in menu with Workspace checkout selected, New worktree, and an empty Existing worktrees list The screenshot's **No other worktrees available** is an empty state. When worktrees are available, the list identifies them by branch or detached commit and directory. Unusable, prunable entries cannot be selected. A worktree requires a suitable Git repository; a plain folder does not acquire Git isolation merely because you choose a workflow. Your initial worktree selection is prepared when you first send. Check the location indicator and any creation error before assuming the task has started in a new directory. For repository setup and local file copying, see [Worktrees](https://repoprompt.com/docs/1.6.0/worktrees/). ### Keep parallel tasks from colliding Two sessions in **Workspace checkout** can edit the same files. Their conversation histories are separate, but their working directory is shared. Use different worktrees for tasks that may touch overlapping files, then review and integrate their changes deliberately. A worktree separates repository files; it does not change the provider's permissions or automatically isolate databases, remote services, or other resources the agent can access. Configure [Tools and permissions](https://repoprompt.com/docs/1.6.0/sessions/tools/) for the intended task. ### Change an existing session's location After a session starts, the menu is labeled **Execution location** and the toolbar can show its bound checkout. Changing it restarts the agent's provider context. If a run is active, RepoPrompt asks you to confirm stopping it; the in-flight request is not replayed automatically. An idle session can also lose some conversational continuity when its provider context restarts. Finish or stop the current task, review its changes, and decide which checkout should receive the next message. Read the confirmation before proceeding. Switching the visible workspace tab is not a substitute for changing a session's execution binding. Once the location is correct, select a [Workflow Template](https://repoprompt.com/docs/1.6.0/sessions/workflow-templates/) and describe the task. For a complete worktree task, follow [Create and Use a Worktree](https://repoprompt.com/docs/1.6.0/worktrees/create-and-use/), then [Review and Merge](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/). Changing this location does not merge changes between checkouts. --- ## Image Support (Sessions) Images give an agent visual evidence that is difficult to express in text: a clipped panel, a design mockup, an error dialog, or the exact arrangement you want to reproduce. Include a short explanation of what the agent should notice and what outcome you want. ### Add images to the next message Click the image-plus button near Send to open **Choose Images**, then select one or more files. You can also paste an image from the clipboard or drag image files into the message editor. RepoPrompt prepares supported image input and shows attachments above the editor. Image-plus attachment button beside the message editor Review the attachment previews before sending. Remove an image with its attachment removal control if it belongs to another task or contains information you do not intend to share. Attachments are staged for the next turn; they are not sent merely because you select or paste them. The available attachment actions depend on the current session and submission state. If an action is disabled during a pending submission or rewrite, finish or cancel that step before changing its attachments. Image support also depends on the provider and selected model; read a reported compatibility or input error rather than assuming every connected model accepts the same formats. ### Explain how to use the image A useful message identifies the relevant part and the requested change: “The Save button is clipped at the bottom of this screenshot. Fix the layout while keeping the form keyboard-accessible.” If you attach several images, describe their relationship, such as current behavior versus intended design. Images can show text, code, and instructions that belong to the material being analyzed. State your task in the message and identify which visual details matter. For documentation work, explain whether a screenshot is the current interface or an example from an older build. ### Images, selected files, and desktop interaction An image attachment is visual input for the message's execution provider. It is separate from the repository file selection in [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/). Selecting source files helps the agent connect the visual issue to implementation, but attaching a screenshot does not select those source files automatically. Re-prompt and automatic routing have narrower inputs: image attachments are not automatically forwarded as visual input to their draft-rewriting or decision requests. The execution provider receives the supported attachments with the submitted task. Review the image for private information before sending. To let an eligible session interact with desktop applications rather than analyze a static image, see [Computer Use](https://repoprompt.com/docs/1.6.0/sessions/computer-use/). --- ## Interviewer (Sessions) The **Interview** control is the question-bubble icon above the editor. Turn it on when your initial request needs a few decisions resolved before the agent starts. It is useful when you know the outcome you want but have not decided the scope, preferred approach, or tradeoffs. Interview control tooltip showing Interview off and Work begins immediately ### Enable before the first task Write your request, turn **Interview** on, and send. The control's tooltip distinguishes **Interview on: Asks questions before starting** from **Interview off: Work begins immediately**. When enabled for the first task, RepoPrompt asks the agent to interview you before beginning substantive work. The interview instructions call for one question at a time, normally with two to four concrete answer choices. The agent should adapt each question to your previous answer, ask one to three questions in total, and stop sooner when the task is clear. It should then summarize what it learned and proceed. Use the question card to select an answer or supply your own explanation. Give answers about the intended result and constraints: for example, whether a change should affect one screen or the entire application, or whether you want a proposal before implementation. ### Understand the scope Interview is a first-task instruction, consumed when used; it is not a requirement to interview you on every follow-up. Turning it on after the conversation already contains an assistant response does not retroactively restart the opening interview. You can always ask a follow-up such as “Before continuing, clarify the remaining decisions with me.” Interview guides model behavior, so the exact questions depend on the provider and task. It does not change the session's tool permissions or promise that the agent will pause before every later action. Approval requests remain governed by [Tools and permissions](https://repoprompt.com/docs/1.6.0/sessions/tools/). ### Combine it with a workflow Choose the [execution location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/), then a [Workflow Template](https://repoprompt.com/docs/1.6.0/sessions/workflow-templates/), and enable Interview if you want a short clarification step before that method begins. **Deep Plan** also has its own instructions for establishing how involved you want to be. Choose the combination that matches your task rather than assuming every template needs an interview. [Re-Prompter](https://repoprompt.com/docs/1.6.0/sessions/re-prompter/) serves a different stage: it helps rewrite the draft in your editor before the execution agent receives it. --- ## Message Editor (Sessions) The message editor is the **Send a message…** field at the bottom of a session. It combines the request you write with the workflow, context, model, and permissions selected around it. Check these surrounding controls before sending, especially when you have switched sessions. Agent Mode composer showing the message field and its toolbar and submission controls ### Write the outcome and constraints Describe the result you need, the relevant behavior, and how you will judge success. Include known files or components as starting points without assuming you must select every file the agent will need. Agents can search the repository and use [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/) to discover relevant code. For example: “Fix the session list so renaming a chat preserves its selection. Keep keyboard navigation working and explain the affected behavior.” Add scope limits, compatibility requirements, or review expectations in the message. A [Workflow Template](https://repoprompt.com/docs/1.6.0/sessions/workflow-templates/) supplies the approach around that task; it does not supply missing product requirements. ### Stage the message Choose the [execution location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/), then select a workflow card or the **Workflow** selector if needed. Use the file/context control to inspect selected files and receiving-model instructions. File mentions can add explicit file attachments when enabled; review the attachment strip rather than assuming a typed path was attached. The image-plus button opens **Choose Images**. You can also paste or drop supported images. Remove an attachment before submission if it should not accompany the next turn. See [Image Support](https://repoprompt.com/docs/1.6.0/sessions/image-support/) for the difference between attachments and repository context. ### Submit and follow up **Return** or the paper-plane button submits the message in the normal composer state. Use **Shift+Return** for a line break. With [Re-prompt](https://repoprompt.com/docs/1.6.0/sessions/re-prompter/) enabled, the first Send can instead rewrite the draft for review; inspect the visible state before sending again. A follow-up sent to a running session can steer its work. It is different from starting a fresh session, and it does not necessarily interrupt a tool action at the exact moment you type. For a question or approval already waiting in the transcript, use that interaction's response controls so the answer reaches the right pending request. ### Review the conversation Replies and tool cards appear above the editor. Expand a card for arguments, results, or a diff. Provider permissions and the **Auto Edit** setting determine whether a file change is applied automatically or needs a decision. Use the session's stop/cancel control when you intend to stop active work; an unsent draft does not stop the agent. Use [Session History](https://repoprompt.com/docs/1.6.0/sessions/session-history/) to return to earlier conversations or [Overseer](https://repoprompt.com/docs/1.6.0/sessions/overseer/) when coordinating several active sessions. --- ## Model and Effort (Sessions) The model selector below the editor chooses the provider and model for the session's work. The adjacent menu selects an available reasoning effort. This guide explains those controls; the shared [Models reference](https://repoprompt.com/docs/1.6.0/providers/models/) owns model availability, identifiers, aliases, effort, and service-tier concepts. Composer model and effort controls with a selected Codex model and Medium effort ### Select a connected model Open the provider/model menu and choose an available entry. Models come from connected runtimes and configured compatible backends, so the list can differ between installations. Connect a missing provider through [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/). The [Providers guide](https://repoprompt.com/docs/1.6.0/providers/overview/) compares the supported integrations in a compact format. An explicit selection establishes the intended provider and model. Read locks and disabled-state explanations when a choice cannot be changed: controls can be locked while an agent controls the session, and some provider settings are locked during an active run. A provider or backend change can require a fresh provider context, so review any restart behavior before switching during a task. ### Choose effort and speed deliberately Open the effort menu and select one of the choices returned for this model. Some connections display provider-specific parameter controls or omit effort when it is not available. See [Reasoning effort](https://repoprompt.com/docs/1.6.0/providers/models/#reasoning-effort) for the meaning of those choices. When a speed or Fast option is available, inspect its selected state separately from effort. [Speed and service tiers](https://repoprompt.com/docs/1.6.0/providers/models/#speed-and-service-tiers) explains the capability and billing distinctions. ### How automatic decisions interact With [Model Router](https://repoprompt.com/docs/1.6.0/sessions/model-router/) enabled for a new session, the composer can replace the ordinary picker with the routing-service label. Router chooses the model and initial effort for that task. Existing sessions retain their established targets. [Auto Effort](https://repoprompt.com/docs/1.6.0/sessions/auto-effort/) keeps an explicitly selected supported model and chooses effort before eligible turns. It does not change effort between tool calls in an active turn. If automatic decisions are unavailable, the manual selection or applicable default is used. Other features have their own model controls. See [Model roles](https://repoprompt.com/docs/1.6.0/providers/models/#model-roles) and the corresponding [Re-prompt](https://repoprompt.com/docs/1.6.0/sessions/re-prompter/), [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/), and [Oracle](https://repoprompt.com/docs/1.6.0/sessions/oracle/) guides. --- ## Model Router **Model Router** is the branching-arrow control above the message editor. Enable it when you want RepoPrompt to choose a suitable execution model for a new task using your connected providers, routing settings, and the task description. Routing chooses the model and then its initial reasoning effort. Composer with Model Router enabled and a Jev by TypeSafe routing label in place of the ordinary model selection ### Read the composer state An enabled control is highlighted, and the composer can show **Model Router · [service]** where the ordinary model choice would appear. In the screenshot the service is **Jev by TypeSafe**. Click the service label to open routing settings. If the service is unavailable, the control directs you to configuration. Configure and verify the decision service and connect an eligible execution provider before enabling routing. The decision service chooses among execution models; it is not itself the coding agent that edits your repository. Available candidates depend on provider connections, model support, and routing configuration. ### New tasks and existing sessions The Router switch is global and stays enabled across sessions until you turn it off. It applies to new primary sessions and eligible RepoPrompt-managed sub-agents. It does not replace an established session's model on every follow-up. Explicit model pins in agent launches remain respected. If routing fails or yields no valid choice, the task continues with the current selection or applicable role default. Local usage balancing can adjust a recommendation to a comparable eligible model. Paid Fast variants require separate eligibility settings; the router does not make those costs disappear. ### Review information sent for a decision Routing sends a short task excerpt, custom routing guidance, role references, and descriptions of candidate models and effort levels to the selected service. RepoPrompt attempts to mask sensitive text, but masking is best effort. Attached files, repository context, chat history, tool results, and execution-provider credentials are not automatically included. Sensitive information typed directly into the task or guidance can still be shared. The full task is then sent to the chosen execution agent. Review service privacy details and disable routing for tasks you do not want excerpted to that service. See [Routing settings](https://repoprompt.com/docs/1.6.0/settings/model-router/) for service verification, available models, usage balancing, Fast-tier eligibility, and guidance. [Auto Effort](https://repoprompt.com/docs/1.6.0/sessions/auto-effort/) makes a narrower decision for eligible turns on a model you selected. --- ## Oracle (Sessions) **Oracle** is the brain-shaped control above the message editor. It opens Oracle conversations associated with the current context so you can inspect the reasoning model's questions, plans, reviews, and answers. Use Oracle when the executing agent would benefit from a second perspective or a model with different strengths. For an introduction to its role and when to use it, read [What Is an Oracle?](https://repoprompt.com/docs/1.6.0/faq/what-is-an-oracle/). ### Execution agent and Oracle The execution agent continues to own the coding task: it searches, edits, runs tools, and responds to your instructions. Oracle is a consultation that receives its prepared context and returns analysis. Consulting Oracle does not automatically replace the model shown below the message editor or apply its suggested changes. Choose the primary Oracle and up to four additional Oracles in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). A grouped request runs those models independently and keeps their results separate in roster order. The control can display **Oracles · 2**, for example, when multiple Oracles are configured or represented in the current grouped consultation. A displayed count is not a count of coding agents editing your files. Composer toolbar showing Oracle access beside the selected-context control ### Open and review consultations Click **Oracle** to inspect the relevant conversation. Oracle consultations can be created by a workflow, a direct agent request, or a Context Builder analysis follow-up. The popover favors conversations associated with the current agent session so results remain connected to the task you are viewing. Read each model's result when a consultation has several lanes. They can disagree or focus on different risks. Bring the useful conclusions back into the coding task with a clear follow-up rather than assuming every suggestion should be implemented. Where offered, **Copy All** collects a grouped consultation's results for reuse. ### Supply useful context Oracle's answer depends on the context assembled for the consultation. Check selected files, relevant Code Maps, instructions, and any requested Git diff. For a review, identify which changes should be inspected; for a plan, state constraints and the intended outcome. [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/) can discover files first and then generate a plan, review, or answer using Oracle. Its discovery model is configured separately from the Oracle roster. External clients can use exposed [Oracle Model Presets](https://repoprompt.com/docs/1.6.0/settings/model-presets/) to select named consultation configurations. For tool-level send, continuation, model-selection, and export behavior, see [Oracle tools](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#oracle--model-tools). --- ## Overseer (Sessions) The oversight control sits between **Workflow** and **Interview** above the message editor. Open it to manage the current session's relationships with other Agent sessions, including sessions in other RepoPrompt windows. The screenshot shows the control's earlier branching-symbol appearance; newer builds use oversight role marks and counts. Overseer popover with Enable overseer mode and a Session ID field for linking an existing session ### Start with a loaded session Send a first message so the session exists and is loaded. A blank composer can display **Send a first message to start this session, then add sessions to oversee**. Overseer activation requires an eligible, user-owned top-level Agent session. When the session is unavailable or ineligible, the popover explains why its controls are disabled. **Enable overseer mode** lets the session create managed lanes without first linking an existing conversation. Enabling it grants no access to unrelated sessions. The activation applies to this session until it is rebound, changes ownership, or the app restarts. ### Add an existing session Copy the target's session ID from its sidebar controls, enter it under **Oversee a session**, or choose **Paste from Clipboard**. Check the preview and choose **Oversee session**. The confirmation explains what the overseer will be allowed to read and control. Choose **Retry** if a session has just become available and the candidate information needs refreshing. This relationship can allow the overseer to read status and conversations, send instructions, steer or stop work, answer questions and applicable one-time approval requests, compact context, and receive updates. Treat the confirmation as a delegation decision. ### Read and manage relationships The popover lists sessions this agent oversees and sessions overseeing it. Role marks and counts help distinguish the two directions. Open a linked session to inspect its work; **Unlink** removes the relationship without deleting the conversation. Automatic wake controls decide when updates can start follow-up work and therefore affect model usage. For the full feature, continue with [Overseer Mode Overview](https://repoprompt.com/docs/1.6.0/overseer/), [Lanes](https://repoprompt.com/docs/1.6.0/overseer/lanes/), [Linking Sessions](https://repoprompt.com/docs/1.6.0/overseer/linking-sessions/), and [Best Practices](https://repoprompt.com/docs/1.6.0/overseer/best-practices/). --- ## Sessions & Interface A session is a conversation with a coding agent, together with its execution location, selected context, tool activity, and results. Start a separate session for a separate task. Sessions can use different providers and models, but two sessions working in the same checkout still share the files in that checkout. Before your first message, make two deliberate choices: **where the work will happen** and **which workflow, if any, should structure the request**. These choices give the agent a place to work and a method to follow. ### 1. Choose the execution location Open **Work locally** above the message editor. Choose **Workspace checkout** to work directly in the open workspace, **New worktree** for a separate Git checkout, or one of the **Existing worktrees** to continue work there. Your initial worktree choice is applied when you first send a message. Composer with execution location, workflow, oversight, interview, rewriting, routing, computer use, Oracle, context, model, effort, tools, permissions, and image controls Use the workspace checkout for changes you want in the files already open. Prefer a separate worktree when several agents will edit the same repository, when you want to compare approaches, or when the current checkout contains unrelated work. Choosing a separate conversation alone does not isolate file changes. Read [Execution Location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/) before changing the location of an established session: that change can stop an active run and restart its provider context. ### 2. Wrap the message in a workflow template The **What are we building?** screen offers workflow cards. Select a card such as **Orchestrate**, **Review**, **Deep Plan**, or **ChatGPT Export**, then write your actual request. The arrows and page dots reveal more cards. Selecting a card prepares the workflow; it does not start the task. What are we building screen with Orchestrate, Review, Deep Plan, and ChatGPT Export workflow cards You can make the same choice from the lightning-bolt **Workflow** selector above the editor. Its catalog includes built-in and custom templates. A template wraps your message in instructions for how to approach it: for example, investigate and plan before implementing, or inspect changes and report review findings. Include your goal, constraints, and acceptance criteria in the message itself. The selected workflow applies to the submitted message and is cleared after submission. Select it again for another message that needs the same structure. You can also send a plain request with no template selected. See [Workflow Templates](https://repoprompt.com/docs/1.6.0/sessions/workflow-templates/) for the catalog and configuration controls. ### Send, watch, and guide Choose a connected provider and model below the editor, then an available reasoning effort. The screenshots show particular models and settings; your choices depend on your connected runtimes. **Tools** controls provider capabilities, and **Permissions** controls how tool requests are approved. Review both before giving the agent a task with significant file or shell work. Send with **Return** or the paper-plane button. The conversation shows replies, tool cards, file reads, edits, and requests for input. Expand a tool card to inspect what happened. Respond to live questions or approval requests in their cards. Provider permissions determine which actions require your approval; review changes in the transcript and repository even when edits were applied automatically. Continue in the same session when the next message depends on the conversation. Use [Session History](https://repoprompt.com/docs/1.6.0/sessions/session-history/) to find earlier work or start another session for an independent task. ### Find the control you need | Goal | Guide | | --- | --- | | Ask questions before work begins | [Interviewer](https://repoprompt.com/docs/1.6.0/sessions/interviewer/) | | Improve a draft before sending it | [Re-Prompter](https://repoprompt.com/docs/1.6.0/sessions/re-prompter/) | | Let a service choose a new task's model | [Model Router](https://repoprompt.com/docs/1.6.0/sessions/model-router/) | | Let a service choose effort for eligible turns | [Auto Effort](https://repoprompt.com/docs/1.6.0/sessions/auto-effort/) | | Let a supported Codex session interact with desktop apps | [Computer Use](https://repoprompt.com/docs/1.6.0/sessions/computer-use/) | | Write messages, attach context, and send follow-ups | [Message Editor](https://repoprompt.com/docs/1.6.0/sessions/message-editor/) | | Pick the execution model and reasoning budget | [Model and Effort](https://repoprompt.com/docs/1.6.0/sessions/model-and-effort/) | | Configure tools and approvals | [Tools](https://repoprompt.com/docs/1.6.0/sessions/tools/) | | Respond to a tool decision, edit review, or hook request | [Approvals and Paused Sessions](https://repoprompt.com/docs/1.6.0/sessions/approvals/) | | Consult other models or assemble repository context | [Oracle](https://repoprompt.com/docs/1.6.0/sessions/oracle/) and [Context Builder](https://repoprompt.com/docs/1.6.0/sessions/context-builder/) | | Prepare a package for an external model | [Prepare and Copy Context](https://repoprompt.com/docs/1.6.0/sessions/context-composer/) | | Integrate completed worktree changes | [Review and Merge](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/) | | Coordinate multiple sessions | [Overseer](https://repoprompt.com/docs/1.6.0/sessions/overseer/) and [Overseer Mode](https://repoprompt.com/docs/1.6.0/overseer/) | | Provide a screenshot or mockup | [Image Support](https://repoprompt.com/docs/1.6.0/sessions/image-support/) | --- ## Re-Prompter (Sessions) **Re-prompt** is the wand control above the message editor. It asks a separate model to improve your draft before you send it to the session's execution agent. Use it to make a rough request clearer, organize constraints, or turn an informal description into a more useful task brief. Enable Re-prompt confirmation describing shared information, provider billing, review behavior, and keyboard controls ### Rewrite, review, then send Enable Re-prompt and read its first-use disclosure. Write the request and press **Return** or click **Send**. In the normal review mode, this first action rewrites the text in the composer. Review and edit the visible draft, then press Return or Send again to submit it. You remain in control of the draft. Typing stops an in-progress rewrite. **Escape** restores the original for your next Send. **⌘Return** asks for another rewrite, and **⌘⇧O** sends the original immediately. Use these controls according to the current composer state rather than repeatedly pressing Send while a rewrite is still arriving. The rewriter can offer an optional clarification question. Answering can produce another revision. You can also continue with the visible draft without answering. This clarification happens before submission; [Interviewer](https://repoprompt.com/docs/1.6.0/sessions/interviewer/) asks the execution agent to clarify the task after submission. ### Choose a model and mode Open the control's context menu to select an available Re-prompt model, restore its automatic default, change **Mode**, or toggle **Include recent chat context**. **Agent Models Settings** opens the related configuration. If no usable model is connected, the control offers **Choose model** instead of silently selecting an unavailable provider. **Send automatically** mode dispatches completed rewrites unless a clarification question or slash-leading text needs review. Use review mode when you want to inspect every rewritten request. Your Re-prompt model is separate from the model that ultimately performs the task. ### Know what is shared The rewriting provider receives your message, rewriting guidance, workspace root names and selected paths, and recent chat excerpts when enabled. File contents, attachments, Git output, and tool results are not included in that rewriting request. The screenshot's model name is an example; provider billing and retention apply to the configured route. Paths, names, excerpts, and anything you type can still be sensitive. Read the disclosure when changing providers. If [Model Router](https://repoprompt.com/docs/1.6.0/sessions/model-router/) or [Auto Effort](https://repoprompt.com/docs/1.6.0/sessions/auto-effort/) is enabled, the resulting task can also be evaluated by its configured decision service before the execution agent starts. --- ## Session History (Sessions) Session history lets you return to a task with its conversation and tool activity intact. Use it to find a previous investigation, continue an implementation, or compare what several agents found. A session's history describes its work; the files on disk can have changed since the last message. ### Find a conversation Open the Agent sessions sidebar to browse sessions in the current workspace. Rows identify the conversation and its activity; parent and child sessions can be grouped together. Select a row to open its transcript. RepoPrompt may show **Restoring conversation…** while it loads saved content. If restoration fails, use the displayed **Retry** action rather than starting a replacement task without checking the original. The **Agent Session Switcher** jumps among sessions in the focused window. **Search all Agent sessions** searches active or recent conversations across windows. Their default shortcuts are **⌘K** and **⇧⌘K**; the sessions sidebar defaults to **⌥⌘B**. All are configurable in [Keyboard Shortcuts](https://repoprompt.com/docs/1.6.0/settings/keyboard-shortcuts/). Give long-running conversations descriptive names using **Rename chat**. A name such as “Checkout cancellation review” is easier to recognize than a generic request. Oversight marks and their tooltips identify sessions that oversee others or are overseen; they do not replace the run status. ### Resume and inspect the work Select the session, read its latest result, and check its [execution location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/) before sending a follow-up. The provider, model, permissions, and worktree can differ from the session you last viewed. A stopped or completed task does not automatically resume merely because you open its transcript. Expand tool cards to inspect file reads, searches, command results, edits, or Oracle consultations. This is useful when a result refers to a file or decision you want to verify. Some saved history loads in bounded portions; use **Show more** where offered. For a fresh provider context or another agent, use **Handoff** where available. Review the destination provider and model and the prepared handoff context. A handoff is a way to carry useful task information forward; it does not make every detail of a long conversation fit into the destination's context window. ### Archive and delete deliberately Archive conversations you want out of the active list while retaining their saved history. The **Archived Sessions** section lets you revisit archived work. Read bulk-action counts before confirming an operation. **Clear archived sessions** and **Delete chats** permanently remove saved conversations and can also remove related sub-agent chats, as stated in the confirmation. To disconnect coordination without deleting a conversation, use **Unlink** in [Overseer controls](https://repoprompt.com/docs/1.6.0/overseer/linking-sessions/). To find older work through an agent, the read-only [history tool](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#history) can search saved sessions across workspaces. --- ## Tools (Sessions) The **Tools** menu below the editor controls capabilities offered to the selected execution provider. It is useful when you want to constrain shell access, adjust provider features, or decide which configured MCP servers the session may use. The available switches depend on the provider. Codex Tools popover showing Bash, Search, Goals, Reasoning Summaries, Local Memories, and required RepoPromptCE MCP access ### Codex controls in the screenshot | Control | Effect | | --- | --- | | **Bash** | Permits Codex shell commands under the selected permission level. | | **Search** | Permits Codex's built-in search capability. RepoPrompt's own repository tools have separate MCP availability controls. | | **Goals** | Enables Codex goal support for continuing tasks. | | **Reasoning Summaries** | Controls whether Codex supplies reasoning summaries in Agent Mode; it does not select reasoning effort. | | **Local Memories** | Allows Codex to generate and reuse local memories across chats. Background or startup generation can consume quota; a new or restarted session may be needed. | | **MCP Servers** | Enables individual servers from RepoPrompt's isolated Codex configuration. **RepoPromptCE** is required and cannot be disabled here. | Tool settings are locked during an active Codex run. If a setting is unavailable, wait for the turn to finish or stop it deliberately before changing the configuration. Other providers expose different controls; [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/) describes their runtime options. ### Choose permission behavior Open **Permissions** beside Tools to inspect the current provider's approval mode. For Codex, the pictured choices are **Read Only**, **Default**, **Auto Review**, and **Full Access**. Auto Review evaluates tool requests automatically before asking you. Full Access removes the normal provider sandbox restriction and per-request tool approval prompts; separate RepoPrompt edit reviews, hook-trust decisions, and worktree merge reviews can still apply. Permissions popover with Codex sandbox levels and the separate Auto Edit switch **Auto Edit** applies file edits without a separate edit approval. It is distinct from a tool being available and from the provider's sandbox or approval policy. Read the current labels and explanation instead of assuming an enabled Tools switch approves every operation. For the actual decision cards, including rejection reasons and remembered approvals, see [Approvals and Paused Sessions](https://repoprompt.com/docs/1.6.0/sessions/approvals/). ### RepoPrompt tools and sub-agents [Settings → MCP Server → Tools](https://repoprompt.com/docs/1.6.0/settings/tools/) controls which RepoPrompt tools are advertised. Window access, individual tool availability, and operation-specific checks still apply. Consult the [MCP Tools Reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/) for those tools' behavior. Sub-agents launched through MCP have a separate policy under [Agent Permissions → Sub-Agents](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/#sub-agents). Changing the current direct session's permission level does not by itself establish the policy for every child or overseen session. --- ## Workflow Templates (Sessions) A workflow template gives the agent a method for handling your request. You provide the task; the template supplies instructions about research, planning, delegation, implementation, or review. Choose a workflow when you want that structure without writing the full procedure yourself. ### Choose from the welcome screen On an empty session, select a card under **What are we building?**. The selected card prepares the next message and focuses the editor. Selecting it again clears that choice. Use the arrows or page dots to browse more cards; the cards reflect your visible workflows and featured choices. Welcome workflow cards for Orchestrate, Review, Deep Plan, and ChatGPT Export Another workflow page with Optimize, Plan and Build, Refactor, and Investigate ### Choose from the Workflow selector Open the lightning-bolt **Workflow** control above the editor. This selector offers the workflow catalog while you compose, including custom workflows you have added. The name and short description help you choose a method before sending. **Configure…** and the welcome screen's **Edit** control open workflow configuration; the refresh control reloads the available definitions. Workflow selector showing built-in templates and Configure | Template | What it asks the agent to do | | --- | --- | | **Orchestrate** | Break a complex request into tasks, delegate work, and check the results. | | **Deep Plan** | Research the code, establish how involved you want to be, and produce a detailed implementation plan. | | **Optimize** | Establish measurements, instrument the relevant behavior, and iterate using evidence. | | **Plan & Build** | Research the request, plan the change, and implement it step by step. | | **Review** | Examine code for bugs, regressions, risks, and missed edge cases. | | **Refactor** | Improve code structure while preserving its intended behavior. | | **Investigate** | Research a bug, crash, security concern, or question and report supporting evidence. | | **ChatGPT Export** | Assemble code and context into a prompt you can take to ChatGPT. | The list depends on visibility settings; a hidden built-in template remains configurable. See [Agent Workflows settings](https://repoprompt.com/docs/1.6.0/settings/agent-workflows/) to show, hide, feature, reorder, or clone templates and create custom Markdown workflows. ### Send the request through the template Select the template, then write a specific request: “Review the checkout changes for cancellation bugs; focus on session cleanup” is more useful than “Review.” Choose the [execution location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/), check the model and permissions, and send. RepoPrompt wraps the message in the selected template and clears the selection after accepting the submission. Select another template when a later message needs a different method. Templates are instructions to an agent, so the actual work depends on the task, connected models, tools, and permissions. Selecting **Orchestrate** does not itself start other sessions, and selecting **Review** does not grant additional repository access. These Agent Mode templates are configured separately from [Copy/Chat Workflow Presets](https://repoprompt.com/docs/1.6.0/settings/workflow-presets/) and external [Skills & Slash Commands](https://repoprompt.com/docs/1.6.0/agent-mode/skills/). For longer explanations of built-in procedures, see [Agent Mode Workflow Commands](https://repoprompt.com/docs/1.6.0/agent-mode/workflows/). --- ## Agent Models (Agent-mode) Agent Models settings with workspace scope, recommendations, Oracle roster, Context Builder, and sub-agent role defaults Choose the Oracle analysis model, the Context Builder agent and model, and model defaults for sub-agent roles such as Pair, Design, Explore, and Engineer. Open **Settings → Agent Mode → Agent Models**. This page chooses the models used by Oracle, Context Builder, and MCP-launched agent roles. The screenshots on this page are historical captures; the model names and connected providers shown are examples, not fixed defaults. Use the [Models reference](https://repoprompt.com/docs/1.6.0/providers/models/#model-roles) for the meaning of these model roles and shared selection concepts, and the [provider directory](https://repoprompt.com/docs/1.6.0/providers/overview/) for connection requirements. The sections below explain settings scope and controls. ### Global settings and workspace overrides Agent Models scope selector and Copy to Workspace control With a workspace open, choose where edits apply: - **Use global settings**: this workspace inherits the global Agent Models profile, and changes below edit that profile. - **Use workspace overrides**: changes below apply to this workspace's profile. **Copy to Workspace** copies the current global profile and switches this workspace to overrides. When editing overrides, the corresponding **Copy to Global** action overwrites the global profile after confirmation, affecting other workspaces that inherit it. The scope chips at the top show the active profile and workspace. ### Recommended setup Recommended setup available banner and Apply Recommended Setup button Recommendations come from the same engine as the setup wizard. **Apply Recommended Setup** applies the recommended configuration to the scope you are editing. Individual rows can also offer **Apply** when their current choice differs. If everything matches, the page reports that the models are up to date. ### Oracle Models Primary Oracle and additional Oracle model pickers with Add Oracle and removal controls Choose a primary Oracle and up to **four additional models**. **Add Oracle** adds another entry; the minus control removes an additional entry. Grouped requests run each model independently and retain separate results in roster order. Newer builds also expose **Reconciliation guidance** for the calling agent when multiple answers return. The calling agent reconciles those answers; this does not launch another synthesis model. Saved guidance affects future requests, and blank guidance restores the default. For named configurations exposed to MCP clients, see [Oracle Model Presets](https://repoprompt.com/docs/1.6.0/settings/model-presets/). ### Context Builder Agent Context Builder Agent provider and model menu Choose the CLI agent and model that discover files and build context for Oracle, plans, and reviews. If no suitable agent is connected, use **Connect in CLI Providers** first. Token budgets and prompt-enhancement behavior belong on [Context Builder](https://repoprompt.com/docs/1.6.0/settings/context-builder/). ### Sub-Agent Role Defaults MCP model discovery filter and Explore, Engineer, Pair, and Design role mappings These mappings supply models when an MCP client launches an agent using a role label: | Role | Intended work | | --- | --- | | **Explore** | Fast, read-only exploration and codebase mapping. | | **Engineer** | Balanced engineering and implementation work. | | **Pair** | Interactive pair programming with highest-tier models (default when `model_id` is omitted in `agent_run op="start"`). | | **Design** | Architecture, design critique, and creative problem solving (produces Markdown design/review documents under `docs/`). | Choose the provider/model from each row's menu. **Reset All to Recommended** appears when role defaults have overrides. **Hide non-role models from MCP agents** limits model discovery: `agent_manage` still exposes role labels and their mappings but omits the extra per-agent model catalog. Explicit compound model identifiers remain accepted. This is not an access-control boundary. [Model Router](https://repoprompt.com/docs/1.6.0/settings/model-router/) can separately route eligible role-based starts. ### Advanced: synchronize built-in chat Advanced option to keep Built-in Chat Model synced with Oracle Model **Keep Built-in Chat Model synced with Oracle Model** makes choosing an Oracle update the built-in chat model to match. Turn it off to choose the chat model independently. This does not make the chat model the same thing as a sub-agent role mapping. ### Related settings Oracle Model Presets settings link Use [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/) for connections, [Agent Permissions](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/) for execution permissions, and [Oracle Model Presets](https://repoprompt.com/docs/1.6.0/settings/model-presets/) for named MCP Oracle configurations. --- ## Agent Permissions (Agent-mode) Agent Permissions Direct Agents tab showing provider summaries, disconnected providers, and related settings Configure permissions for agents launched directly from RepoPrompt and the separate policy for sub-agents launched through MCP. Sub-agent policy can use Safe Managed behavior, inherit direct-agent settings, or use custom settings. Open **Settings → Agent Mode → Agent Permissions**. The page has two tabs with separate responsibilities: **Direct Agents** and **Sub-Agents**. Model selection remains in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). Direct Agents and Sub-Agents tab selector ### Direct Agents This tab configures provider-native permissions for agents you launch directly from RepoPrompt. Expand a connected provider row to change its permission level and, where supported, **Tools & Runtime Options**. Connection indicators and summary values describe your current setup. A green indicator means the provider is available; it does not mean it has unrestricted access. #### Codex CLI Codex CLI direct-agent sandbox and third-party MCP summary The row summarizes the sandbox and third-party MCP policy. Expand it for Codex permission levels and runtime tool controls. Third-party MCP servers are controlled individually and are off by default; that control is separate from the RepoPrompt MCP tool list. #### Claude Code Claude Code direct-agent permission mode and third-party MCP summary The summary shows the selected Claude permission mode and MCP scope. Expand it to configure Claude's provider permissions and tool/runtime settings. **Auto-approve Edits** and **RepoPrompt only** are the selections pictured, not a recommendation to enable broader access. #### OpenCode and Google Antigravity OpenCode direct-agent ACP session mode and MCP support summary Google Antigravity direct-agent ACP mode and MCP management summary These rows expose each provider's ACP session mode. The provider's capabilities determine which permission and tool controls are available. The screenshot reports no third-party MCP support for OpenCode and provider-managed MCP for Antigravity; do not assume the same MCP controls apply to both. #### Disconnected providers Disconnected Cursor CLI, Grok Build, and Devin CLI rows and Open CLI Providers button Unavailable providers are listed under **Not connected** and cannot be expanded for editing. **Open CLI Providers** opens connection setup. A provider moves into the connected list when it becomes available. ### Sub-Agents
View the complete Sub-Agents tab Agent Permissions Sub-Agents tab showing policy selection, Safe Managed preview, effective profiles, and related settings
Sub-agent sandbox policy selector with Safe Managed, Inherit Provider, and Custom This policy applies when another agent launches a sub-agent through MCP: | Policy | Behavior | | --- | --- | | **Safe Managed** | Applies RepoPrompt's managed provider profiles instead of the direct-agent settings. | | **Inherit Provider** | Uses the direct-agent provider settings, including permissive modes you enabled there. | | **Custom** | Uses independent per-provider sub-agent permission levels. | Custom mode exposes **Per-provider sub-agent modes**. These affect future sub-agent launches without changing Direct Agents settings. Inherit Provider can pass through Full Access; review direct-agent settings before choosing it. #### Preview Safe Managed profile Expanded Safe Managed policy explanation in the captured build The preview explains the policy and shows an effective profile for each available provider. :::note[The captured policy differs from the current source] The screenshot says shell tools are disabled for both Claude and Codex. The current implementation disables Claude Bash but **enables Codex Bash**, using Codex's managed Auto Review sandbox/approval profile. It still forces Claude to strict MCP and suppresses user-enabled third-party MCP servers for Codex. Current source also notes a Grok Build exception: MCP launches use its Default mode, and its own rules, including inherited Claude Code permission rules, can allow requests without asking RepoPrompt. Safe Managed does not guarantee an approval prompt for every provider action. ::: #### Effective per-provider profile Safe Managed profiles for connected providers and unavailable-provider indicators Read these summaries for the active build and connected providers. They show the resulting sandbox or permission mode and third-party MCP handling. The rows are a preview of policy, not a second set of editable Direct Agents settings. ### Related settings and storage Links to CLI Providers, Workspace Approvals, MCP Tools, Agent Models, and Agent Mode Overview - [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/) configures connections and other runtime options. - [Workspace Approvals](https://repoprompt.com/docs/1.6.0/settings/workspace-approvals/) controls requests that change RepoPrompt workspace records. - [MCP Tools](https://repoprompt.com/docs/1.6.0/settings/tools/) controls tool availability. - [Agent Mode Overview](https://repoprompt.com/docs/1.6.0/settings/overview/) summarizes the wider setup. Both tabs share secure-permission storage diagnostics. If a degraded-storage banner appears, check it before assuming a permission change was saved; failed writes can return to the effective stored value. --- ## Agent Workflows (Agent-mode) Agent Workflows settings with cleanup guidance, featured workflows, built-in visibility, and custom workflow controls Manage the built-in workflows shown in Agent Mode, featured workflows, custom Markdown workflows, and cleanup guidance included with workflows. Open **Settings → Agent Mode → Agent Workflows**. These are Agent Mode prompt templates, separate from [Copy/Chat Workflow Presets](https://repoprompt.com/docs/1.6.0/settings/workflow-presets/). Select a workflow in Agent Mode before sending a task. ### Prompt Behavior Include Session Cleanup Guidance switch **Include Session Cleanup Guidance** controls housekeeping instructions appended to built-in workflow templates, reminding the coding agent to dismiss completed sessions. Turn it off if that text conflicts with your session-management process. It does not change custom workflow templates or separately installed external workflow instructions, and it does not immediately dismiss sessions itself. ### Featured Workflows Featured workflow list with Add Featured Workflow, ordering arrows, and Remove Up to **four** workflows appear first in Agent Mode. **Add Featured Workflow** chooses from eligible workflows; it is disabled when the list is full or there are no more available choices. Use the up and down arrows to reorder this list. **Remove** removes a workflow from the featured list without deleting the workflow. The full visible catalog remains available in the workflow picker. ### Built-in Workflows Built-in workflow rows with Visible, Feature, and Clone controls The built-in catalog includes: | Workflow | Purpose | | --- | --- | | **Orchestrate** | Break work into smaller tasks, delegate, and check results. | | **Deep Plan** | Research the code and produce an implementation plan. | | **Optimize** | Measure, add metrics, and iterate on improvements. | | **Plan & Build** | Plan and implement a change step by step. | | **Review** | Look for bugs, regressions, risks, and missed cases. | | **Refactor** | Improve structure while preserving behavior. | | **Investigate** | Investigate problems or research questions and report evidence. | | **ChatGPT Export** | Prepare code and context for a prompt to use in ChatGPT. | **Visible** shows or hides a built-in in the picker. Hiding it also removes it from Featured Workflows. **Feature** adds a visible workflow to the featured list, subject to the four-item limit. **Clone** creates an editable custom Markdown copy; it does not modify the shipped template. ### Custom Workflows Custom Workflows section with New, Reload, and Open Folder controls Choose **New**, enter a name, and select **Create** to create a Markdown workflow. Alternatively, clone a built-in and edit the resulting file. **Open Folder** opens the Workflows folder. You can add `.md` files there directly; **Reload** refreshes the catalog after external changes. Files can include optional frontmatter for a name, icon, accent color, tooltip, or description; otherwise the filename supplies the display name. Custom rows provide their own management actions. Deleting a custom workflow asks for confirmation and removes its file from the Workflows folder; it cannot be undone from RepoPrompt. --- ## CLI Providers (Agent-mode) Full CLI Providers settings pane showing the setup banner, all provider rows, and expanded custom backend controls Connect coding-agent runtimes and configure their authentication, permissions, tools, and compatible backends. Open **Settings → Agent Mode → CLI Providers**. Expand a provider’s row to see its available controls. The information button opens the provider’s website or documentation. Controls change with runtime availability and connection state. Screenshots illustrate the controls; the selections shown are examples rather than recommended defaults. :::note[Historical Screenshot Note] The overview screenshot (`cli-providers.png`) is a historical capture that may not reflect the expanded details or latest layout for newer provider integrations such as **Grok Build** and **OpenCode CLI**. Refer to the dedicated [OpenCode CLI](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#opencode-cli) and [Grok Build](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#grok-build) sections below for complete setup, authentication, and permission controls. ::: ### Connection and setup controls **Connect** checks whether RepoPrompt can use a provider. For providers with an established connection, **Test Connection** checks it again. Errors appear in the provider card or a result dialog. Where available, **Save Trace to Downloads** exports a diagnostic trace after a failed test. Status badges distinguish connection or installation availability from backend configuration. Compatible backends may be **Off**, need an **API key**, or be **Ready**; use **Test Backend** to check the configured route rather than treating readiness as a successful request. The **Check Now** banner opens setup recommendations when the app has connected CLI providers. It is separate from the individual connection tests. :::note[Direct agents and sub-agents] The inline **Permissions** or **Permissions & Runtime** controls apply to agents launched directly from RepoPrompt. **Open Agent Permissions** takes you to [Agent Permissions](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/), where MCP-launched sub-agent policy is configured separately. ::: ### Plan usage The current source places **Plan usage** controls inside the connected Codex CLI and Claude Code CLI cards. Usage-source setup is separate from connecting the coding runtime. The **Show usage limits when available** preference in [Agent Mode Overview](https://repoprompt.com/docs/1.6.0/settings/overview/) controls visibility; the provider's source must also be enabled or connected before readings are available. Use **Refresh** to request an updated reading. These controls report account usage; [Usage balancing](https://repoprompt.com/docs/1.6.0/settings/model-router/#usage-balancing) separately controls whether it influences model selection. ### Codex CLI Provider reference: [Codex CLI](https://repoprompt.com/docs/1.6.0/providers/codex-cli/). Codex CLI settings panel with runtime, sign-in, permissions, tools, optional features, and MCP server controls; account value removed RepoPrompt uses a managed Codex runtime and a managed sign-in separate from your ordinary `~/.codex` sign-in. #### Runtime and sign-in - **Included with RepoPrompt** shows the bundled runtime’s version and availability. The active-runtime summary identifies what this app launch is using. - Under **Advanced**, open the runtime menu and select a detected executable, or choose **Choose…** to select a custom Codex executable. RepoPrompt checks its version and reports availability or compatibility problems. - In the same runtime menu, select **Included Codex [version]** to switch the pending choice back to the bundled runtime. - **Connect** checks the selected runtime’s connection. When sign-in is needed, use **Login with ChatGPT** or **Use device code instead**. The device-code flow provides **Copy code** and **Open verification page**; keep the panel open while completing the browser step. - After authentication, the account summary shows account, plan, and authentication information. **Test Connection** checks the integration again. - **Sign Out** requires confirmation to stop Codex sessions and sign out of the managed account. :::note[Runtime changes require relaunch] Runtime selection takes effect on the next RepoPrompt launch, when the model list is refreshed. Saved model choices are preserved. Custom executables are not managed or verified by RepoPrompt and may be incompatible with its integration; the version check does not guarantee full compatibility. ::: #### Permission Level - **Read Only** uses a read-only sandbox with approvals requested when needed. - **Default** allows workspace writes and asks you for approvals when needed. - **Auto Review** allows workspace writes and uses automatic review of tool requests before asking you. - **Full Access** removes the sandbox restriction and runs without approval prompts. #### Core tools and runtime features Each switch enables or disables the named capability: - **Bash** permits Codex shell commands within the selected permission level. - **Search** permits built-in project search while Codex works. - **Goals** enables Codex goal support for tasks that continue between turns. - **Reasoning Summaries** shows Codex reasoning summaries in Agent Mode. It does not change model reasoning effort or Chat/Oracle behavior. - **Local Memories** permits Codex to generate and reuse local memories across Agent Mode chats. Memories are stored under the runtime’s Codex home. Generation can perform background or startup model work and consume Codex quota; applying the change may require a new or restarted session. #### Optional Codex Features - **Apps** permits use of connected apps. - **Plugins** permits loading installed plugins. - **MCP Elicitation** permits MCP servers to request additional input during a run. - **Tool Suggestions** permits suggestions to install or enable apps and plugins. Under **MCP servers**, toggle the configured servers that Codex may use. **RepoPromptCE** is required for the integration and cannot be disabled here. This list is read from RepoPrompt’s isolated Codex configuration. ### Claude Code CLI Provider reference: [Claude Code CLI](https://repoprompt.com/docs/1.6.0/providers/claude-code-cli/). Claude Code CLI settings panel with connection buttons, permission level, tool switches, and Advanced disclosure Claude Code uses the installed `claude` command and its login for Anthropic models. Complete its terminal login if necessary, then select **Connect**: ```sh claude login ``` **Test Connection** rechecks access. **Sign Out** clears RepoPrompt’s recorded Claude connection state; it is not a replacement for logging out of the standalone CLI. #### Permission Level - **Require Approval** asks before running tools. - **Auto-approve Edits** automatically approves file edits and common filesystem commands. - **Auto (Preview)** approves tool calls that pass background safety checks. The provider treats this as a preview feature. - **Full Access** runs tools without approval prompts. #### Claude Tools - **Bash** enables or disables Claude’s shell tool. - **RepoPrompt Only (Strict MCP)** restricts the session to RepoPrompt’s MCP server when enabled. When disabled, MCP servers from the Claude configuration may also be loaded. - **Lazy Tool Loading** lets Claude search for tools as needed, reducing context use but adding discovery latency. With it disabled, tools are preloaded into context. Changes to Claude tool settings apply to the next Claude turn. #### Advanced: Sys Prompt Packaging Expand **Advanced** inside the Claude Code CLI card to reveal **Sys Prompt Packaging**. This menu controls where RepoPrompt places its Agent Mode instructions and whether Claude Code keeps its native system prompt. An explanation below the menu updates to describe the selected mode: - **User Message (Keep Native)** puts RepoPrompt instructions in the user message and retains Claude Code’s native system prompt. - **User Message (No Native)** puts RepoPrompt instructions in the user message and removes the native system prompt. - **Replace System Prompt** uses RepoPrompt instructions in place of Claude Code’s native system prompt. The choice is saved when you select it; there is no separate Save button. With no saved preference or legacy override, RepoPrompt uses **Replace System Prompt**. This setting controls instruction delivery, while **Permission Level** and **Claude Tools** control tool access. ### OpenCode CLI Provider reference: [OpenCode CLI](https://repoprompt.com/docs/1.6.0/providers/opencode-cli/). OpenCode CLI panel with connection test, sign-out button, and ACP session mode Authenticate the installed OpenCode CLI, then select **Connect**: ```sh opencode auth login ``` - **Test Connection** rechecks the integration. A summary reports discovered models; discovery can refresh in the background. - **Sign Out** clears the connection and cached model availability in RepoPrompt. Manage the standalone CLI’s credentials through OpenCode. - **ACP Session Mode → Default** asks before tools that need approval. - **ACP Session Mode → Full Access** runs available tools without approval prompts. Interactive Agent Mode uses OpenCode’s Agent Client Protocol (ACP) runtime. Headless OpenCode runs use a managed mode without native tools. ### Cursor CLI Provider reference: [Cursor CLI](https://repoprompt.com/docs/1.6.0/providers/cursor-cli/). Collapsed Cursor CLI provider card with its expansion control **Connect** checks the installed Cursor runtime. Complete Cursor login when prompted, or provide the credentials supported by that runtime, such as `CURSOR_API_KEY` or `CURSOR_AUTH_TOKEN`. - **Test Connection** rechecks access. - **Refresh Models** requests an updated list from the runtime. - **Sign Out** disconnects Cursor in RepoPrompt and clears its cached model availability. - **ACP Auto-Approve → Default** asks before tools requiring approval. - **ACP Auto-Approve → Full Access** makes RepoPrompt automatically approve Cursor ACP tool-permission requests. RepoPrompt supplies its MCP integration through the ACP session. The provider’s **Auto** model option lets Cursor choose the model. ### Grok Build Provider reference: [Grok Build](https://repoprompt.com/docs/1.6.0/providers/grok-build/). Collapsed Grok Build provider card with its expansion control **Connect** checks the installed Grok runtime. Authenticate with `grok login` or configure a Grok API key in API Providers. ```sh grok login ``` - **Test Connection** rechecks access and reports discovered models. - **Sign Out** disconnects Grok Build in RepoPrompt and clears cached model availability. - **Always-Approve Launch → Default** leaves Grok’s approval prompts enabled. - **Always-Approve Launch → Full Access** launches Grok with `--always-approve`, allowing its shell and editing tools to run without per-request confirmation. The launch setting applies to newly started Grok processes. ### Google Antigravity Provider reference: [Google Antigravity](https://repoprompt.com/docs/1.6.0/providers/google-antigravity/). Google Antigravity panel with Update Runtime and Test Connection buttons - **Install Runtime** installs RepoPrompt’s managed Antigravity ACP runtime. - **Update Runtime** updates an installed runtime. - **Test Connection** checks runtime support and refreshes model discovery. It is available after installation. Google authentication is requested through ACP when needed. The card’s availability indicator reflects runtime installation; it does not by itself establish that Google login is complete or that selectable models were returned. This card does not include its own sign-out or inline permission picker. ### Devin CLI Provider reference: [Devin CLI](https://repoprompt.com/docs/1.6.0/providers/devin-cli/). Collapsed Devin CLI provider card with its expansion control Install and authenticate Devin so the `devin acp` runtime is available. Devin manages its own authentication and internal tools. The card’s availability indicator reflects whether the runtime is installed. **Refresh Models** requests the model list. **Permission Mode** controls newly started Devin processes: - **Provider Default** passes no permission flag and uses Devin’s own configured default. - **Normal** automatically approves read-only tools and asks before actions requiring approval (`auto`). - **Accept Edits** also automatically accepts workspace edits (`accept-edits`). - **Smart** additionally runs actions judged safe by a fast model (`smart`). - **Full Approval** runs tools without approval prompts (`dangerous`). This integration does not offer Devin’s autonomous mode. Use Devin’s own authentication tools to manage its login. ### Claude Code–Compatible Backends These backends reuse the installed `claude` executable with their own endpoint and credentials. They do not require an Anthropic Claude account login. The prerequisite row explains whether the Claude executable is available and offers a connection or installation action when needed. **Test Backend** sends a minimal message using the same backend environment overrides as Agent Mode. Enable and configure the backend, save a credential, and make sure the Claude executable is available before testing. The result appears in the card. Saving display, endpoint, authentication-mode, or model-mapping changes updates the backend configuration; credential fields use their separate **Save** or **Change** action. #### CC Zai Provider reference: [CC Zai](https://repoprompt.com/docs/1.6.0/providers/cc-zai/). CC Zai backend panel with credential controls, model-slot mappings, backend test, and Advanced disclosure; saved key field cleared CC Zai routes Claude Code through Z.ai’s Anthropic-compatible endpoint. - **Z.ai API Key** accepts the backend credential. **Save** or **Change** stores it; **Delete** removes it. - **Claude slot → Backend model ID** maps the **Haiku**, **Sonnet**, and **Opus** slots to backend model identifiers. Fill all three slots. RepoPrompt passes the selected slot to Claude and supplies the mappings through environment variables. - **Reset to GLM defaults** restores the backend preset, including its standard slot mappings. - **View Z.ai plans** opens the provider’s coding-plan information. :::note[Shared Z.ai credential] This field uses the same saved secret as Z.AI in [API Providers](https://repoprompt.com/docs/1.6.0/settings/api-providers/). Changing or deleting it here also changes that API-provider credential. ::: ##### Advanced Expand **Advanced** inside the CC Zai card to edit the preset’s connection settings: - **Display name** changes the backend’s label in RepoPrompt, including its card title. A blank name falls back to **CC Zai**. - **Base URL** sets the Anthropic-compatible endpoint. The preset is `https://api.z.ai/api/anthropic`. The address must include an `http` or `https` scheme and a host to be valid. - **Auth header** chooses how the saved credential is supplied to Claude Code: **ANTHROPIC_API_KEY** or **ANTHROPIC_AUTH_TOKEN**. CC Zai defaults to **ANTHROPIC_AUTH_TOKEN**. Choose the option expected by the endpoint; this menu does not enter or replace the saved key. - **Reset to defaults** restores the entire CC Zai preset, including its display name, endpoint, authentication choice, enabled state, and model-slot mappings. Inspect the restored fields for the exact model IDs supplied by your app version; see [model-slot mappings](https://repoprompt.com/docs/1.6.0/providers/cc-zai/#model-slot-mappings) for their meaning. Name, URL, and authentication changes are saved as you edit them. They clear the previous backend test result; use **Test Backend** to check the new configuration. Resetting keeps the saved Z.ai credential. Use the credential’s **Delete** button to remove it. #### CC Moonshot Provider reference: [CC Moonshot](https://repoprompt.com/docs/1.6.0/providers/cc-moonshot/). CC Moonshot backend panel with API key controls, model behavior, backend test, and Advanced disclosure CC Moonshot routes Claude Code through Kimi’s coding backend. - **API Key** accepts the Kimi credential. **Save** or **Change** stores it; **Delete** removes it. The key information button opens the Kimi Code console. - **View Kimi plans** opens the provider’s coding-plan information. - **Test Backend** checks the configured Kimi route. Kimi manages model selection. RepoPrompt sends neither a `--model` flag nor a Claude Code effort level for this backend. ##### Advanced Expand **Advanced** inside the CC Moonshot card to edit its connection settings: - **Display name** changes the backend’s label in RepoPrompt, including its card title. A blank name falls back to **CC Moonshot**. - **Base URL** sets the Kimi coding endpoint. The preset is `https://api.kimi.com/coding/`. The address must include an `http` or `https` scheme and a host to be valid. - **Auth header** offers **ANTHROPIC_API_KEY** and **ANTHROPIC_AUTH_TOKEN**, selecting the environment variable through which Claude Code receives the saved credential. CC Moonshot defaults to **ANTHROPIC_API_KEY**. Changing this choice does not replace the saved key. - **Reset to defaults** restores the entire CC Moonshot preset: its name, endpoint, authentication choice, enabled state, and backend-managed model selection with no `--model` flag. Name, URL, and authentication changes are saved as you edit them and clear the previous backend test result. Run **Test Backend** again to check them. Resetting keeps the saved Kimi credential; use the credential’s **Delete** button to remove it. #### CC Custom Provider reference: [CC Custom](https://repoprompt.com/docs/1.6.0/providers/cc-custom/). CC Custom backend panel with enable switch, display name, endpoint, authentication, model behavior, and backend test Use CC Custom for your own Claude-compatible endpoint: - **Enable custom backend** controls whether the configured backend is active. - **Display name** sets its label in the app. - **Base URL** identifies the compatible endpoint. - **Auth header** chooses **ANTHROPIC_API_KEY** or **ANTHROPIC_AUTH_TOKEN**, the environment variable through which the Claude process receives the credential. - **API Key** or **Auth Token** accepts that credential. **Save** or **Change** stores it; **Delete** removes it. - **Model behavior → No model flag** leaves model selection to the backend. RepoPrompt sends no Claude slot or Claude Code effort level. - **Model behavior → Claude slot mappings** exposes **Haiku**, **Sonnet**, and **Opus** model-ID fields. All three must be filled before the backend can launch. **Reset custom backend** restores the custom backend preset. - **Test Backend** checks the enabled, configured endpoint. :::caution[Approval-free modes] Full Access, Grok’s always-approve launch, and Devin’s Full Approval allow actions without individual confirmation. Codex Full Access also permits writes outside the workspace sandbox. Use these modes only where that access is intended. Sub-agent policy remains separately controlled in [Agent Permissions](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/). ::: --- ## Context Builder (3) Context Builder settings showing shared budgets, enhancement, question timeout, and separate UI and MCP run options Configure context and analysis token budgets, prompt enhancement, question timeouts, and clarifying-question behavior. This page also manages custom instructions and distinguishes runs started in the interface from runs requested through MCP. Open **Settings → Agent Mode → Context Builder**. Shared settings apply to context building from the interface and MCP, while each run type has its own clarifying-question switch. Screenshot selections are examples, not all factory defaults. ### Context Builder Agent About Context Builder and the Context Builder Agent settings link The **Context Builder Agent** row shows the current CLI agent and model. Open it to change those choices in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). This page controls context-building behavior rather than model selection. ### Context Budget Context Budget slider and target-size explanation Sets the target size of the selected context package for context-only runs, such as preparing a web export. The slider spans **10,000–200,000 tokens** in **5,000-token steps**; the default is **160,000**. A lower target can produce a smaller package. This is a context-selection budget, not an output-token limit or a guarantee about a model's supported context window. ### Analysis Budget Analysis Budget slider for immediate plan, review, or answer generation Sets the context-package target when Context Builder will immediately produce a plan, review, or answer. The range is **40,000–200,000 tokens**, in **5,000-token steps**. The default is **120,000**, even though this capture shows **200k**. ### Prompt Enhancement Rewrite, Augment, and Preserve prompt-enhancement choices | Mode | Result | | --- | --- | | **Rewrite** | Rewrites the prompt while building context; the default mode. | | **Augment** | Keeps your instructions and appends relevant context. | | **Preserve** | Updates file selection while leaving instructions unchanged. | ### Question Timeout Question Timeout choices of 30 seconds, one minute, two minutes, and five minutes Choose **30 seconds**, **1 minute**, **2 minutes**, or **5 minutes**. This is how long the agent waits for your answer before continuing on its own; it applies to clarifying questions and Agent Mode `ask_user`. It is not the total Context Builder run timeout. ### UI Runs: clarifying questions UI Runs Allow Clarifying Questions switch For runs started with **Run** in the Context Builder panel, **Allow Clarifying Questions** lets the agent ask you for more information. It is on by default. The description reflects the selected Question Timeout. Turning this UI setting off also clears the MCP clarifying-question setting. Re-enabling UI questions does not automatically opt MCP runs back in. ### UI Runs: follow-up analysis Follow-up Analysis switch **Follow-up Analysis** automatically runs the current tab's selected plan, review, or question after context building completes. It is off by default, though it is enabled in the capture. The follow-up type is selected per tab. ### Custom Instructions Custom Instructions manager button and per-tab selection explanation **Add**, or the saved-prompt count, opens the custom-instructions manager. Choose **New**, enter a title and instructions, then **Save**; the same manager edits existing prompts. The settings page previews up to three saved titles. Saving a prompt here does not select it for every run. Select the instructions to use in the Context Builder panel for the current tab. ### MCP Runs MCP Runs Allow Clarifying Questions switch The MCP **Allow Clarifying Questions** switch is separate and off by default. Enable it when you intend to watch RepoPrompt and answer questions from an external client's `context_builder` request. Questions use the shared timeout and remain disabled for inactive target workspaces. MCP callers choose their requested response type through the tool. The UI-only Follow-up Analysis switch does not replace that request. See [MCP Tools](https://repoprompt.com/docs/1.6.0/settings/tools/#context_builder) for the tool overview. --- ## Overview (Agent-mode) Full Overview settings pane showing model shortcuts, supervision, providers, cleanup, hook approval, handoff instructions, permissions, context budgets, workflows, and chats Configure Agent Mode behavior and find the settings for models, providers, permissions, and context building. Open **Settings → Agent Mode → Overview**. This page combines shortcuts to detailed configuration with a few app-wide behavior controls. Screenshots illustrate the controls; the selections shown are examples rather than recommended defaults. ### Models and context - **Oracle Model** opens [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). Oracle analyzes the current file selection and chat history for planning and review, without tools or file edits. Change its model on the linked page. - **Context Builder Agent** also opens [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). Choose the agent and model that explore the repository and gather relevant files for Oracle. - **Sub-Agent Role Defaults** opens [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). Assign models to orchestration roles: **Pair** for primary work, **Design** for interface and copy work, **Explore** for investigation, and **Engineer** for implementation. The model names shown on Overview summarize your configuration. They are navigation links, not model pickers. ### Sub-Agent Supervision Sub-Agent Supervision panel with the default wait menu and its explanation **Default subagent wait** sets how long an orchestrating agent normally waits for a sub-agent before checking back. The available intervals are **2, 5, 10, 20, 30, and 60 minutes**. Shorter waits allow more frequent progress checks; longer waits reduce routine model calls. Completion, questions, or your steering can end a wait early. An agent can request a different wait for an individual task, so this is a default supervision interval rather than a task time limit. ### CLI Providers CLI Providers summary with provider connection indicators Open [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/) to connect runtimes, manage authentication, test connections, and configure provider controls. Overview summarizes the connection state for Codex CLI, Claude Code, OpenCode, Cursor CLI, Grok Build, Google Antigravity, and Devin CLI. These indicators summarize the connection information already held by the app. Use **Test Connection** on the provider page to check availability again. ### Provider Conversation Cleanup Provider Conversation Cleanup panel with Archive and Delete choices **Cleanup action** controls what RepoPrompt requests from a supported provider when you delete an Agent Mode session: - **Archive** requests archiving of the provider conversation. - **Delete** requests deletion of the provider conversation. Local session cleanup continues if the provider does not support conversation cleanup. Selecting an action does not immediately archive or delete existing sessions. :::caution[Provider-side cleanup] Deleting an Agent Mode session can also affect its provider conversation. Choose the cleanup action before removing sessions; support for the requested action depends on the provider. ::: ### Require Codex project-hook approval Codex project-hook approval switch and workspace override menu The app-wide **Require Codex project-hook approval** switch determines whether Codex may begin without approval of the displayed project hooks. When approval is required, **Continue Without Hooks** is unavailable. The first Codex turn remains blocked until those hooks are approved or become trusted externally. Turning off the requirement permits the continue-without-hooks path; it does not itself approve or trust hooks. When a workspace is available, **In this workspace** can override the app-wide setting: - **App default** follows the app-wide switch. - **Always require approval** requires hook approval in this workspace. - **Don't require approval** allows this workspace to use the continue-without-hooks path. ### Handoff Instructions Handoff Instructions editor, character count, Save, and Clear Saved Instructions controls Enter reusable instructions that the titlebar’s **Handoff** action appends to a handoff. The saved text applies across the app. - The editor accepts up to **20,000 characters** and displays a character count. - **Save** stores a changed, valid draft. Text that exceeds the limit must be shortened before saving. - **Clear Saved Instructions** removes the saved text and clears the editor. For example, you could save: ```text Summarize the task, decisions, changed files, and validation results. List the remaining work and any unresolved questions. ``` :::note[Saving and concurrent changes] If the saved instructions change elsewhere while you have an edited draft, the page warns that saving will replace the newer value. If global settings cannot be saved, a separate warning explains that changes are active only for the current launch until persistence is restored. ::: ### Agent Permissions Agent Permissions links for direct agents and sub-agents These links open [Agent Permissions](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/): - **Direct Agents** configures provider controls for agents you launch directly, such as Claude Bash access, Codex sandbox permissions, ACP session modes, and MCP restrictions. - **Sub-Agents** configures the policy for agents launched through MCP. The displayed policy name summarizes the current setting. Safe Managed applies managed overrides; other policy choices are configured on the linked page. :::note[Two permission scopes] Direct-agent controls and sub-agent policy are separate. Changing a provider control does not mean every MCP-launched sub-agent will use that same setting. ::: ### Context Builder Budgets & Timeouts Context Builder Budgets and Timeouts settings link **Context Builder Budgets & Timeouts** opens [Context Builder](https://repoprompt.com/docs/1.6.0/settings/context-builder/), which owns token budgets, prompt enhancement, question timeouts, and clarifying-question behavior. ### Agent Workflows Agent Workflows settings link and cleanup guidance summary Open [Agent Workflows](https://repoprompt.com/docs/1.6.0/settings/agent-workflows/) to manage built-in workflow visibility, featured workflows, custom Markdown workflows, and cleanup guidance. Overview displays a summary; change the workflow options on their own page. ### Agent Chats Agent Chats panel with Show chats created by MCP tools switch **Show chats created by MCP tools** controls whether the chat list includes Compose tabs created through MCP before an agent has run in them. Enable it to inspect and adjust those tabs’ selections, prompts, and Context Builder runs in Compose. Disable it to omit those not-yet-run chats from this view. The switch changes visibility; it does not delete the chats. ### Usage Quota Telemetry Newer builds also include passive usage quota display preferences (not shown in the historical overview screenshot above) that are reachable via the [App Settings Tool](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-app-settings/#agent_mode--selected-global-behavior): - **`agent_mode.claude_usage_quota_enabled`** — Passive run rate-limit diagnostics for Claude Code runs (does not connect an account or authorize external usage reads). - **`agent_mode.codex_usage_quota_enabled`** — Observe-only Codex quota display preference (quota readings are displayed in the UI and not returned over MCP). - **`agent_mode.usage_limits_display_enabled`** — Controls whether already-enabled usage sources are displayed in the UI, without changing routing or provider connections. --- ## Advanced (General) Full Advanced pane showing filesystem, AI behavior, history, shortcuts, URL opener, and saved prompts Configure workspace folder scanning, ignore rules, symbolic links, Code Maps, prompt packaging, history time tracking, keyboard-shortcut availability, URL opening, and saved-prompt utilities. Open **Settings → General → Advanced**. The screenshot shows example values. These controls combine app-wide preferences with prompt-editor options and one-time utilities. ### Workspace Folder Scanning Folder scanning controls for ignore files, symbolic links, and empty folders Changes refresh open folders and use the same preferences as the `app_settings` MCP tool. | Control | Effect | | --- | --- | | **Respect .repo_ignore rules** | Honors RepoPrompt-specific ignore files. Edit their contents in the Ignore Patterns editor or with file-editing tools. | | **Respect .cursorignore rules** | Honors `.cursorignore` files during scans. | | **Respect nested ignore files** | Reads ignore files in nested directories as well as the workspace root. | | **Follow symbolic links** | Follows symbolic links while scanning directories. | | **Show empty folders** | Includes empty folders in workspace folder listings. | These switches control scanning behavior; they do not edit your ignore files. ### Code Maps Global Code Maps disable switch and non-Git folder scanning option **Disable Code Maps globally** stops Code Map scanning and prompt inclusion, cancels active scans, and temporarily ignores saved workspace Copy and Chat Code Map modes. Those modes are preserved and take effect again when you turn the global disable switch off. **Enable Code Maps in non-Git folders** permits background Code Map scanning for plain folders. It is off by default for existing workspaces. It does not override a global Code Maps disable setting. ### Prompt Packaging Full and Relative file path choices and instruction timestamp checkbox **Full** and **Relative** choose how file paths appear in packaged prompts. **Include datetime in user instructions** adds a timestamp attribute to the user-instruction tags. These controls affect copied prompts and built-in chat instructions; they do not rename files. ### History time tracking Default idle threshold slider for history time tracking **Default idle threshold** controls the `history` MCP tool's active-work calculation. Gaps between agent turns longer than the threshold count as idle rather than active work. The range is **0–60 minutes**, in one-minute steps; the default is **10 minutes**. Lower values count only more tightly spaced work, while higher values include short breaks. A query can override the setting with `idle_threshold_minutes`. This changes the calculation, not the underlying session history. ### Keyboard Shortcuts Keyboard shortcuts master switch and Open Keyboard Shortcuts button **Enable keyboard shortcuts** is the same master switch used on the [Keyboard Shortcuts](https://repoprompt.com/docs/1.6.0/settings/keyboard-shortcuts/) page. Turning it off leaves custom bindings saved. **Open Keyboard Shortcuts…** opens the complete binding editor for this window. ### URL Opener URL Opener examples for folders, file selection, ephemeral workspaces, and saved prompts Use the **`repoprompt-ce://`** scheme for links from external tools. The page's **Copy** buttons copy examples so you can replace the sample paths and URL-encode your text. ```text repoprompt-ce://open//Users/example/Project repoprompt-ce://open//Users/example/Project?files=Sources/App.swift,README.md&prompt=Review%20the%20selected%20files repoprompt-ce://open//Users/example/Project?workspace=Review&focus=true&ephemeral=true repoprompt-ce://prompt?title=Review&content=Review%20the%20current%20selection&focus=true ``` The opener supports `workspace`, `files`, `prompt`, `focus`, `ephemeral`, and `persist` parameters. The examples respectively open a folder, select files and seed instructions, focus or create an ephemeral workspace, and create a saved prompt. Copying an example does not execute it. ### Saved Prompts Export Prompts, Import Prompts, and Reset Prompts buttons - **Export Prompts** writes saved prompts to a JSON file you choose, with `SavedPrompts.json` suggested as the filename. - **Import Prompts** reads a JSON file and adds imported prompts, reporting how many were added. - **Reset Prompts** asks for confirmation, removes custom prompts, and restores the defaults. This action cannot be undone through the reset dialog; export first if you want a backup. --- ## Appearance (General) Full Appearance pane showing theme, text size, display options, and text editing Adjust the app’s appearance, theme, and interface text size. Open **Settings → General → Appearance**. Most choices apply app-wide and are saved for later launches. The screenshot shows example selections, not recommended defaults. ### Theme Theme selector with System, Light, and Dark choices Choose **System** to follow macOS appearance, or **Light** or **Dark** to keep a specific color scheme. The selected theme is applied when you change it. ### Text Size Text Size selector with Normal, Large, and Extra Large choices **Normal**, **Large**, and **Extra Large** set the app's global text-size preset. You can also step through these presets with the font-size controls in [Keyboard Shortcuts](https://repoprompt.com/docs/1.6.0/settings/keyboard-shortcuts/). Changes normally apply immediately. During a response that freezes text scaling to keep the streaming layout stable, the new size is held until scaling is unfrozen. ### Display Options Display Options with collapse file changes, tooltips, and timestamp date switches - **Always Collapse File Changes** keeps file-change displays collapsed, reducing rendering work for very large generations. - **Show Tooltips** enables the app's hover explanations. - **Show dates in message timestamps** adds labels such as Yesterday, a weekday, or a date to message and tool timestamps. These settings change presentation; collapsing file changes does not undo edits. ### Text Editing Text Editing with spell checking, Compact or Expanded file picker style, and experimental mention menu **Enable Spell Checking in Instructions** checks spelling in the instructions text area. **@ File Picker Style** changes the density of file-mention suggestions: **Compact** or **Expanded**. **Enable @-Mention Menu (Experimental)** enables file suggestions when typing `@` in the Compose prompt editor. Picker style and enabling the experimental menu are separate controls. --- ## Keyboard Shortcuts (General) Full Keyboard Shortcuts pane showing the master switch and all four shortcut groups Review and customize keyboard shortcuts for RepoPrompt actions, including workspace, Compose, preset, and agent commands. Open **Settings → General → Keyboard Shortcuts**. Click a shortcut recorder and press the desired key combination to change that action's binding. Use its clear button to remove a binding. Bindings are stored per app; menu-bar shortcuts or other apps can conflict with them. The tables below list the implementation defaults. Your current bindings can differ. On a Mac, **Command** is ⌘, **Option** is ⌥, **Control** is ⌃, and **Shift** is ⇧. ### Enable keyboard shortcuts Enable keyboard shortcuts master switch and explanation that custom bindings remain saved Turn off **Enable keyboard shortcuts** to stop these registered shortcuts from running while keeping your custom bindings saved. [Advanced](https://repoprompt.com/docs/1.6.0/settings/advanced/#keyboard-shortcuts) exposes the same master setting. Although this pane calls them global hotkeys, action handlers still check the app and window context. Workspace and session actions need an appropriate focused RepoPrompt window; agent shortcuts need a real workspace. ### Agent & layout Agent and layout shortcuts for new chat, session sidebar, Context Composer, and session search | Action | Default | | --- | --- | | New Agent chat | Option+Command+N | | Toggle session sidebar | Option+Command+B | | Toggle Context Composer | Command+P | | Show Agent Session Switcher | Command+K | | Search all Agent sessions | Shift+Command+K | **New Agent chat** follows the titlebar's New Session action. The session switcher navigates sessions in the focused window; searching all sessions includes active and recent sessions across windows. ### Workspace & presets Workspace save actions and numbered preset shortcuts | Action | Default | | --- | --- | | Save workspace | Command+S | | Save workspace and switch to system workspace | Shift+Command+S | | Save current preset, or create one if none exists | Option+Command+S | | Create new preset | Option+Command+P | | Switch to preset 1–9 | Option+Command+1–9 | Preset numbers follow the workspace manager's preset order. Saving the current preset opens the creation flow if the workspace has no presets. See [Manage Presets](https://repoprompt.com/docs/1.6.0/settings/manage-presets/) for preset configuration. ### Agent session tabs Session tab creation, closing, navigation, parent navigation, and numbered tab shortcuts | Action | Default | | --- | --- | | New Agent session tab | Command+T | | Close active Agent session tab | Command+W | | Next Agent session tab | Control+Tab | | Previous Agent session tab | Control+Shift+Tab | | Next parent Agent session | Option+Command+] | | Previous parent Agent session | Option+Command+[ | | Focus Agent session tab 1–9 | Command+1–9 | Numbered session shortcuts follow the Agent session sidebar order. Parent-session navigation cycles only root rows; child sessions stay grouped under their parent. ### Display Increase and decrease font size shortcut recorders **Command+=** increases text size and **Command+-** decreases it. These step through the same global text-size presets as [Appearance](https://repoprompt.com/docs/1.6.0/settings/appearance/#text-size). --- ## Notifications (General) Full Notifications pane showing delivery controls, Agent Sessions events, response actions, and Chat and Context Builder notifications Choose which events notify you, whether previews include details, and which requests you can answer from a notification. Open **Settings → General → Notifications**. These preferences apply app-wide and also appear in the `notifications` group of the `app_settings` MCP tool. ### Notification delivery and previews Permission status, Open System Settings button, master switch, preview details, active-app delivery, and Dock badge controls **Enable Notifications** is the master switch. Turning it off stops notification posting and disables the event-specific controls below. macOS permission is separate: the status row reports whether delivery is allowed, and **Open System Settings…** opens the macOS notification settings. When macOS permission is denied, RepoPrompt can fall back to bouncing its Dock icon. - **Show Details in Notifications** includes commands, questions, and message previews. Turn it off for generic text; the **Approve** action is then never offered. - **Notify While RepoPrompt Is Active** allows input-needed banners while the app is frontmost, unless the relevant session is already on screen. - **Show Pending Count on Dock Icon** badges the Dock icon with the number of sessions waiting for you. These four switches are on by default. Notification previews can expose task content on screen; choose the details setting accordingly. ### Agent Sessions Agent Sessions controls for approvals, instruction waits, completion, failure, active-app completions, agent-driven sessions, and MCP questions The following event notifications are on by default: | Control | Event | | --- | --- | | **Approvals & Questions** | A session needs approval, an answer, or a review. | | **Waiting for Instruction** | A session is waiting for your next instruction. | | **Turn Complete** | An agent turn finishes while you are elsewhere. | | **Run Failed** | An agent run fails. | Notifications are grouped by session and removed when the request is handled elsewhere. Three additional options are off by default: - **Completions While RepoPrompt Is Active** also allows completion and failure banners while RepoPrompt is frontmost. It is separate from the input-needed banner setting above. - **Include Agent-Driven Sessions** includes sessions controlled by another agent through `agent_run`. Their interactions offer **Open** only, because the orchestrating agent handles the answers. - **Notify Instead of Activating for MCP Questions** posts a notification when an external MCP client asks a question in an Agent Mode tab while RepoPrompt is in the background, instead of bringing the app forward. ### Responding from Notifications Response action switches for approval, answers, and replies to completed turns **Approve from Notifications** is on by default, but only offers approval for short, single-line, low-risk shell commands displayed in full. File changes, permission grants, reviews, and persistent “always allow” decisions open RepoPrompt instead. Showing notification details must also be enabled. **Answer from Notifications** is on by default. Simple questions and instruction waits can offer option buttons, **Skip**, **Decline**, or **Reply**. **Reply from Turn-Complete Notifications** is off by default. Enable it to send typed notification replies as the session's next message. Every action is checked against the live request when pressed. Stale, risky, or complex requests open the app instead of applying an outdated response. ### Chat & Context Builder Chat Complete and Context Builder Complete notification switches **Chat Complete** notifies when a chat response finishes in the background. **Context Builder Complete** does the same when Context Builder finishes. Both are on by default. --- ## Telemetry (General) Full Telemetry pane with build status, three reporting controls, and privacy explanation Control sharing of crash reports and diagnostics, app-hang reports, and performance timing and tracing. Open **Settings → General → Telemetry**. Reporting depends on both your preferences and whether the build includes a configured telemetry service. ### Build status Telemetry status banner showing reporting active for this build The banner explains the effective state. Telemetry can be inactive because the Sentry SDK is absent, no Sentry DSN is configured, reporting is disabled in Settings, or the process was launched with `REPOPROMPT_TELEMETRY_DISABLED=1`. A stored preference alone does not mean data is being sent. The master control is unavailable in builds without the SDK. ### Reporting controls Share crash reports and diagnostics, App hang reports, and Performance timing and tracing controls - **Share crash reports and diagnostics** is the master permission for configured Sentry reporting. - **App hang reports** allows reporting when the SDK detects that the app has been stuck long enough. It requires the master setting. - **Performance timing and tracing** allows a conservative sample of startup traces. The implementation sets a 5% trace sample rate when enabled; manual tool and agent-run metrics are not sent by this build. Turning off the master setting disables the subordinate controls. Automatic release-health session tracking and failed-request capture are disabled. ### Privacy Privacy disclosure listing collected metadata, excluded content, scrubbing, and the process-level disable variable Reported information can include crash diagnostics, enabled hang reports, release/build metadata, OS and app versions, and optional startup timing. RepoPrompt does not intentionally send prompt contents, chat transcripts, selected file contents, tool payloads, API keys, provider tokens, or full local paths through telemetry. Before upload, a scrubber removes request payloads, headers, cookies, query strings, obvious secrets, local home paths, user/location/server identifiers, stable device identifiers, and IP-like values. To disable telemetry for an entire process regardless of Settings, set **`REPOPROMPT_TELEMETRY_DISABLED=1` before launching it**. This telemetry preference does not control information sent to execution providers or to [Model Router](https://repoprompt.com/docs/1.6.0/settings/model-router/) decision services. --- ## Updates (General) Full Software Updates pane showing update status, manual check, channel selection, and automatic checks Manage software-update checks and choose the release channel used for RepoPrompt updates. Open **Settings → General → Updates**. Status and available actions depend on the installed build and its update configuration. ### Check for Updates Update status beside the Check for Updates button Choose **Check for Updates** to request an update check. The status distinguishes **not checked yet**, **checking**, a successful check with no newer eligible version, an available update, and a failed check. “Updates have not been checked yet” does not confirm that your installation is current. If an update is available, the app offers installation or a manual download according to what that build supports. Checking alone is not confirmation that an update was installed. ### Update Channel Update Channel selector with Stable and Tip Builds | Channel | Releases offered | | --- | --- | | **Stable** | Curated releases; the default channel. | | **Tip Builds** | Signed and notarized builds from the latest passing main branch. | Switching from Tip Builds back to Stable takes effect with the next applicable stable release. To return immediately, reinstall Stable. Newer builds can also show Tip build history when that channel is selected. For help choosing a channel, see [What Is the Tip Version and Should I Use It?](https://repoprompt.com/docs/1.6.0/faq/tip-version/). ### Automatic checks Automatically check for updates checkbox **Automatically check for updates** enables passive checks when the updater is configured for this build. The implementation checks on startup and schedules checks at 12-hour intervals. Turning it off stops those passive checks; you can still use the manual button. Passive checks discover releases. Installation remains a separate updater action. --- ## MCP Server (Mcp-server) Full MCP Server pane with window status, Oracle presets, Context Builder, Quick Setup, CLI Tools, and JSON Configuration Manage RepoPrompt’s Model Context Protocol server, inspect connection status, configure external clients, and access CLI installation and JSON configuration tools. Open **Settings → MCP Server**. The window number identifies the workspace window whose MCP access you are configuring. Connection counts and available tool counts are live values; the screenshots on this page are historical captures showing `21 available` tools (out of **31 total domain tools**, **21 are advertised** to external clients — **3 global** and **18 window-scoped** — while **10 policy-gated and sub-agent internal tools** are reserved for Agent Mode and oversight sessions). ### Status and window access MCP status, window access switch, Auto-Start, connection count, Status Dashboard, and Force Stop Listener The main switch enables or disables MCP tools **for this window**. A running listener and enabled window access are different states: the page can report **Active**, **Waiting for listener…**, **Listener active** with tools disabled for the window, or **Inactive**. **Auto-Start** controls automatic MCP server startup when RepoPrompt launches. The connection badge summarizes connected clients. **Status Dashboard** opens diagnostics, and an error indicator, when present, opens error details. **Force Stop Listener** shuts down the shared listener for **every window and client**. Use the window switch when you only intend to disable access to the current window. A **Cancel** button can appear while a tool is running to abort that call. ### Oracle Model Presets Oracle Model Presets switch, Manage button, fallback model picker, and Show presets link **Use Oracle Model Presets for MCP** controls whether MCP exposes configured Oracle presets. **Manage** opens [Model Presets](https://repoprompt.com/docs/1.6.0/settings/model-presets/). When presets are disabled, MCP uses the current Oracle model. If no presets are defined, the page offers a model choice and uses the Oracle fallback. If Setup Wizard temporarily hid presets, **Show presets** restores their visibility. The selected model in the screenshot is an example, not a requirement. ### Context Builder Context Builder model summary linking to Agent Models This row displays the agent and model used by the `context_builder` MCP tool. Open it to change the selection in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). It is separate from Oracle Model Presets. ### Quick Setup Quick Setup with Install MCP, Skills menu, and copy configuration button **Install MCP…** offers setup for supported clients, including Cursor, VS Code, Codex CLI, OpenCode, Claude Desktop, and per-project Claude Code configuration. Choose the client you intend to connect. If it does not discover the integration immediately, restart that client after installation. **Skills** installs or removes integration instructions for supported locations, including shared `.agents/skills`, Claude Code commands, and RepoPrompt's isolated Codex prompts. Choose the MCP or CLI variant for the integration you use. These are separate from installing the MCP client configuration. The copy button copies the generated MCP configuration for manual setup. ### CLI Tools CLI installation status and uninstall actions for rpce-cli and claude-rpce **`rpce-cli`** runs MCP commands from a terminal. **`claude-rpce`** wraps Claude Code so it can use RepoPrompt's MCP tools. Each row reports whether its command is installed and offers **Install**, **Update**, or **Uninstall** as appropriate. Debug builds use their debug command names. Installing a CLI command and enabling a window's MCP access are separate steps. ### JSON Configuration Collapsed JSON Configuration disclosure Expand **JSON Configuration** to inspect and copy the JSON for an external client's MCP configuration. The generated command normally uses a managed link that survives app updates, with a bundled-path fallback. Add the configuration in your client, then connect it to RepoPrompt. If the client cannot find `repoprompt-mcp` after moving the app or switching app builds, copy the configuration again from the intended running app and update the client. Use [Tools](https://repoprompt.com/docs/1.6.0/settings/tools/) to control individual tool availability. Tool access also remains subject to the target workspace and applicable approval rules. --- ## Model Presets (Mcp-server) Configured Default model preset showing one Oracle, its model, description, and All modes Create and manage named model configurations for common tasks and expose model presets through the MCP interface. Open **Settings → MCP Server → Model Presets**, or choose **Manage Presets** from Chat Settings. These are named Oracle configurations, distinct from [workspace presets](https://repoprompt.com/docs/1.6.0/settings/manage-presets/) and [Copy/Chat workflow presets](https://repoprompt.com/docs/1.6.0/settings/workflow-presets/). ### Read a model preset Default preset row with one Oracle and no mode restrictions The pictured row contains: - **Default**: the preset name. - **1 Oracle**: the number of models in its ordered Oracle roster. - The configured model name: the model used by that roster entry. - **Current chat model**: this preset's description. - **All modes**: no Chat, Plan, or Review restriction. The model and description are saved preset values. “Current chat model” does not make the preset a live alias that automatically follows later model-picker changes. ### Create and edit If the list is empty, **Create Default Preset** creates one from the currently selected chat model and opens its editor. Otherwise, use **Add Preset**. Hovering an existing row reveals **Edit** and the delete control; those actions are not visible in this capture. The editor configures the name, ordered Oracle models, optional description, supported modes, and optional Chat Preset mappings. The first model is the **Primary Oracle**; additional entries can be reordered or removed. Save persists the configuration. Deleting a preset removes the named configuration, not the provider account or model itself. ### Expose presets to MCP Enable **Use Oracle Model Presets for MCP** in [MCP Server](https://repoprompt.com/docs/1.6.0/settings/mcp-server/#oracle-model-presets) or [Chat Settings](https://repoprompt.com/docs/1.6.0/settings/chat-settings/#oracle-model-presets). These controls use the same saved setting. When recommendations temporarily hide presets, the **Presets Hidden** banner offers **Show Presets**. The presets remain stored while hidden. Mode restrictions can limit which presets are available for a particular Oracle request. --- ## Tools (3) MCP Tools window access switch, enabled count, and tool search Manage window-level MCP access, search the tool catalog, and configure individual tool availability. The sections below show each tool separately so its controls and description remain readable. Open **Settings → MCP Server → Tools**. RepoPrompt defines **31 total domain tools**, of which **21 are advertised** to standard external MCP clients (composed of **3 global tools** — `app_settings`, `bind_context`, and `manage_workspaces` — and **18 window-scoped tools**). The remaining **10 policy-gated and sub-agent internal tools** are reserved for eligible Agent Mode sessions and cross-session oversight. The screenshots on this page (`tools.png` and individual `tools-*.png` captures) are historical captures showing the 21 advertised tool descriptions expanded. There are minor differences in parameter naming (such as `search_pattern` vs `pattern` and regex flag descriptions) and legacy window-selector wording compared to the latest code (`MCPDomainToolCatalog.swift`). For current arguments, response behavior, and examples, see the [MCP Server Tools Reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/).
View the complete MCP Tools screenshot (historical capture) Complete MCP Tools pane with all 21 tool descriptions expanded
### Access, search, and availability **Enable MCP tools for this window** is the same window-level gate as the switch on [MCP Server](https://repoprompt.com/docs/1.6.0/settings/mcp-server/). Turning it off disables the individual switches in this pane. Individual tool switches are saved in an **app-wide** disabled-tools list shared by windows. They are not separate per-window preferences, despite the captured pane's introductory wording. Changes notify connected clients that the tool list changed. **Search tools…** filters names and descriptions without changing enablement. The count shows how many tools are enabled; with a search, the list also shows how many matching tools are enabled. **More…** expands a long description and **Show less** collapses it. Expanding a description does not run the tool. If the list says **No tools discovered**, start the MCP server and connect a client. Tools restricted to particular agent contexts are omitted from this general settings list. Enabling a tool does not bypass workspace permissions or the tool's own input and approval checks. ### agent_explore Launches short-lived, read-only child agents for narrow repository investigations. Each gets a fresh context and the Explore role. Operations are `start`, `poll`, `wait`, and `cancel`; a batch can start multiple independent probes. See the [`agent_explore` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#agent_explore). Explore children cannot edit files, call Oracle, or spawn more agents. They inherit worktree bindings by default, with an opt-out. When Model Router is enabled, new explore children can be routed across eligible targets. agent\_explore switch and expanded description for read-only exploration agents ### agent_manage Lists agent choices, model and role mappings, sessions, and workflows. It also reads session logs, exports handoffs, creates or resumes sessions, stops sessions, and cleans up eligible MCP-created sessions. `list_agents` supplies the current role mappings and exact model identifiers. `get_log` reads transcript turns; handoff export prepares context for continuing elsewhere. Cleanup targets specified MCP-originated sessions and does not delete user-created sessions. See the [`agent_manage` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#agent_manage). agent\_manage switch and expanded agent catalog, session management, and workflow description ### agent_run Starts and controls Agent Mode runs. `start` creates a new session; `steer` continues an existing one. `poll` checks immediately, `wait` waits for completion or input, `respond` resolves a pending interaction, and `cancel` stops an active run. Use the returned session and interaction identifiers for follow-up calls. Role labels use the configured Agent Models mapping; an exact compound model identifier pins a target. Model Router can choose for eligible starts using a role or omitted model. See the [`agent_run` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#agent_run) and [Model Router](https://repoprompt.com/docs/1.6.0/settings/model-router/). agent\_run switch and expanded start, wait, steering, and interaction description ### app_settings Reads and updates the allowed set of app-wide preferences. `list` discovers settings, `get` reads values, `set` writes one key, and `options` discovers supported choices where available. Only exposed settings can be changed; invalid or out-of-range values are rejected. The current implementation also exposes notification preferences, matching the [Notifications](https://repoprompt.com/docs/1.6.0/settings/notifications/) pane. See the [`app_settings` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#app_settings) and the full [App Settings Tool reference](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-app-settings/). app\_settings switch and expanded allowed preferences and operations ### apply_edits Edits file contents using exactly one mode: replace the whole file with `rewrite`, replace matching text with `search` and `replace`, or apply a list of `edits`. Mixing modes is rejected. Replacements are literal text. A rewrite can opt into creating a missing file with `on_missing`; otherwise a missing file is an error. Enable this tool only when clients should be able to request file-content changes under the applicable permissions. See the [`apply_edits` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#apply_edits). apply\_edits switch and expanded rewrite, replacement, and multiple-edit modes ### bind_context Lists available contexts, reports the connection's current binding, and binds a client to a specific workspace context. Prefer absolute workspace root paths in `working_dirs`, or use a returned `context_id`. The binding is retained for that MCP connection. Switching the visible tab does not redirect an existing binding. The captured description includes legacy window selectors; newer builds make this a global context tool without an app-window selector. Use the schema advertised by your connected build. See the [`bind_context` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#bind_context) and [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/#context-binding). bind\_context switch and expanded context listing and binding description ### context_builder Runs a Context Builder agent to discover relevant code, select files within a token budget, and prepare a clarified prompt. Describe the task and known constraints; exhaustive file selection beforehand is not required. The default or `clarify` response returns context for later use. `question`, `plan`, and `review` request a follow-up answer, implementation plan, or review. Response export can produce a shareable file. See the [`context_builder` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#context_builder). Configure discovery in [Context Builder](https://repoprompt.com/docs/1.6.0/settings/context-builder/) and its model in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). context\_builder switch and expanded discovery, response type, and export description ### file_actions Creates, moves, or deletes files using absolute paths. A created file is automatically selected. Creation rejects existing files unless overwrite is explicitly requested; a move fails when the destination already exists. Deletion moves files or folders to the macOS Trash, where they remain recoverable until Trash is emptied. Moving a file transfers its selection state. See the [`file_actions` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#file_actions). file\_actions switch and expanded create, delete, and move behavior ### file_search Searches file paths, file contents, or both. `auto` selects the mode from the pattern; explicit modes are `path`, `content`, and `both`. Filters can limit extensions and directories or exclude paths. Regex matching is available; set `regex=false` for literal content matching or glob-style path matching. Result and output limits can truncate large searches. For an agent bound to a worktree, filesystem searching uses that worktree even when returned paths retain the canonical workspace form. See the [`file_search` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#file_search). file\_search switch and expanded path, content, matching, and filter options ### get_code_structure Returns root-local committed code structure for supplied files or directories, or the current selection when paths are omitted. It can include signatures and expand relationships through `uses`, `used_by`, or both. Output size and relationship depth limit the response. If a result reports truncation, request a larger size or narrow the seeds. Update-pending information distinguishes a usable committed graph from work still being refreshed. See the [`get_code_structure` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#get_code_structure). get\_code\_structure switch and expanded structure, relationship, signature, and output-size options ### get_file_tree Returns a text directory tree or lists loaded root folders. Tree modes include automatic sizing, full output, folders only, and selected files with their parent directories. Use `path` to focus a subtree and `max_depth` to limit traversal. Selection and Code Map markers describe workspace state. Bound-worktree searches follow the session's worktree. See the [`get_file_tree` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#get_file_tree). get\_file\_tree switch and expanded tree types, modes, depth, and selection markers ### git Provides read-only Git inspection: `status`, `diff`, `log`, `show`, and `blame`. Diff comparison choices include staged, unstaged, uncommitted, branch, and merge-base comparisons. Detail levels range from summary to full patches. Artifact output writes review files and can make them available for later context selection. This tool does not commit or push. Use repository selectors when working with multiple roots; some history operations use the primary repository only. See the [`git` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#git). git switch and expanded read-only status, diff, log, show, blame, and artifact options ### history Queries past Agent Mode sessions across saved workspaces. Operations list sessions, search transcripts and summaries, retrieve a bounded session excerpt, and calculate time spent. These operations are read-only. Use workspace filters when you want a narrower scope; binding the MCP connection to a window does not itself restrict historical searches. Time calculations use the [Advanced idle threshold](https://repoprompt.com/docs/1.6.0/settings/advanced/#history-time-tracking) unless overridden per query. See the [`history` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#history). history switch and expanded cross-workspace session search, transcript, and time analytics ### manage_selection Changes the file context used by tools: get, add, remove, replace, clear, preview, promote, or demote selections. Files can be represented by full content, line slices, or Code Maps. `set` can replace a selection, so use incremental `add` and `remove` when preserving existing context matters. Multi-root paths can use a root-name prefix to disambiguate files. Git artifact paths have stricter matching and representation limits than ordinary workspace files. See the [`manage_selection` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#manage_selection). manage\_selection switch and expanded selection operations, full files, slices, and Code Maps ### manage_workspaces Lists, creates, switches, hides, restores, and deletes workspaces, and manages their folders and Compose tabs. Hiding keeps a workspace recoverable; deleting a saved workspace is permanent. `bind_context` is the canonical tool for connection binding. Legacy tab-listing and tab-selection operations remain compatibility paths. Background tab creation can avoid stealing focus; setting `focus=true` visibly switches the user's tab. See the [`manage_workspaces` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#manage_workspaces) and [Connection Management](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-connections/). manage\_workspaces switch and expanded workspace and Compose-tab lifecycle operations ### manage_worktree Lists, inspects, creates, and binds Git worktrees to Agent sessions. Merge operations use the session's bound source worktree and can preview, apply, inspect status, continue, or abort a merge. Preview does not mutate the repository. Apply uses the returned operation identifier and requires the applicable confirmation; plain MCP callers use `confirm_preview=true`. Worktree binding is session-specific, so identify the intended session and repository when there is ambiguity. See the [`manage_worktree` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#manage_worktree) and [Worktrees](https://repoprompt.com/docs/1.6.0/worktrees/). manage\_worktree switch and expanded Git worktree binding, merge preview, apply, and confirmation behavior ### oracle_send Consults Oracle for questions, planning, or review. Without an explicit chat or new-chat request, it resumes the selected eligible conversation, falling back to the most recent eligible conversation. `new_chat=true` starts fresh. A model override applies only to an explicit new conversation. Exposed Model Presets can select a complete Oracle roster and Chat Preset. Response export writes a shareable file for another agent. Agent Mode can expose `ask_oracle` for the corresponding task. See the [`oracle_send` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#oracle_send). oracle\_send switch and expanded conversation continuation, model selection, and export behavior ### oracle_utils Provides read-only Oracle helpers: discover available model choices and list Oracle/chat sessions. It does not send an Oracle message. Use `oracle_send`, or `ask_oracle` when exposed in Agent Mode, to request a response. oracle\_utils switch and expanded read-only model and session listing See the [`oracle_utils` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#oracle_utils). ### prompt Gets, replaces, appends to, clears, or exports the shared instructions text. It also lists and selects copy presets. Selecting a preset requires an explicitly bound tab context. Export writes the formatted prompt to a file. It does not submit that file to another AI service. A copy-preset override changes the export format. See the [`prompt` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#prompt). prompt switch and expanded prompt editing, export, and preset operations ### read_file Reads a file in full or by line range. Positive `start_line` values are one-based; a negative value reads from the end. With a positive start, `limit` bounds the number of lines. Reuse returned file paths for reliable lookup, adding a root alias when needed. For worktree-bound sessions, reads use the bound worktree. Approved external read paths remain read-only. See the [`read_file` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#read_file). read\_file switch and expanded path and line-range reading options ### workspace_context Returns or exports the current workspace context. The default snapshot includes the prompt, selection, code structure, and token counts. Optional sections can include full file contents or a selected-file tree. Use include options to control the payload, or a copy-preset override to change rendering and token calculation. `export` writes the rendered context to disk; it does not send that context to an external service. See the [`workspace_context` contract](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#workspace_context). workspace\_context switch and expanded snapshot, export, token, and copy-preset options ### Policy-Gated and Sub-Agent Internal Tools In addition to the 21 advertised tools above, RepoPrompt defines **10 policy-gated and sub-agent internal tools** that are omitted from this general settings pane and dynamically exposed only within eligible Agent Mode sessions and authorized oversight contexts: - **`ask_user`** — Prompts the user with structured questions, optional suggested answers, and configurable timeouts. - **`ask_oracle`** — Consults the configured Oracle model directly from an eligible Agent Mode session. - **`oracle_chat_log`** — Reads recent Oracle conversation history (`limit` 1–50) during an Agent Mode run without sending a new turn. - **`agent_session_link`** — Manages cross-window and cross-session communication links, steering, model targeting, and auto-wake snoozing. - **`session_admin`** — Administers sessions within a user-granted delegation scope, including session tree inspection, organization, worktree binding, and merge coordination. - **`become_overseer`** — Requests promotion of the calling session to an overseer role to coordinate sibling sessions. - **`self_compact`** — Requests self-compaction or context inspection (`op="context"` or `"compact"`) of the agent's own session context. - **`share_thoughts`** — Publishes reasoning thoughts or plan progress to the session timeline. - **`set_status`** — Updates the human-visible status indicator on the session card. - **`wait_for_next_user_instruction`** — Signals that the agent has completed its turn and is waiting for the next user instruction. See [Policy-Gated and Sub-Agent Internal Tools](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#policy-gated-and-sub-agent-internal-tools) in the Tools Reference for details. --- ## Workspace Approvals (Mcp-server) Workspace Approvals with global approval, operation permissions, and trusted clients Manage approvals for operations that change RepoPrompt workspaces, such as creating folders or deleting workspaces. Configure global operation approvals and review or revoke trusted-client permissions. Open **Settings → MCP Server → Workspace Approvals**. These controls govern requests to change RepoPrompt workspaces. CLI-agent tool permissions and sub-agent policies are configured separately in [Agent Permissions](https://repoprompt.com/docs/1.6.0/settings/agent-permissions/). ### Global Settings Auto-approve All Operations switch **Auto-approve All Operations** skips workspace-operation approval prompts from every client. It is off by default. When enabled, the individual operation switches below are disabled because the global choice already approves them all. This switch grants future requests approval; it does not itself create, remove, or change a workspace. ### Operation Permissions Create Workspace, Delete Workspace, Add Folder, and Remove Folder approval switches with risk labels Enable a switch to automatically approve that operation globally, without granting every operation. All four are off by default. | Operation | Effect | Displayed risk | | --- | --- | --- | | **Create Workspace** | Creates a workspace record. | Low | | **Delete Workspace** | Deletes an existing workspace. | High | | **Add Folder** | Adds a folder to a workspace. | Medium | | **Remove Folder** | Removes a folder from a workspace. | Medium | Adding or removing a workspace folder changes its membership; it does not mean creating or deleting that project folder on disk. Workspace deletion can remove saved workspace state and history, so review the requested target. ### Trusted Clients Trusted Clients list showing a client, permission count, expansion control, removal control, and Reset All Clients appear here after you choose **Always Allow** for a workspace operation. Each row shows the client identifier, saved permission count, and last-used information. Expand a row to inspect and remove individual operation permissions, or use its removal control to clear all permissions for that client. **Reset All** asks for confirmation before removing every client's saved auto-approvals. It does not turn off the global approval settings above: disable those separately if you want those operations to prompt again. --- ## API Providers (Models-and-providers) API Providers pane with legacy storage repair, provider credentials, Azure configuration, and local model settings Configure direct API-provider credentials and provider-specific connections used by RepoPrompt’s model features. These API connections are separate from the coding-agent runtimes configured in CLI Providers. Open **Settings → Models & Providers → API Providers**. These connections primarily serve the Oracle Model, built-in chat, and legacy integrations. For coding-agent runtimes, use [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/). The masked keys and model selections in the screenshot are examples. ### Credentials and model choices For the difference between a coding-runtime login and an API credential, and how saved keys are used, see [Do I Need an API Key?](https://repoprompt.com/docs/1.6.0/faq/api-keys/). For a provider, enter its key and choose **Validate & Save**. A validated entry displays a checkmark and changes the button label to **Change**. **Delete** removes that stored provider credential. The information button opens the provider's reference page. Where model discovery is supported, validate first to populate **Add Custom Model**. Select a model to add it to RepoPrompt's model choices; **None (Remove custom model)** clears that custom choice. Where the UI instead offers a text field, enter a compatible model identifier and use its save button. Validation contacts the selected provider; it is not an offline format check. ### Legacy secure storage repair Legacy secure storage repair notice and Review button Older official builds may have credentials in a legacy Keychain service. **Review…** opens an explicit review/import flow; no legacy scan runs at startup. Imported values are verified, and legacy values are retained by default for rollback. Deleting a legacy value is a separate action. Follow [Recover Credentials After an Upgrade](https://repoprompt.com/docs/1.6.0/faq/credential-recovery/) for scan results, replacement conflicts, Keychain prompts, and the optional legacy deletion step. Storage verification is separate from validation with the provider's service. ### Anthropic Provider reference: [Anthropic API](https://repoprompt.com/docs/1.6.0/providers/anthropic-api/). Anthropic API key controls and custom model identifier field Configure the direct Anthropic API key here. The custom-model field accepts a compatible Anthropic model identifier. This is separate from signing into Claude Code in CLI Providers. ### OpenAI Provider reference: [OpenAI API](https://repoprompt.com/docs/1.6.0/providers/openai-api/). OpenAI key controls, Service Tier, service-tier variant switch, and custom base URL disclosure Validate the key to fetch available models. **Service Tier** offers **Auto**, **Default**, **Flex**, and **Priority**. Auto follows the API project's settings. The pane describes Flex as a cost-oriented option and Priority as a speed-oriented option; availability depends on the provider and model. **Show service-tier variants in model list** exposes tier-specific model choices. Selecting one overrides the global tier for that request. Expand **Advanced (Custom Base URL)** to configure and validate an alternate OpenAI endpoint. For a separate OpenAI-compatible provider configuration, use [Custom API](https://repoprompt.com/docs/1.6.0/settings/custom-api/). ### DeepSeek Provider reference: [DeepSeek](https://repoprompt.com/docs/1.6.0/providers/deepseek/). DeepSeek validated key and custom model selection Validate the DeepSeek API key, then choose a discovered custom model if needed. The selected model and success message show what has been added to the model list; the pictured model is not a required default. ### Fireworks AI Provider reference: [Fireworks AI](https://repoprompt.com/docs/1.6.0/providers/fireworks-ai/). Fireworks AI key validation and model discovery status Configure a Fireworks AI key. Model choices become available after validation; an empty discovery list is shown with guidance to validate first. ### Grok (xAI) Provider reference: [Grok / xAI API](https://repoprompt.com/docs/1.6.0/providers/xai-api/). Grok xAI key validation and model discovery status Configure direct xAI API access and discover available models. A saved xAI API key is also passed to Grok Build for Agent Mode, Context Builder, Oracle, Chat, and model discovery (including Connect), even when you are signed in with `grok login`. Grok chooses which credential each request uses; requests that use the key are billed to your xAI API account. ### Groq Provider reference: [Groq](https://repoprompt.com/docs/1.6.0/providers/groq/). Groq key validation and model discovery status Configure a Groq API key and validate it before selecting a discovered model. **Groq** and **Grok (xAI)** are different provider entries. ### Z.AI Provider reference: [Z.AI API](https://repoprompt.com/docs/1.6.0/providers/zai-api/). Z.AI key controls and custom model selection Configure the Z.AI key and optional custom model. Unlike most entries on this page, this credential also activates **CC Zai** in Agent Mode. Manage that runtime's configuration in [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/). ### Gemini Provider reference: [Gemini API](https://repoprompt.com/docs/1.6.0/providers/gemini-api/). Gemini key controls and custom model identifier field Configure the Gemini API key for direct model access. Use the custom-model field and its save control for a compatible model identifier. This is not the Google Antigravity CLI setup. ### Azure OpenAI Provider reference: [Azure OpenAI](https://repoprompt.com/docs/1.6.0/providers/azure-openai/). Azure OpenAI Base URL, API Version, key, and validation controls Enter the Azure resource **Base URL**, **API Version**, and **API Key**, then choose **Validate & Save**. The displayed API-version value is an example from the capture, not a recommendation for every Azure deployment. After discovery, the implementation can offer **Add Custom Deployment** to pin a deployment. Clearing that choice returns to the discovered deployment priority. ### Local Model Settings Provider reference: [Local Models](https://repoprompt.com/docs/1.6.0/providers/local-models/). Local model URL, model selector, Validate and fetch models, and Reset to Default Enter the URL of your running local model server, then choose **Validate & fetch models**. Once discovery succeeds, select a model. For an already validated configuration, the button becomes **Refresh models**. The pane identifies common ports: **11434** for Ollama and **1234** for LM Studio. **Reset to Default** restores the local configuration defaults. It does not install or start a model server. --- ## Custom API (3) OpenAI-compatible provider configuration with endpoint, key, preferred model, token limit, and save controls Add and manage custom OpenAI-compatible API endpoints, their authentication, and the models offered through each endpoint. Open **Settings → Models & Providers → Custom API** to configure an OpenAI-compatible endpoint. This is a direct API connection, not a CLI-agent runtime. For endpoint compatibility, model discovery, prerequisites, and account boundaries, see the [Custom API provider reference](https://repoprompt.com/docs/1.6.0/providers/custom-api/). The sections below describe the configuration fields and actions. ### Endpoint, key, and preferred model Custom API provider URL, key, and optional preferred model identifier Enter the **Provider URL**, including the API version path where needed, and the provider's **API Key**. Endpoints that do not require authentication can use an empty key. Current builds may request explicit consent before sending credentials to a non-HTTPS endpoint. Leave **Preferred Model ID** blank to discover models from the endpoint. If the provider cannot list models, enter an exact compatible model identifier instead. ### Default Output Max Tokens Default Output Max Tokens field and save button This caps the requested output length. **0** or an empty saved limit uses the model/provider default. Increase a positive limit when outputs are cut off, subject to the model's actual limits. The displayed **8192** is an example value. The adjacent save button updates the limit on an already validated configuration without another network validation. ### Validate, save, and remove Validate and Save, Delete Provider, and Content-Type header controls **Validate & Save** validates the endpoint and persists the configuration. With no preferred model, it fetches a nonempty model list. With a preferred model, it tests that model with a short completion request rather than relying on model discovery. That validation sends a small test prompt to the provider. **Content-Type header** controls inclusion of that header in the saved custom-provider configuration. **Delete Provider** removes the custom configuration and its stored credential; it does not delete an account at the service. After successful discovery, **Available Models** offers search and per-model enable controls, showing up to 20 matches with enabled models first. Previously enabled models are retained when they still exist in the refreshed catalog. A preferred model is stored separately from that enabled-model set. --- ## Model Config (Models-and-providers) Settings sidebar with the Model Config item visible. Configure per-model streaming, API routing, and temperature overrides. These settings are especially useful when a custom endpoint needs behavior different from the app's defaults. Open **Settings → Models & Providers → Model Config**. Available models are grouped by provider and sorted by name. Expand a model to see its controls. If a model is missing, configure its provider and model availability in [API Providers](https://repoprompt.com/docs/1.6.0/settings/api-providers/), [OpenRouter](https://repoprompt.com/docs/1.6.0/settings/openrouter/), or [Custom API](https://repoprompt.com/docs/1.6.0/settings/custom-api/). Changes are saved automatically as app-wide overrides keyed to the model's identifier. There is no separate Save button. Models with saved overrides display a sliders icon and expand automatically when you open the page. For model discovery, identifiers, capabilities, effort, and tiers, use the shared [Models reference](https://repoprompt.com/docs/1.6.0/providers/models/). This page documents the per-model settings controls. ### Allow Diff Editing This switch remains in the interface and saves a per-model preference, but the current implementation treats every model as capable of diff editing. The saved switch does **not** disable diff eligibility or force whole-file responses. To choose **Diff**, **Whole**, or **None** for built-in chat, use [Chat Settings → Advanced Chat Controls](https://repoprompt.com/docs/1.6.0/settings/chat-settings/#advanced-chat-controls-edit-mode). That response-format choice is separate from this legacy capability switch. ### Use Streaming Controls whether a supported provider request streams its response as it arrives or returns the completed response together. Turn it off for a model or endpoint that does not support streaming reliably. The saved override is consulted by provider paths that use the model's streaming capability. It cannot make an endpoint support a streaming protocol it does not implement. Built-in model defaults can differ, so the switch is not a universal guarantee of the request mode used by every provider. ### Use Responses-API This switch appears only for custom-provider models. It controls the model's API-routing flag for the **Responses API**, rather than the usual Chat Completions route. Enable it only when the custom endpoint supports that API. Without a saved override, custom-provider models default to not using the Responses API. Built-in models choose their API route through the app's model definitions and do not show this switch. This setting does not change the provider URL, credentials, or available model list. Configure those on [Custom API](https://repoprompt.com/docs/1.6.0/settings/custom-api/). ### Temperature The per-model slider ranges from **0.0 to 2.0** in **0.1** steps. Moving it creates an explicit temperature override for that model. An explicit **0.0** is still an override; it is not the same as removing the setting. **Reset** removes only the temperature override. The row then displays **Default**, using the model's default temperature when one exists, or the global temperature for its slider display. For provider requests that use the shared temperature settings, precedence is: 1. An explicit per-model temperature override. 2. The request's global temperature, when nonzero. 3. The model's built-in default, or omission of the parameter if no default exists. The displayed fallback and the eventual request value can therefore differ when a nonzero global temperature is set. Provider implementations can also omit temperature for models that do not support it. Temperature is not a reasoning-effort control. ### Token limits and other settings Model Config has no context-window or maximum-output-token control in the current implementation. Set custom-provider output limits on [Custom API](https://repoprompt.com/docs/1.6.0/settings/custom-api/#default-output-max-tokens), or use the provider-specific options in [OpenRouter](https://repoprompt.com/docs/1.6.0/settings/openrouter/#advanced-configuration). **Reset** beside Temperature does not clear streaming, Responses API, or diff preferences. Those switches save explicit on/off values independently. CLI-agent model and reasoning-effort choices are configured in [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/). --- ## OpenRouter (3) OpenRouter pane showing key controls, advanced configuration, registered models, and fetched models Manage the OpenRouter API key, fetch available models, and choose which models appear in RepoPrompt. Advanced configuration includes token limits and custom headers. Open **Settings → Models & Providers → OpenRouter**. This page controls API access and which OpenRouter models appear in RepoPrompt. Models in the screenshot are examples of a fetched catalog, not fixed defaults. For connection prerequisites, catalog references, capabilities, and account billing, see the [OpenRouter provider reference](https://repoprompt.com/docs/1.6.0/providers/openrouter/). The sections below describe this settings pane's controls. ### API key OpenRouter API key field with Change Key and Refresh and Delete Key controls Enter an OpenRouter key and choose **Validate & Fetch**. Once validated, the button reads **Change Key & Refresh**. **Delete Key** removes the stored credential. A green checkmark reports successful validation. ### Advanced Configuration Collapsed OpenRouter Advanced Configuration section Expand this section for provider settings and custom headers. **Include default OpenRouter models** controls inclusion of the app's default OpenRouter choices. **Use Custom Settings** exposes **Max Tokens**; its reset button restores **8192**. Custom headers are entered as a name/value pair and added with the plus button. Existing headers have individual delete controls. These are request settings, not additional model registrations. ### Registered Models Registered OpenRouter model with a removal button This list contains models you explicitly registered for RepoPrompt's model list. The trash button removes that registration; it does not remove the model from OpenRouter's service. ### Available Models Fetched OpenRouter model search, refresh button, and add controls **Refresh Model List** fetches the provider catalog. **Search fetched models…** filters it by model identifier. The UI displays the first 20 matching models, so use search for identifiers farther down the catalog. Use the plus button to register a model. Registered state changes the row's control so you can remove it again. Fetching a catalog does not automatically register every model in it. --- ## Chat Settings (Prompting) Chat Settings showing the built-in model, Oracle presets, planning prompt, edit mode, and temperature Configure the built-in chat model, the planning prompt, and named Oracle model presets exposed to MCP clients. Built-in chat settings are separate from Agent Mode configuration. Open **Settings → Prompting → Chat Settings**. These controls configure RepoPrompt's built-in chat and MCP Oracle choices. Agent Mode uses its own configuration. ### Recommendations Chat Settings scope explanation and Check Recommendations button **Check Recommendations** opens the recommendations flow for this window. Review the proposed setup there. The model and enabled options pictured on this page are examples, not recommendations for every task. ### Built-in Chat Model Built-in Chat Model picker Choose the model used by built-in chat. Available choices depend on configured providers and models. This picker does not replace your Agent Models role assignments. ### Oracle Model Presets Oracle Model Presets enable switch, availability count, and Manage Presets button **Use Oracle Model Presets for MCP** exposes named presets to MCP clients. **Manage Presets** opens [Model Presets](https://repoprompt.com/docs/1.6.0/settings/model-presets/). This is the same enable setting shown on the MCP Server page, so it does not need to be configured twice. If enabled with no presets defined, a fallback model picker is shown. If disabled, MCP uses the current Oracle model. The availability count is your current configuration, not a fixed preset limit. ### Chat Planning Prompt Chat Planning Prompt editor with Save and Reset to Default Edit the instructions used by built-in chat's **Plan** mode, then choose **Save** to persist your draft. **Reset to Default** restores the shipped planning prompt and refreshes the editor. Copy any custom text you want to keep before resetting. The text in the screenshot is the prompt being configured, not an instruction for someone reading this documentation. ### Advanced Chat Controls: edit mode Advanced Chat Controls with Diff, Whole, and None edit format choices Expand **Advanced Chat Controls** to choose the response format used outside Pro Mode: | Format | Behavior | | --- | --- | | **Diff** | Requests only the changes needed. | | **Whole** | Requests complete replacement file contents. | | **None** | Leaves chat unconstrained but does not support direct file editing through this format. | The picker is disabled for a model that cannot use diff editing; selecting such a model switches the edit format to Whole. ### Model Temperature Model Temperature slider and current numeric value The slider ranges from **0 to 1** in steps of **0.1**. Lower values request more focused output; higher values request more variation. The actual effect depends on the selected model and provider's support for temperature. --- ## Copy Prompt Order (Prompting) Copy Prompt Order showing section order, reset action, and duplicated instructions option Set the order of sections in copied prompts and built-in chat context, and choose whether user instructions also appear at the top. Agent Mode assembles its own context independently. Open **Settings → Prompting → Copy Prompt Order**. This affects copied prompts and built-in chat packaging. Agent Mode assembles its context separately. ### Section Order Draggable File Tree, File Contents, Git Diff, Meta Prompts, and User Instructions rows Drag the section rows to change their order. The default is: 1. **File Tree** 2. **File Contents** 3. **Git Diff** 4. **Meta Prompts** 5. **User Instructions** The order is saved when changed. Reordering does not enable a disabled content section or create missing content: disabled, empty, or unavailable sections are omitted during packaging. ### Reset to Default Reset to Default button for section order **Reset to Default** restores and saves the five-section order above. It does not change the separate duplicate-instructions setting. ### Duplicate User Instructions Enable duplicate at top checkbox and explanation **Enable duplicate at top** adds user instructions at the start of the prompt as well as at their normal ordered position. The gray **User Instructions (duplicate at top)** row previews this fixed copy and cannot be dragged. Turn the setting off to remove the extra top copy. The regular User Instructions row remains in the order you chose. No extra block is added when the instructions are empty. --- ## Workflow Presets (Prompting) Workflow Presets Copy tab showing Standard, Plan, Review, and Diff Follow-Up presets Manage reusable Copy and Chat presets that bundle prompts with Code Map, file-tree, and Git-diff options. These presets configure copied prompts and built-in chat rather than Agent Mode workflows. Open **Settings → Prompting → Workflow Presets**. **Copy** and **Chat** use separate preset collections. These presets package copied context or configure built-in chat; they do not configure Agent Mode workflows. ### Choose a collection and find a preset Copy and Chat selector, preset search, visibility filter, and Add Preset Switch between **Copy** and **Chat**, search by preset name, and filter **All**, **Shown**, or **Hidden**. Switching collection resets that list's search and filter state. The switch beside each preset controls its visibility in the quick menu, not whether the preset is currently applied. **Add Preset** creates a custom preset. **Clone** starts a copy you can customize; **Edit** opens the selected preset's configuration. ### Copy presets Copy preset rows with visibility switches, summary chips, Clone, and Edit Copy presets bundle prompt packaging choices, including Code Maps, file-tree and Git-diff inclusion, and stored prompts. The captured built-ins are **Standard**, **Plan**, **Review**, and **Diff Follow-Up**. Summary chips show non-default settings. **Map Auto** indicates automatic Code Map usage, and **Git** indicates Git content inclusion. The exact bundle can be inspected in the editor. ### Chat presets Workflow Presets Chat tab showing Chat, Plan, and Review Chat presets bundle the chat mode, optional model selection, context inclusion, and stored prompts. The pictured built-ins are **Chat**, **Plan**, and **Review**. Mode chips identify the chat mode; **Prompts: 1** reports one selected stored prompt, not one message in the conversation. Chat preset visibility controls and row actions ### Built-in and custom presets The lock and **Built-in** label identify shipped presets. They can have saved overrides; a modified built-in is marked accordingly. **Reset Overrides**, where available, restores its shipped configuration. Built-ins cannot be deleted. Custom presets have a delete action with confirmation. Hiding a preset keeps its saved configuration. Use [Copy Prompt Order](https://repoprompt.com/docs/1.6.0/settings/copy-prompt-order/) for the order of packaged sections, and [Chat Settings](https://repoprompt.com/docs/1.6.0/settings/chat-settings/) for the built-in model and planning prompt. --- ## Model Router (Router) Full Routing settings pane showing usage balancing, paid Fast tiers, Model Router, Auto effort, Jev configuration, routing preferences, and data sharing Configure how RepoPrompt chooses models and reasoning effort, balances connected plan usage, and connects to a decision service such as TypeSafe Jev. These controls serve different purposes. You can balance usage locally, use a service to choose a model, let it choose only reasoning effort, or combine these features. Open **Settings → Routing** in the version pictured here. Newer builds call this pane **Agent Decisions** and group the same features into **Model Router**, **Auto Effort**, **Usage Balancing**, and **Decision Services**. The screenshots show an example configuration, not recommended defaults; labels and placement can differ by build. | Feature | What it changes | When it applies | | --- | --- | --- | | Usage balancing | Can substitute a comparable model on another connected plan | Eligible new tasks; usage decisions stay on your Mac | | Model Router | Chooses a provider, model, and initial reasoning effort | New primary sessions and RepoPrompt-managed sub-agents | | Auto effort | Chooses reasoning effort for the model you explicitly selected | Eligible user turns, including settled follow-ups | ### Usage balancing Usage balancing switch, three strategies, Manage plan usage button, and background refresh option Use the [Plan usage controls](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#plan-usage) for usage readings, then turn on **Usage balancing**. **Manage plan usage…** opens CLI Providers, where those controls appear in the supported provider cards. If the coding runtime itself is not connected, complete [provider connection setup](https://repoprompt.com/docs/1.6.0/settings/cli-providers/#connection-and-setup-controls) separately. Balancing compares each plan's own remaining allowance and reset time. It does not treat a percentage of one plan as the same token capacity as a percentage of another. Only comparable models are substituted. Existing sessions and explicit MCP model pins keep their targets. Usage balancing is off by default. When enabled, the default strategy is **Even pace**: | Strategy | Behavior | | --- | --- | | **Only near limits** | Keeps the starting model unless its plan is at least 90% used. | | **Even pace** | Shifts work toward the plan with more unused weekly allowance relative to the time until reset. | | **Use expiring quota first** | Favors spare weekly allowance resetting within a day; otherwise balances weekly pace. | #### Background usage refresh **Refresh Claude usage in the background** requires a connected Claude usage source. Enabling it asks for consent to refresh through Claude Code's usage command and status line. It sends no model prompt, although Claude may retain normal session bookkeeping. While the app is active, task activity can trigger refreshes: at most once per **30 minutes**, with **12 checks per rolling day** for Claude, and at most once per **10 minutes** for Codex. There is no idle polling, and routing does not wait for a refresh. Connected usage also supports a startup check and manual refresh. Usage readings and balancing decisions stay on this Mac. This is separate from task excerpts sent when Model Router or Auto effort uses a decision service. :::note[Additional control in newer builds] **Override Model Router when usage is critical** is off by default. When enabled with usage balancing, it can restrict new tasks to one provider when a plan has at least 25% of its weekly allowance resetting within 48 hours, has 1.75 times the other plan's unused allowance relative to its remaining time, or the other plan is 90% used. Model Router then chooses within that provider, or is skipped if only one model qualifies. Primary sessions still require an eligible strong or frontier model; otherwise mixed routing remains in charge. ::: ### Paid Fast tiers Allow paid Fast tiers in automatic routing checkbox and cost explanation **Allow paid Fast tiers in automatic routing** is off by default. Enable it to make paid Fast variants eligible for automatic selection. These variants can consume plan allowance or credits more quickly. This setting does not change models you explicitly select yourself. ### Enable Model Router Model Router ready-to-enable status and switch, with new-session and fallback explanations First configure a decision service and connect a supported execution provider. **Ready to enable** means the service is ready and RepoPrompt can build an eligible set of models; it does not mean routing is already on. Turn on the switch here or use **Router** in the Agent Mode toolbar. The setting stays enabled across sessions until you turn it off. It applies to each new primary session and RepoPrompt-managed sub-agent. Existing sessions keep their established targets, and explicit MCP model pins are respected. Model Router chooses a model and then its initial reasoning effort, even if Auto effort is off. If routing is unavailable or returns no valid choice, the task continues with the current selection or its agent-role default. ### Auto effort Auto effort switch with eligibility, privacy, and manual-effort fallback explanations Turn on **Auto effort** to let the selected decision service choose reasoning effort before an eligible user turn. It keeps the selected model and works independently of the Model Router switch. Eligible turns use a supported model you explicitly selected, with more than one advertised effort level. This includes first MCP starts and follow-up messages sent after the preceding turn has finished. - Default selections, model aliases, and custom workflows keep manual effort. - A start already handled by Model Router keeps its routed effort. - Steering sent while a turn is running keeps the effort already in use; effort does not change between tool calls inside a turn. - If the service is unavailable or cannot return a valid choice, RepoPrompt uses manual effort. In newer builds, Auto Effort has its own **Decision service** selector. Changing Model Router's service does not change Auto Effort's service. For each eligible message, the service receives a short, best-effort-masked excerpt, the selected model ID, available effort choices, and the category of any selected built-in workflow. Workflow templates, attached files, tool results, and earlier conversation are not added. Masking can miss sensitive text; turn this feature off for private tasks. Effort changes can affect provider caching, and savings are not guaranteed. ### Routing service: Jev by TypeSafe Jev routing service with TypeSafe API key field, Validate and Save, Verify Saved Key, Remove Key, and verified status The pictured configuration uses **Jev by TypeSafe**. In newer builds, open its card under **Decision Services** and select it for the feature you want to use. 1. Enter your **TypeSafe API key**. 2. Choose **Validate & Save** to verify and save it. 3. After verification succeeds, enable Model Router or Auto effort. **Verify Saved Key** checks the stored credential again. **Remove Key** removes it; features that depend on that credential cannot make service decisions until a valid key is configured again. Key verification checks account access without sending a task. For actual decisions, Jev chooses a model and then effort for Model Router, or only effort for Auto effort. Each Jev decision request has a **five-second deadline** and is **not retried automatically**. The service card links to TypeSafe's API documentation and privacy policy. A verified key is only part of readiness: Model Router also needs an eligible execution model from a connected provider. ### Routing behavior Routing behavior with separate Primary sessions and Subagents provider preference menus The pictured **Primary sessions** and **Subagents** menus set provider preferences separately for the two session types. **Automatic (all connected)** allows all eligible connected providers. When you prefer a provider, routing uses it while it is authenticated and eligible. If it is unavailable, routing can fall back to another connected provider and resume the preference when the preferred provider reconnects. A preference does not establish a provider connection; manage that in [CLI Providers](https://repoprompt.com/docs/1.6.0/settings/cli-providers/). Newer builds place model availability and guidance under **Routing configuration**; the provider preference menus shown here may not be exposed in that layout. ### Custom guidance Custom guidance editor with a 1,000-character counter and Save Guidance button Use **Custom guidance** for preferences, such as “Prefer my connected coding provider for implementation.” Saved guidance shapes the service's starting recommendation among eligible models. It does not add unavailable models or bypass provider restrictions. With usage balancing enabled, RepoPrompt may subsequently choose a comparable model on another plan. Use the shared [Models reference](https://repoprompt.com/docs/1.6.0/providers/models/) for model identities, effort, and service tiers. The editor accepts up to **1,000 characters**. **Save Guidance** is available when the draft has changed and is within the limit. Clear the text and save to remove saved guidance. Guidance is sent with routing requests. Avoid putting credentials or private information in it. ### Automatic model selection Automatic model selection summary with current target count and connected Claude Code and Codex CLI providers RepoPrompt builds a curated set of eligible models from the connected Codex CLI and Claude Code catalogs, using quality, cost, capability, and availability information. It chooses the base model first, then that model's reasoning effort separately. [Agent Models](https://repoprompt.com/docs/1.6.0/settings/agent-models/) role settings are reference signals, not a fixed shortlist or forced default. Provider preferences constrain candidates, custom guidance shapes the recommendation, and local usage balancing may adjust it afterward. The **8 current targets** shown in the screenshot is an example, not a fixed limit or guaranteed list. Available targets depend on connected providers, model availability, and routing settings such as paid Fast eligibility. Newer builds show **Available models** and reasons for unavailable models under Routing configuration. ### What gets shared What gets shared explanation for routed task text, guidance, role references, and candidate descriptions For a new routed session, the decision service receives a short task excerpt, saved custom guidance, Agent Models role references, and descriptions of candidate providers, models, and effort levels. RepoPrompt attempts to mask sensitive information; for long tasks it uses an excerpt from the beginning and end. The full task goes to the selected execution agent. Attached files, workspace context, file paths, chat history, tool results, and execution-provider credentials are not automatically included in the routing request. Text you put directly into the task or guidance can still be shared, including sensitive information the masking misses. Auto effort sends the narrower message-and-effort information described above. Usage balancing itself stays local. Review the service's privacy policy and turn off service-based decisions for tasks you do not want excerpted to that service. --- ## Search Settings (Settings) Settings search field. Search Settings filters the app’s settings navigation by page title and related keywords. Matching pages appear in an alphabetical list; clearing the search restores the grouped navigation. --- ## Manage Presets (Workspaces) Manage Presets showing the current workspace and its empty preset list Manage saved workspace presets so you can restore reusable file selections and context configurations. Open **Settings → Workspaces → Manage Presets** for the workspace you want to organize. These presets restore workspace file selections. They are separate from [Oracle Model Presets](https://repoprompt.com/docs/1.6.0/settings/model-presets/) and [Workflow Presets](https://repoprompt.com/docs/1.6.0/settings/workflow-presets/). ### Workspace scope Existing Presets heading identifying the current workspace and numbered shortcuts The heading identifies the workspace whose presets you are editing. The first nine presets can be selected with **Option+Command+1–9**, unless you remapped them in [Keyboard Shortcuts](https://repoprompt.com/docs/1.6.0/settings/keyboard-shortcuts/). ### Create the first preset No presets found message directing you to the Presets menu The screenshot shows an empty list. Create a preset from the workspace's **Presets** menu after preparing the selection you want to reuse. The new-preset shortcut is **Option+Command+P** by default. ### Manage existing presets Once presets exist, each row offers switching, renaming, reordering, and deletion. Moving a preset up or down changes its position and therefore its numbered shortcut. A rename must contain non-whitespace text. Switching applies the preset and closes the management sheet. Deleting removes the saved preset from that workspace; it does not delete the selected project files. --- ## Manage Workspaces (Workspaces) Manage Workspaces with launch restoration, global storage, workspace creation, and library filters Organize the workspaces that group your project folders and context. Use this page to manage workspace entries and their associated folders. Open **Settings → Workspaces → Manage Workspaces**. A workspace groups project folders and saved RepoPrompt context; it is not the project directory itself. ### Restore workspaces on launch Restore workspaces on launch checkbox **Restore workspaces on launch** controls restoration of workspace windows when RepoPrompt starts. It does not create a new workspace or delete existing saved workspaces. ### Global Storage Location Collapsed Global Storage Location disclosure Expand this section to see the custom storage path or **Using Default Storage**. **Set Storage Location** chooses where RepoPrompt stores workspace data. **Reset to Default** appears when a custom location is configured. Changing this setting can migrate saved workspace data. It is separate from adding project folders to a workspace; it does not relocate your source-code directories. ### Create a New Workspace Workspace name, Add Folders, and Create Workspace controls Enter a **Workspace name**, choose **Add Folders** to select one or more directories, then choose **Create Workspace**. You can create from a name without folders, or from selected folders with an automatically supplied name. The button is disabled while both name and folder selection are empty. The app creates the workspace and requests a switch to it. Adding folders references existing directories; it does not copy the project files. ### Browse and manage the library Saved, Temporary, and All filters, workspace search, and Select control Use **Saved**, **Temporary**, or **All** to choose the workspace collection, and **Search workspaces…** to filter the list. **Select** opens the multi-selection controls for bulk actions. Existing workspace rows provide management actions such as renaming and hiding. Hidden workspaces remain recoverable. Deleting a workspace removes its saved state, tabs, and history; project folders are kept. Bulk deletion asks for confirmation and stops running work in affected workspaces. When duplicate records share project roots, newer builds can offer **Consolidate Duplicates…**. Its confirmation explains the backup and preservation of records still in active use. Workspace operations requested by clients can also be governed by [Workspace Approvals](https://repoprompt.com/docs/1.6.0/settings/workspace-approvals/). --- ## Why RepoPrompt (Version-1.6.0) Modern coding agents optimize for raw _convenience_: you type a prompt, and the agent immediately starts running shell commands and editing files. On small scripts, this feels magical. But on production codebases, unguided autonomous agents frequently hit a wall. RepoPrompt was explicitly architected to solve the **top failure modes in standard coding agents**: --- ### The Top Failure Modes in Standard Coding Agents #### 1. Context Rot & Hallucinations As conversation histories and file dumps expand past a model's effective sweet spot (64k–128k tokens), attention degrades sharply. When forced to reason inside a bloated context window filled with dead-end searches, models invent non-existent APIs, misremember types, and hallucinate implementations. - **How RepoPrompt addresses it:** The **Context Builder** discovery coding agent curates a focused selection toward a configurable context budget before follow-up Oracle analysis. This reduces search noise in the receiving model's context; nearly guaranteeing that every relevant file is found or that all reasoning is spent on the solution. See [Reliable, Useful Results](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#1-reliable-useful-results-context-over-convenience). #### 2. "Lost in the Middle" Forgetting Due to the U-shaped attention curve of transformers, models strongly weight instructions at the very beginning and very end of a prompt, but drop accuracy by 30%+ on vital constraints, types, or instructions buried in the middle of a large payload. **How RepoPrompt solves it:** 1. **Code Maps** are compact, Tree-sitter-generated summaries of a file's structure: types, method signatures, and `uses`/`used_by` relationships. They give the model an architectural overview and the interfaces of neighboring modules without filling the prompt with their full implementations. 2. **Line Slices** include selected line ranges from a file, so relevant functions or sections can appear together even when they are far apart in the source. Each slice retains its line numbers and can include a description, keeping implementation details available while leaving out unrelated code. 3. **Instruction Sandwiching** duplicates `` at both the top and bottom of assembled prompts when **Duplicate User Instructions at Top** is enabled. This places your requirements around the Code Maps and file contents, reinforcing them at both ends of the prompt. See [Advanced Context Engineering](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#2-advanced-context-engineering). #### 3. MCP & Tool Context Bloat Unbounded tool schemas (schema bloat) and voluminous raw tool outputs (like 500-line `grep` logs) flood the message buffer, burning token budgets and destroying prompt caches before the model even begins reasoning. - **How RepoPrompt solves it:** Strict separation of **Model Context** (curated workspace selection) from **Tool Context** (noisy command history), preloaded compact tool catalogs, non-blocking auto-selection, and disabling redundant native file tools. See [Model Context vs. Tool Context](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#3-model-context-vs-tool-context). #### 4. Multi-Turn Drift on Large Tasks As a single agent loops through dozens of iterative edits across 30+ turns, early constraints fade and small misinterpretations compound, causing the agent to wander away from the original goal or introduce conflicting changes. - **How RepoPrompt solves it:** A **Coordinator vs. Worker** architecture (Orchestrator Workflow) that breaks work into discrete 1–4 file work items for fresh sub-agents, coupled with the **Phase Gate Invariant** and an event-driven Overseer Mode **Oversight Auto-Wake**. See [Multi-Turn & Long-Horizon Operation](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#4-agents-operating-over-multiple-turns-and-longer-time-horizons). #### 5. Compaction Amnesia Naive token-limit compaction summarizes conversation history by focusing on _what was done_, frequently stripping negative side constraints (e.g., _"never modify the public API"_) and raw file details, causing post-compaction regression loops. - **How RepoPrompt solves it:** Agent-initiated `self_compact` at clean turn boundaries with dedicated `` continuation delivery, `oracle_chat_log` recovery, and `` handoffs. See [Compaction Architecture](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#5-compaction-and-preventing-compaction-amnesia). #### 6. Single-Model Blind Spots Forcing a single model to act as search engine, architect, and coder causes failures—especially when reasoning models (trained to "think then act" in consensus) are forced to execute tool calls mid-thought. - **How RepoPrompt solves it:** Tool-less **Oracle** reasoning paired with tool-native CLI agents, 4 specialized **Agent Roles** (`explore`, `engineer`, `pair`, `design`), parallel **Multi-Oracle Rosters** (up to 5 models) with reconciliation guidance, and local **Usage Balancing**. See [LLM Variations & Limitations](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#6-variations-and-limitations-of-large-language-models-llms). #### 7. Diff-Only Review Blindness Reviewing isolated Git patches without surrounding repository context creates high false-positive noise on style while completely missing breaking changes to callers one hop away from the diff. - **How RepoPrompt solves it:** Materialized selectable diff artifacts (`MAP.txt`, `all.patch`, per-file patches) combined with curated codebase context (callers, callees, and type contracts) in `/rp-review`. See [Codebase-Context Code Reviews](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#7-code-reviews-diff-only-vs-codebase-context-reviews). #### 8. Over-Engineered Simple Edits Triggering heavy multi-agent orchestration, full discovery pipelines, or multi-model planning for trivial, localized 1–3 file fixes wastes time, tokens, and developer patience. - **How RepoPrompt solves it:** Built-in **Fast Path** rules in `/rp-build` and `/rp-investigate`, the **~30-line / ≤ 2-file threshold** in `/rp-orchestrate`, and disabled-by-default `context_builder` on routine turns. See [When RepoPrompt Would Not Be Helpful](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#8-when-repoprompt-would-not-be-helpful). --- ### Explore the Architecture - Learn how to start your first task in [Getting Started](https://repoprompt.com/docs/1.6.0/overview/getting-started/). - Walk through the three-stage discovery pipeline in [How It Works](https://repoprompt.com/docs/1.6.0/overview/how-it-works/). - Dive deep into the source code implementation and the **Summary Matrix** in [How It (Really) Works](https://repoprompt.com/docs/1.6.0/overview/how-it-really-works/#summary-matrix-problem-vs-repoprompt-architecture). --- ## Create and Use a Worktree (Worktrees) A worktree gives a coding task its own checkout. Before starting, open the intended Git repository and decide which committed starting point the task needs. A new worktree does not copy your main checkout's uncommitted tracked edits. ### Start a task in a new worktree 1. Open a new session and choose **Work locally** above the message editor. 2. Under **Start in**, select **New worktree**. This stages the choice; creation happens when you first send. 3. Write a focused task with an observable result. For example: “Fix the empty-state layout and verify it at narrow widths. Work in the new worktree; leave the main checkout unchanged.” 4. Send, then inspect the execution-location indicator. Check the path and branch or detached commit before assuming that work is isolated. If creation reports an error, resolve it before asking for edits. Start in picker offering the workspace checkout, a new worktree, and existing worktrees For a particular base revision or branch configuration, use the supported creation options exposed by the [manage_worktree tool](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#manage_worktree), and inspect the returned descriptor. Do not infer the base from the task's name. ### Continue in an existing worktree Choose an entry under **Existing worktrees**. Rows identify the branch or detached commit, worktree name, and path. A prunable entry is unavailable. “No other worktrees available” means the picker has no alternative checkout to offer; it does not create one automatically. Changing an established session's location restarts its provider context and can require stopping an active turn. Follow [Execution Location](https://repoprompt.com/docs/1.6.0/sessions/execution-location/#change-an-existing-sessions-location) before moving an ongoing task. ### Prepare local setup Committed files come from Git. Dependencies, local configuration, and development services may need separate preparation. To copy selected ignored setup files into app-managed worktrees, put narrow patterns in `.worktreeinclude` at the main repository root: ```gitignore # Copy only these files if Git already ignores them. .env.local config/development.json ``` The include file does not make a file ignored. Add the appropriate ignore rules separately if needed. Automatic session creation uses the ignored-only default; see [copying rules and exclusions](https://repoprompt.com/docs/1.6.0/worktrees/#copying-local-ignored-files-with-worktreeinclude) for the MCP untracked-file opt-in and external-path limitations. ### Finish and preserve the result Run the project's relevant checks in the task's checkout and inspect the actual changes. Commit the intended source changes before requesting a RepoPrompt worktree merge. Stopping a coding agent, closing a conversation, or retiring an overseer lane does not merge its work. Keep the checkout until its work is integrated or deliberately preserved elsewhere. Unbinding a session is a routing change, not worktree deletion. Continue with [Review and Merge](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/). --- ## Worktrees (Worktrees) A **Git worktree** is a separate working directory attached to the same repository. Each checkout has its own files, index, and checked-out branch or commit, while sharing Git history. You can work on different branches at once without repeatedly switching branches in your main checkout. RepoPrompt CE creates worktrees through Agent Mode and the MCP `manage_worktree create` tool, with optional copying of local setup files. ### Start with a separate checkout Use a worktree when parallel coding tasks could edit the same files, or when you want to try an approach without changing your main checkout. Separate sessions alone do not isolate files. Follow [Create and use a worktree](https://repoprompt.com/docs/1.6.0/worktrees/create-and-use/) to choose a location and prepare its local setup. When the task is complete, follow [Review and merge](https://repoprompt.com/docs/1.6.0/worktrees/review-and-merge/) to bring committed changes into the intended target checkout. Starting a worktree does not automatically integrate its results. RepoPrompt can create worktrees for MCP tools and Agent Mode. App-managed worktrees are placed in the `.repoprompt-worktrees` container unless you deliberately choose an external path. A worktree gives a coding agent an isolated checkout while the main checkout and other worktrees remain available for parallel work. It does not isolate external services, databases, credentials, or processes outside that checkout. On APFS, RepoPrompt automatically attempts copy-on-write cloning when the new worktree starts from the same tree as a clean source checkout on the same volume. Tracked files initially share disk blocks with the source and consume additional space only when changed. RepoPrompt verifies the cloned checkout by refreshing its index and requiring a clean Git status. It uses an ordinary Git checkout when the source is dirty, the requested base differs, or repository features such as sparse checkout, submodules, Git LFS filters, special line-ending or encoding attributes, hooks, path collisions, different volumes, or an external destination make cloning unsuitable. Set `clone_tracked_checkout=false` when checkout speed matters more than disk space. ### Copying local ignored files with `.worktreeinclude` Add `.worktreeinclude` at the main repository root using `.gitignore` patterns. Matching ignored files are copied; tracked edits are excluded. MCP creation can explicitly include matching untracked files with `copy_worktree_include_untracked_files=true`. Patterns support comments, directory rules, globs, and `!` negations. With the default ignored-only behavior, Git must already treat a file as ignored, and the final matching `.worktreeinclude` rule must include it. The explicit MCP opt-in above also permits matching non-ignored untracked files. RepoPrompt copies regular files individually, using APFS clones when available and byte copies otherwise. It does not copy tracked files, ordinary untracked files by default, symlinks, unsafe paths, or files that would overwrite an existing destination. Copying is limited to RepoPrompt-managed worktrees. An external worktree created with `allow_external_path=true` is still created, but `.worktreeinclude` files are not copied there. Successful copying is silent; if a copy cannot be completed, the worktree remains and `manage_worktree create` may report a warning. Agent Mode and descriptor-only flows record production-safe diagnostics. ### Be careful with broad patterns There is no copy-size or file-count limit. Keep patterns narrow to avoid duplicating large caches. For implementation details, see the [worktrees guide in the application source repository](https://github.com/repoprompt/repoprompt-ce/blob/main/docs/worktrees.md). --- ## Review and Merge (Worktrees) A worktree merge integrates committed history into another checkout in the same repository. It does not copy an unfinished working directory. The **source** is the session-bound worktree supplying commits; the **target** is the checkout that receives them. ### Prepare both checkouts Finish or stop work that could change either checkout. Review and commit the intended source edits, and ensure the target is clean. RepoPrompt blocks merges when either checkout is dirty, either already has a merge in progress, the repositories differ, or the source and target are the same worktree. If the source commit is already included in the target, there is no new source history to merge. If the session has bindings for several repository roots, identify which repository supplies the source. A session name alone does not identify a checkout. ### Request a preview Ask the coding agent to use the worktree merge tools and name the target explicitly. For example: > Preview merging this session's committed worktree changes into the main workspace checkout. Report the source and target paths, commits, and any blockers. Wait for my review before applying the merge. The [manage_worktree tool](https://repoprompt.com/docs/1.6.0/mcp-server/mcp-tools/#manage_worktree) separates `preview` from `apply`. A preview does not modify the repository. Its operation ID identifies the prepared operation; applying requires the corresponding confirmation or routed UI approval. ### Read Worktree Merge Review When routed through the session's review interface, the card shows source and target endpoints, a merge graph, preflight information, and available diff artifacts. Check the paths as well as branch names. The inline diff is a bounded excerpt; inspect the referenced artifacts or repository changes when the excerpt is incomplete. Choose **Merge** to approve the prepared operation or **Cancel** to dismiss it without applying. If either checkout changed after preview, the operation can become stale. Request a fresh preview and review the new state rather than reusing old approval. ### Resolve conflicts in the target Conflicts belong to the **target worktree**, whose path appears on the conflict card. Open that checkout, inspect Git status, resolve the listed files, and stage the resolutions there. Then choose **Continue after resolving**. When no conflicts remain, continuing creates the merge commit in the target. Choose **Abort merge** if you intend to discard the in-progress merge in the target. This is different from cancelling a preview before mutation. If continuing or aborting fails, read the reported error and inspect that target checkout before retrying. ### Verify the integrated result After completion, inspect the target's Git history and diff and run the relevant checks there. A completed merge does not publish a branch or establish that tests pass. Keep the source checkout until you have verified the result; closing or unlinking the session is not evidence that integration succeeded. --- ## API Providers (Ai-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 — RepoPrompt supports [six compatible CLIs](https://repoprompt.com/docs/providers/overview/) 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](https://repoprompt.com/docs/providers/overview/)) to access GPT-5.5. ::: ### Supported Providers RepoPrompt 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 1. Open **Settings** (`⌘+,`) 2. Go to **API Settings → API Providers** 3. Find your provider and enter your API key 4. Click **Validate & Save** 5. A green checkmark confirms the key is valid ### Getting API Keys #### Anthropic (Claude) 1. Go to [console.anthropic.com](https://console.anthropic.com/settings/keys) 2. Create an account or sign in 3. Navigate to Settings → API Keys 4. Create a new key and copy it #### OpenAI (GPT) 1. Go to [platform.openai.com](https://platform.openai.com/api-keys) 2. Create an account or sign in 3. Navigate to API Keys 4. Create a new secret key and copy it #### Google (Gemini) 1. Go to [aistudio.google.com](https://aistudio.google.com) 2. Sign in with your Google account 3. 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: 1. After validating your API key, look for the "Custom Model" field 2. Enter the model identifier (e.g., `claude-3-5-sonnet-latest`) 3. Click "Save Model" 4. 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: 1. Go to Settings → API Providers 2. Click "Sign in with GitHub" 3. Authorize RepoPrompt 4. 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: 1. Install Ollama from [ollama.com](https://ollama.com) 2. Pull a model: `ollama pull llama3.1` 3. In Settings → API Providers, find "Local Model Settings" 4. The default URL is `http://localhost:11434` 5. Click "Validate" to fetch available models 6. Select your model from the dropdown --- ## CLI Providers (Ai-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 RepoPrompt'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 RepoPrompt 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. 1. Install Claude Code: `npm install -g @anthropic-ai/claude-code` 2. Login: `claude login` 3. In RepoPrompt, go to Settings → CLI Providers 4. Click "Connect" next to Claude Code 5. 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](https://repoprompt.com/docs/providers/overview/) for details. #### Codex CLI (OpenAI Plus/Pro) Use OpenAI models through your ChatGPT Plus or Pro subscription. 1. Install Codex: `npm install -g @openai/codex` 2. Login: `codex login` 3. In RepoPrompt, go to Settings → CLI Providers 4. Click "Connect" next to Codex CLI 5. 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. 1. Install Gemini CLI: `npm install -g @google/gemini-cli` 2. Login: `gemini login` 3. In RepoPrompt, go to Settings → CLI Providers 4. Click "Connect" next to Gemini CLI 5. 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. 1. Install Cursor and ensure `cursor` is available on your PATH 2. Login to your Cursor Pro or Business account 3. In RepoPrompt, go to Settings → CLI Providers 4. Click "Connect" next to Cursor CLI 5. Test the connection — available models will be discovered automatically ### Using CLI Providers Once connected, CLI providers appear as model options throughout RepoPrompt: - **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. ::: --- ## 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 1. Open **Settings** (`⌘+,`) 2. Go to **API Settings → Custom API** 3. 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 4. Click **Validate & Save** ### Configuration Examples #### vLLM Server ```text Base URL: http://localhost:8000/v1 API Key: (leave empty for local) Model: meta-llama/Llama-3.1-70B-Instruct ``` #### Text Generation Inference ```text Base URL: http://localhost:8080/v1 API Key: (leave empty for local) Model: tgi ``` #### Company Internal API ```text Base URL: https://ai.internal.company.com/api/v1 API Key: your-internal-api-key Model: company-gpt-4 ``` ### OpenAI Custom Base URL You can also customize the OpenAI base URL for proxies without using a full custom provider: 1. Go to Settings → API Providers 2. Under OpenAI, click "Advanced (Custom Base URL)" 3. Enter your custom endpoint 4. 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 --- ## OpenRouter (Ai-providers) 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](https://repoprompt.com/docs/providers/overview/) 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 1. Create an account at [openrouter.ai](https://openrouter.ai) 2. Add credits to your account 3. Go to Keys → Create Key 4. Copy your API key 5. In RepoPrompt: Settings → API Settings → OpenRouter 6. 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. ::: --- ## Classic Version 1.0 ### Classic Edition Version 1.0 Series The Classic Edition 1.0 series marked RepoPrompt's official release, leaving beta with stability improvements, presets, and foundational chat features. #### Key Features in 1.0 - **Official Release** - First production-ready version, leaving beta - **File Presets** - Save and switch between selected file sets with hotkeys - **Plan/Act Mode** - Toggle between planning and acting in chat - **Model Temperature** - Configure temperature settings per model - **Custom Planning Prompt** - Customize the planning prompt - **Deepseek V3** - OpenRouter support for Deepseek's latest - **Azure Reasoning Models** - Support for Azure-hosted reasoning models - **Markdown Rendering** - Chat messages render with markdown - **Sandbox Removal** - Enables future CLI event handling
View detailed changelog (1.0 - 1.0.26) ##### 1.0.26 - App terminates properly when closing last window - New chat hotkey (cmd+shift+n) works in chat view - Fixed slow typing and text selection issues ##### 1.0.24 - Presets for quick file selection switching - Hotkey support for preset navigation ##### 1.0.19 - Markdown rendering in chat - Max output token options for custom providers - Fixed temperature errors for o-series models ##### 1.0.16 - Model temperature configuration - Prevent diff edit models from using rewrite - Deepseek V3 via OpenRouter - Custom planning prompt ##### 1.0 - Official Release - First official release, leaving beta - Collapse all folders hotkey (cmd+option+c) - Workspace restore from sandbox migration - App sandbox removed for CLI support ##### Other 1.0.x releases Versions 1.0.1-1.0.15, 1.0.17-1.0.23, 1.0.25 include plan/act toggle, pro edit improvements, Azure reasoning model fixes, path resolution improvements, hotkey fixes, and stability improvements.
--- ## Classic Version 1.1 ### Classic Edition Version 1.1 Series The Classic Edition 1.1 series introduced Context Builder for AI-powered file recommendations, Pro Edit with parallel file changes, and major chat performance improvements. #### Key Features in 1.1 - **Context Builder** - Combine codemaps and LLMs to produce relevant file recommendations - **Pro Edit Parallel Changes** - Split changes within a file to tackle complex edits in parallel - **File Checkpoints** - Capture and restore file states across app reloads - **File Renaming** - Rename files (treated as create + delete) in chat and apply - **Fireworks AI Provider** - Built-in support for Fireworks - **Native File Tree** - Complete rebuild for better large repository scaling - **Plan/Act Toggle** - Switch between planning and acting modes in chat - **O3/O4 Mini Support** - OpenAI's compact reasoning models - **Prompt Ordering Menu** - Experiment with element order in prompts - **Token Usage Display** - Per-message and delegate edit token counts
View detailed changelog (1.1.0 - 1.1.20) ##### 1.1.20 - May 2, 2024 - Fixed state caching issues with empty files or excess deletions - Improved delegate edit error handling ##### 1.1.16 - April 28, 2024 - Pro edit can split changes within files for parallel processing - File checkpoints with persistence across reloads - File renaming support - Fireworks AI provider - Per-message token usage display ##### 1.1.11 - April 18, 2024 - Complete native file tree rebuild for large repos - Fuzzy search with space-as-wildcard - Font sizing options - Prompt export/import ##### 1.1.10 - April 16, 2024 - O3 and O4 mini support via OpenAI - Prompt ordering menu - User instruction sandwiching ##### 1.1.0 - Major Release - Context Builder for AI-powered file recommendations - Parallel AI queries for large codebases - Save recommendations as presets - Optimized chat streaming performance ##### Other 1.1.x releases Versions 1.1.1-1.1.9, 1.1.12-1.1.15, 1.1.17-1.1.19 include Gemini 2.5 Pro Exp, Sonnet Thinking MAX, o1 Pro support, URL scheme improvements, chat rendering optimizations, and stability fixes.
--- ## Classic Version 1.2 ### Classic Edition Version 1.2 Series The Classic Edition 1.2 series introduced XML Architect Mode for complex multi-file edits and enhanced support for reasoning models across providers. #### Key Features in 1.2 - **XML Architect Mode** - Use external chat model to architect complex multi-file edits, then delegate to pro edit model - **O3 Pro Support** - Full support for OpenAI's o3-pro reasoning model - **Responses API** - OpenAI reasoning models display reasoning summaries - **Gemini 2.5 Updates** - Flash 2.5 and Pro 2.5 GA releases, Flash Lite Preview - **Reasoning Effort Variants** - Configure effort levels for o3 models - **Chat Message Actions** - Accept all and restore checkpoint buttons - **Mention Menu** - Experimental @ mentions in chat - **Model Override UI** - Per-model Responses API configuration
View detailed changelog (1.2.0 - 1.2.29) ##### 1.2.29 - June 18, 2024 - Fixed token usage display for OpenAI reasoning models - Optimized temperature defaults (0.7 Gemini Pro 2.5, 0.6 Deepseek R1) - Fixed Azure reasoning model timeouts ##### 1.2.27 - June 16, 2024 - All OpenAI reasoning models use Responses API with summaries - Enhanced O3 Pro behavior in chat ##### 1.2.26 - June 13, 2024 - Accept all and restore checkpoint buttons on chat messages - Fixed Model overrides UI ##### 1.2.23 - June 10, 2024 - Full o3-pro API support - Experimental mention menu (beta) ##### 1.2.0 - May 4, 2024 - XML Architect Mode for complex multi-file edits - File count badge in selected files view ##### Other 1.2.x releases Versions 1.2.1-1.2.22, 1.2.24-1.2.25, 1.2.28 include Gemini model updates, reasoning effort variants, preset naming, improved diff generation, conflict detection, and various stability fixes.
--- ## Classic Version 1.3 ### Classic Edition Version 1.3 Series The Classic Edition 1.3 series introduced the MCP Server for external tool integration, Claude Code as a provider, and major improvements to chat and editing workflows. #### Key Features in 1.3 - **MCP Server** - Connect external tools like Claude Code and Cursor to interact with RepoPrompt - **Claude Code as Provider** - Use your existing Claude Code installation as an API provider with MAX subscription - **MCP Chat Tools** - External agents can invoke built-in chat for planning, debugging, and engineering - **MCP File Operations** - Create, delete, move, and edit files via MCP - **Git Integration** - Select unstaged files and copy diffs for code reviews - **Groq Provider** - Support for Kimi K2 model - **Grok 4 Support** - Added xAI's latest model - **PHP Codemaps** - Added PHP language support for code structure - **Delegate Edits** - Refined approach for more reliable file edits - **Shift Select** - Faster bulk file selection in file tree
View detailed changelog (1.3 - 1.3.50) ##### 1.3.19 - July 17, 2025 - Improved Claude Code stability for large prompts - Model parameter selection (opus vs sonnet) - New built-in prompts: MCP Pair Program and MCP Claude Code - CodeMap cache reset button ##### 1.3.17 - July 16, 2025 - Claude Code as an API provider - Groq provider with Kimi K2 support - New MCP search tool for efficient codebase navigation ##### 1.3.15 - July 11, 2025 - PHP codemap support - Revamped JavaScript/TypeScript codemaps - Grok 4 model support ##### 1.3.13 - July 4, 2024 - MCP Chat tools - Claude gets a pair programmer - Unified diffs for tracking changes ##### 1.3.12 - July 2, 2024 - MCP file operations (create, delete, move, edit) - Multiple search/replace in single tool call - Tool call cancellation ##### 1.3 - June 23, 2024 - MCP Server for external tool integration - Search, codemaps, and planning via Claude Code or Cursor - UI control: update file selection and instructions ##### Other 1.3.x releases Versions 1.3.1-1.3.11, 1.3.14, 1.3.16, 1.3.18, 1.3.20-1.3.50 include git diff support, hierarchical ignore files, multi-window MCP mode, improved diff generation, memory optimizations, and numerous stability fixes.
--- ## Classic Version 1.4 ### Classic Edition Version 1.4 Series The Classic Edition 1.4 series introduces the Presets system, macOS Tahoe support, git integration, and major performance optimizations. #### Key Features in 1.4 - **Presets System** - Quickly jump to optimized app configurations for different workflows - **macOS 26 Tahoe Support** - Revamped visual design with native components - **Git Diffs in Prompts** - Include git diffs from all files or your selection for code reviews - **GPT-5 Pro Support** - Full support for OpenAI's latest reasoning models - **z.AI Provider** - Added support for z.AI models - **MCP Chat Model Presets** - Configure models for chat MCP tools with descriptions - **Multi-Window MCP Mode** - Access different workspaces in parallel - **Hierarchical Ignore Files** - Support for .cursorignore and nested gitignore - **Codex CLI 1-Click Install** - Simplified setup for Codex integration
View detailed changelog (1.4.0 - 1.4.27) ##### 1.4.27 - October 7, 2025 - Added support for GPT-5 Pro - Performance improvements ##### 1.4.17 - September 26, 2025 - macOS 26 Tahoe support with native components - File loading optimization for large binary files ##### 1.4.0 - August 25, 2025 - Presets system for streamlined workflows - Simplified chat view presentation ##### Other 1.4.x releases Versions 1.4.1-1.4.16, 1.4.18-1.4.24, 1.4.26 include z.AI provider, GLM 4.6 support, git diffs in prompts, multi-window MCP mode, hierarchical ignore files, Codex CLI 1-click install, improved file tree auto mode, smart caching, and numerous stability fixes.
--- ## Classic Version 1.5 ### Classic Edition Version 1.5 Series The Classic Edition 1.5 series introduces Background Mode with menu bar control, tab-bound chats with concurrent streaming, Context Builder 2.0 with agentic discovery and auto plan generation, compose tabs for parallel workflows, interactive CLI, and support for new CLI providers. #### Key Features in 1.5 - **Integrated Sidebar Terminal** - Launch terminal sessions directly in the sidebar with support for AI agent CLIs or a plain shell - **Background Mode** - App stays active when windows are closed, with a menu bar icon for quick restore or quit - **Tab-Bound Chats** - Chats are now bound to tabs for easier session management, with support for multiple concurrent streaming conversations - **Interactive CLI** - Command-line interface for MCP tools with shell aliases, command history, output redirection, exec mode, and one-click PATH installation - **Context Builder 2.0** - Agentic context building using Claude Code or Codex to automatically select files, codemaps, and slices within a token budget - **Auto Plan Generation** - Context builder can automatically generate an implementation plan after exploration - **Discovery Clarifying Questions** - Agent can ask clarifying questions during context building for better results - **Reasoning Display** - See the model's thought process during plan generation in a collapsible section - **Compose Tabs** - Work on multiple tasks in parallel with independent prompts and file selections per tab - **Pro Edit Agent Mode** - Use Claude Code or Codex with MCP tools to generate edits in parallel with higher accuracy - **Claude Code Slash Commands** - One-click installation of RepoPrompt MCP commands from settings - **MCP Builder Preset** - Four-phase workflow: quick scan, context building, chat refinement, and implementation - **UNIX Socket MCP Transport** - Replaced network communication for better performance, no Local Network permission needed - **Codex CLI as API Provider** - Use OpenAI models through your Plus or Pro plan via Codex CLI - **Gemini CLI Support** - Use Gemini CLI for chat, discovery & delegate edits - **Context Builder as MCP Tool** - Run discovery directly from external agents - **Tab Management via MCP** - Control tabs and workspaces programmatically - **GPT-5.2 & Opus 4.5 Support** - Latest OpenAI and Anthropic models with extended reasoning variants - **Chat Message Forking** - Edit user messages to create conversation branches - **Model Recommendation Engine** - Automatic model suggestions based on your current workflow and configuration - **File Actions** - Open files in default apps, copy absolute paths, and reveal in Finder from file tree - **Prompt Export** - Export complete clipboard content to a file via MCP tool, plus ChatGPT Prompt Export command for generating prompt files for GPT Pro models
View detailed changelog (1.5 - 1.5.68) ##### 1.5.68 - January 16, 2026 - **New:** OpenCode CLI installer - Install MCP server configuration for OpenCode CLI from settings - **New:** claude-rp CLI wrapper - An alias for running Claude Code with RepoPrompt's MCP tools, disabling clashing built-in tools - **New:** MCP Tools settings - New settings tab to toggle individual MCP tools per-window with search (Pro) - **New:** Window management for MCP/CLI - MCP and CLI can now automatically open and close windows when creating, switching, or deleting workspaces - Cleaned up MCP settings UI - Smarter CLI command management - respects user-removed commands and won't re-add them on updates - MCP question UI - questions asked during MCP operations now appear and work consistently - Fixed terminal crash during long terminal sessions ##### 1.5.67 - January 13, 2026 - Fixed issue with Gemini CLI's stream getting cutoff mid-response - Fixed issue with OpenAI API where heartbeats were causing decode errors ##### 1.5.66 - January 12, 2026 - **New:** Built-in Interview Prompt - New interview prompt for Context Builder to guide implementation planning - **New:** Pinnable Context Builder Prompts - Pin your favorite prompts for quick access (shown first in the list) - **New:** Collapsible Instructions Panel - Collapse the instructions panel for a cleaner prompt view - Improved MCP and CLI tool schemas - Improved CLI documentation and help output - More flexible CLI invocation with support for various argument formats - Enhanced Discovery Agent tool descriptions for better structure in agent/planner workflows - Improved Discovery Agent prompt for smarter file selection - Better terminal stability with smoother resizing and scroll restoration - Fixed long-running MCP tool calls disconnecting prematurely - Fixed terminal keyUp recursion crash - Fixed chat sessions overwriting compose tab prompt IDs - Fixed workspace refresh issues with stale indices ##### 1.5.65 - January 8, 2026 - Fixed tabs getting wiped on update ##### 1.5.64 - January 8, 2026 - **New:** Customizable Context Builder Prompts - Create and save custom prompts for the context builder to tailor how context is discovered for different tasks - **New:** Remote Git Branches - View and select remote branches alongside local ones; remote refs are now auto-fetched to stay current - **CLI:** New --json flag for scripting, better flag parsing, and cleaner command syntax for the builder command - New compose tabs now preserve your current file tree expansion instead of collapsing everything - Fixed issue with context builder state getting wiped on tab switches - Fixed git diff not being included when it was supposed to - Fixed issue with model presets getting wiped ##### 1.5.63 - January 7, 2026 - **New:** Integrated Sidebar Terminal - Launch terminal sessions directly in the sidebar with support for AI agent CLIs (Claude Code, Gemini CLI, etc.) or a plain shell - Code review mode now available via MCP tools - Changed default chat\_send mode to "chat" for safer initial MCP interactions - Fixed tools timing out after 15 minutes, preventing long context builder runs - Fixed workspace tooling not working reliably from the CLI - Fixed folder picker sometimes blocking the app - Improved performance when expanding large workspaces ##### 1.5.62 - January 5, 2026 - **CLI:** Tab targeting - Target specific compose tabs via CLI flags for precise multi-window control - **CLI:** Copy preset management - List and select copy presets directly from CLI and MCP - **CLI:** Progress notifications - Shows progress updates during lengthy tasks to prevent timeouts - **CLI:** Better multi-window guidance - Help output includes contextual routing tips when multiple windows are detected - Shift+Command+W shortcut to close the active window quickly - Improved tab cleanup - Running tasks are properly stopped when tabs are closed ##### 1.5.61 - January 1, 2026 - **New:** Background Mode - App stays active when you close windows, with a menu bar icon for quick restore or quit - **New:** Chat UX Revamp - Chats are now bound to tabs for easier session management, with support for multiple concurrent streaming conversations - **New:** Prompt Export Tool - New MCP tool to export complete clipboard content to a file - **New:** ChatGPT Prompt Export Command - New rp-oracle-export prompt to run context builder and export a prompt file for use with GPT Pro models on ChatGPT - **New:** File Actions - Open files in default apps, copy absolute paths, and reveal in Finder from file tree and selected files - Improved cache cleanup to remove stale code maps for deleted folders ##### 1.5.60 - December 22, 2025 - **New:** CLI command installation - Added rp-investigate and rp-build CLI commands for easier use in Codex and Claude Code environments - **New:** Per-tab auto-plan setting - Auto-generate plan now works per-tab with workspace fallback for finer control - **CLI:** Raw JSON output mode - New --raw-json flag returns pure JSON responses for easier scripting and automation - **CLI:** Output redirection - Commands now support shell-like > (overwrite) and >> (append) redirection to files - **CLI:** Enhanced command parsing - Extended flags and options across search, selection, file operations, and chat commands - **CLI:** Smarter path resolution - Improved handling of folder paths, workspace-relative paths, and root aliases - Better codemap management - Files without codemap support are now properly filtered and reported instead of causing errors - Improved custom text input UI - Styled as a selectable option with visual feedback for better consistency - Fixed codemap demotion incorrectly removing files that don't support codemaps - Fixed path resolution edge cases in multi-root workspaces ##### 1.5.59 - December 19, 2025 - **Fixed truncation of tool descriptions and workspace names** - Some content was incorrectly being cut off in command output and UI prompts - **Improved app quit stability** - Fixed potential crashes when quitting the app by preventing duplicate termination attempts - Cleaner CLI error messages ##### 1.5.58 - December 19, 2025 - **Improved chat bubble performance** - Optimized text layout to reduce unnecessary UI updates and improve scrolling smoothness - **Updated MCP Builder workflow** - Consolidated and improved guidance for context building and implementation workflows - Fixed inconsistent CLI naming in help menu ##### 1.5.57 - December 18, 2025 - **Major:** Interactive CLI - New command-line interface for exploring and executing MCP tools directly from terminal. Includes shell-like aliases, command history, output redirection, timing info, typo suggestions, tool group filtering, and exec mode for scripting. Easy one-click PATH installation from Settings. - **New:** MCP Slash Commands - Key prompts (rp-build, rp-investigate) now automatically exposed to any connected MCP client as slash commands - **New:** Path Paste Menu - Quickly select files from a blob of text containing paths, available in More Actions - **New:** OpenAI Service Tier setting for Responses API - Improved tooltip positioning on hover and scroll - Enhanced window/tab routing for workspace tools - Auto-apply recommendations for new workspaces - Fixed infinite layout loop crashes in search file tree - Fixed recommendation invalidation issues - Improved MCP socket connection stability and handling - Misc UI fixes ##### 1.5.56 - December 11, 2025 - Improved GPT-5.2 Pro support - Added background job support for Azure OpenAI and OpenAI providers, enabling stable use of GPT-5.2 Pro and other models that require asynchronous processing - Improved text editor stability - Fixed TextKit issues that could cause crashes or visual glitches during editing - Improved app stability - Various fixes to prevent crashes and improve reliability - Fixed high CPU usage - Resolved performance issue where the Discover Agent view could cause high CPU usage during extended runs ##### 1.5.55 - December 11, 2025 - **New:** GPT-5.2 support with XHigh reasoning variants - Context builder now shows your actual codemap preset settings alongside its normalized view - Background plan generation now runs independently per tab, enabling concurrent plans - Improved socket connection stability with better race condition handling - Fixed context builder and manage\_selection tools not properly providing feedback when using codemap modes other than "auto" ##### 1.5.54 - December 10, 2025 - **New:** Claude Code slash commands with one-click installation from settings - **New:** "MCP Builder" preset with four-phase workflow: quick scan, context building, chat refinement, and implementation - **New:** Discovery agent can now ask clarifying questions during context building (optional setting) - Gemini CLI integration now uses persistent settings file for better reliability - Auto-focus window and switch to compose tab when clarifying questions are pending - Fixed context bleed between tabs during discovery runs - Fixed text field scrolling issues on Intel Macs - Fixed potential MCP socket connection errors on systems with restrictive firewalls ##### 1.5.53 - December 8, 2025 - Overhauled MCP transport architecture - replaced all local network communication with high-performance UNIX sockets, significantly reducing CPU overhead and improving connection stability - Removed network permission requirements - the app no longer needs Local Network access, eliminating authorization popups when connecting to MCP servers - Improved CLI provider initialization - changed where CLI providers are initialized to avoid unnecessary access popups for Apple Music and Documents folders - More reliable MCP connections - added robust reconnect logic with client identity caching, ensuring consistent connections during session recovery ##### 1.5.52 - December 7, 2025 - Temporarily disabled filesystem transport due to CPU overhead - reworking the solution - Fixed tab related race conditions causing issues with MCP powered context building - Fixed context builder text state issues - Better handling of discovery runs where the agent doesn't leave a handoff prompt - Minor UI improvements ##### 1.5.51 - December 6, 2025 - Fixed tab state not working correctly for context builder view ##### 1.5.50 - December 6, 2025 - **New:** Reasoning/thinking display for plan generation - see the model's thought process in a collapsible section - **New:** Plan preset locking ensures consistent settings during context builder operations - Better cancellation support for async operations - more responsive UI when stopping queries - Improved streaming with proper cleanup to prevent hangs - Enhanced tab busy state indicators for plan generation - Fixed potential resource leaks during streaming cancellation - Fixed file deletion detection ##### 1.5.48 - December 5, 2025 - Further improved CPU utilization - found high churn areas that appeared after many hours of uptime - Improved UI for active discovery tabs - Fixed regressions in MCP connection stability ##### 1.5.47 - December 5, 2025 - Reworked some file tree logic to optimize UI churn for extremely large repos - Reworked MCP lifecycle management to better handle closing connections and CPU usage - More fixes to parallel MCP-based plan/discovery queries ##### 1.5.46 - December 3, 2025 - **New Models:** Replaced Codex models from OpenAI with Codex-max - Optimized file-watcher logic so that it's a lot less CPU hungry - Polished recommendation wizard + small UI fixes - Fixed issues with parallel context builder plan generation - Fixed non-working GPT-5 mini models ##### 1.5.45 - December 3, 2025 - **New:** Context builder can now automatically generate a plan after completing its exploration - **New:** Improved MCP context builder tool to add followup chaining for questions or plans - **New:** Added Recommendation engine for auto model selection based on current configuration - file\_search uses improved regex engine for better performance in large repos - Many CPU usage optimizations across the app - Fixed MCP tool routing by using direct window\_id and tab\_id params to tools - Improved performance of discovery agent ##### 1.5.44 - November 29, 2025 - Resolved issues with prompts getting reset on tab switches - Fixed UI issue for pro edit settings - Discovery MCP tool now shows cancellation info ##### 1.5.42 - November 28, 2025 - Context builder as an MCP tool - Tab management now possible with MCP tooling - Workspace tool can create and edit workspaces with permission management ##### 1.5.40 - November 24, 2025 - Added support for Opus 4.5 across the app and providers - Zero-network MCP mode using filesystem-based transport ##### 1.5.37 - November 17, 2025 - Added support for Gemini CLI for chat, discovery & delegate edits ##### 1.5.28 - November 10, 2025 - Codex CLI as an API provider for OpenAI models via Plus/Pro plan ##### 1.5.21 - November 4, 2025 - File slices now stored in Application Support - Haiku 4.5 support, deprecated Sonnet 3.5 removed - Custom provider supports V4+ endpoint versions ##### 1.5.15 - October 29, 2025 - Pro Edit Agent mode with Claude Code or Codex for parallel edits ##### 1.5.5 - October 21, 2025 - Compose Tabs for parallel task workflows - Prompt enhancement modes: Replace, Augment, or Preserve - Desktop notifications when context builder completes ##### 1.5 - October 16, 2025 - Context Builder 2.0 with agentic discovery using Claude Code or Codex - Automatically selects files, codemaps, and slices within token budget - Overhauled file search and manage\_selection MCP tools ##### Other 1.5.x releases Versions 1.5.1-1.5.4, 1.5.6-1.5.14, 1.5.16-1.5.20, 1.5.22-1.5.27, 1.5.29-1.5.39, 1.5.41, 1.5.43 include MCP connection improvements, tab stashing (limit raised to 25), GPT-5 updates, native markdown rendering, auto workspace restore, and numerous stability fixes.
--- ## Classic Version 1.6 ### Classic Edition Version 1.6 Series The Classic Edition 1.6 series introduces Deep Code Reviews with a unified git tool, review mode for Context Builder, new slash commands for code review and refactoring workflows, and Jujutsu (jj) VCS support. #### Key Features in 1.6 - **Git Worktree Support** - Compare diffs across worktrees and linked checkouts, with full worktree metadata display and intuitive "main"/"trunk" aliases - **Jujutsu (jj) VCS Support** - RepoPrompt now supports Jujutsu version control alongside Git, with automatic detection and seamless switching between backends - **Context Builder Review Mode** - New response type for deep code reviews that analyzes your code with full codebase context - **New Slash Commands** - `rp-review` for comprehensive code reviews and `rp-refactor` for finding refactoring opportunities - **Unified Git Tool** - New MCP tool for git operations (status, diff, log, show, blame) with token-efficient output and built-in safety features - **Git Diff Artifact Publishing** - Generate and publish git diff snapshots directly from the UI for sharing with AI agents
View detailed changelog (1.6.0 - 1.6.14) ##### 1.6.14 - February 6, 2026 New Features (CLI) - **Machine-readable tool schemas** - New `--tools-schema` flag and `tools --schema` command for structured JSON output of tool definitions, enabling integration with external systems - **JSON file/stdin support** - Pass JSON arguments via `@file` or `@-` (stdin) for easier handling of complex payloads Improvements - **Improved git tool diff detail levels** - New "patches" detail level for truncated diffs; "full" now provides complete untruncated output - **Better discovery agent guidance** - Context builder now explores more broadly and effectively when analyzing codebases - **Smarter CLI JSON parsing** - Auto-detects JSON files and auto-repairs common formatting issues from LLM outputs Fixes - Fixed silent failures in apply\_edits replace-all - Now shows a clear error when no matches are found instead of silently succeeding ##### 1.6.13 - February 5, 2026 Improvements - **Updated to GPT-5.3 Codex and Claude Opus 4.6** - Upgraded to the latest models for improved coding performance and context building Fixes - Fixed MCP server approval flow - Resolved issues with stale auto-denials and duplicate approval requests - Improved MCP connection management - Better handling of connection slots when at capacity - Fixed folder management for system workspaces - Prevented folders from being incorrectly added to or loaded in system workspaces - Fixed proxy mode startup - Resolved false exits caused by MCP host delays ##### 1.6.12 - February 4, 2026 New Features - **Select as Codemap** - New context menu option to mark files or folders as codemap-only directly from the file tree - **Tab management** - Added "Close All Tabs" and "Clear All Stashed Tabs" actions for better tab control - **Skills installer** - Renamed "Commands" to "Skills" with support for both project-local and global (~/.agents/skills/) installation for cross-agent compatibility Improvements - **Workspace switching confirmation** - Prompts before switching workspaces if active chat sessions or context builders could be disrupted - **Faster workspace exit** - Improved performance when closing workspaces with many folders - **Better context menu organization** - Reordered and grouped context menu items with separators for clarity - **MCP connection reliability** - Added health checks, auto-restart, and retry logic for more robust MCP connections - **Large table rendering** - Tables with many rows now render more efficiently with a simpler fallback - **Improved rp workflows** - Updated prompts for better code generation guidance - **Window tools always available** - List and select window tools now always exposed, with list windows showing all opened roots for easier binding Fixes - Fixed UI indicator that was preventing sidebar from being resized - Fixed various async/concurrency issues throughout the app ##### 1.6.11 - February 2, 2026 Improvements - **MCP server self-healing** - Automatically recovers MCP server connections when they drop unexpectedly - **Smarter file search** - Auto-detects regex patterns vs literal text, making searches more intuitive - **Whole-word matching** - New option for precise searches that match complete words only - **Improved edit reliability** - Automatically handles escaped characters (like \\n) in edit operations without manual intervention - **Better search guidance** - Suggests exploring file tree when search returns empty due to path filters Fixes - Fixed potential edit failures when search text contains escape sequences ##### 1.6.10 - February 1, 2026 Improvements - **Better TypeScript/TSX code maps** - Improved parsing and signature extraction for TypeScript and TSX files, with better handling of multi-line function signatures, type annotations, and React components - **Improved MCP connection stability** - Fixed issues where long-lived idle connections could cause session blocking or connection capacity exhaustion, now with keepalive pings and automatic cleanup of stale connections - **Auto-approved MCP clients** - Built-in clients like Claude Code are now automatically approved without manual addition to the allow-list Fixes - Fixed UI freezing during startup - Fixed MCP reconnection issues - Improved handling of reconnects and transient denials to prevent unnecessary session blocking - Fixed type detection regression for auto codemaps ##### 1.6.9 - January 31, 2026 New Features - **Ruby language support** - Code structure analysis now supports Ruby files with Tree-sitter integration - **OpenAI service tier variants** - Choose service tier (auto, default, flex) per-model in the model picker, with a new global default tier setting Improvements - **Code structure enhancements** - Line numbers now included for function/method definitions, improved parsing accuracy for Swift, TypeScript, JavaScript, C/C++, Dart, and other languages, better handling of complex signatures and nested types, performance improvements with regex caching - **Model picker refinements** - Cleaner UI with legacy models hidden, unified planning model handling, and improved model selection consistency - **Path resolution improvements** - Root folder names now work as aliases in search filters and file resolution - **API fixes** - Temperature parameter no longer sent to reasoning models (which don't support it) ##### 1.6.8 - January 28, 2026 Fixes - Fixed inconsistent handling of file creation and moving in multi-root workspaces ##### 1.6.7 - January 27, 2026 Fixes - Fixed MCP compatibility with Codex by adding resource handling support ##### 1.6.6 - January 27, 2026 Fixes - Fixed token reporting for context builder - Fixed potential hangs in discovery agent when errors occurred during streaming - Improved agent lifecycle management to prevent stale routing state ##### 1.6.5 - January 26, 2026 Improvements - Folder sorting operations are now much faster - File system operations are more efficient - Symlink traversal can now be enabled for folders (note: folders outside the repo may not have their updates tracked correctly) - Optimized apply\_edits diff logic Fixes - Stability fixes for MCP connectivity - Miscellaneous performance and stability improvements ##### 1.6.4 - January 23, 2026 New Features - **Git Worktree Support** - Compare diffs across worktrees and linked checkouts, with worktree info displayed in git operations (branch names, main checkout references). Use "main" or "trunk" aliases in compare specs for intuitive diff comparisons. Improvements - Better file creation handling in multi-root workspaces - paths with folder aliases now resolve correctly - Git diff caching is more accurate, detecting file changes better and avoiding stale results - Codex CLI is now prioritized as the recommended chat backend for better cost efficiency - MCP tool connections are now more reliable - tools only become available once fully initialized - Improved tool documentation for better clarity and usability Fixes - Fixed Codex CLI not being able to use the git tool in some cases - Fixed apply\_edits line count reporting - changed line counts now accurately reported - Fixed lingering tools in Context Builder (Claude Code) - tools properly cleaned up after discovery runs - Fixed race condition where MCP clients could receive incomplete tool lists on fast connections ##### 1.6.3 - January 23, 2026 New Features - **Selectable follow-up types in Context Builder** - Choose between Plan, Review, or Question modes when auto-generating from discovery results Improvements - **Optimized Context Builder streaming** - Improved performance of the Context Builder view during streaming responses - **Better markdown table display** - Tables now render in a horizontally scrollable view, preserving column alignment without wrapping Fixes - Fixed Review mode not working when started from the Context Builder interface - Fixed delegate edit tools not appearing in Pro Edit mode in some cases - Fixed git tool not being available to external agents (Codex) ##### 1.6.1 - January 22, 2026 New Features - **Jujutsu (jj) VCS Support** - RepoPrompt now supports Jujutsu version control alongside Git, with automatic detection and seamless switching between backends Improvements - **file\_search is now 80% more token efficient** - Optimized search result formatting significantly reduces token usage - Upgraded MCP backend to better support coding agents that do MCP tool search - Improved search result formatting with hierarchical file tree view for easier navigation - Better handling of workspaces with multiple git repositories - Performance improvements for file sorting operations Fixes - Fixed git tool support when used in a worktree - Fixed context builder settings getting reset after app restart ##### 1.6.0 - January 20, 2026 Deep Code Reviews This release introduces powerful code review capabilities powered by a new unified git tool: - **Context Builder Review Mode** - New response type for deep code reviews that analyzes your code with full codebase context - **New Slash Commands** - `rp-review` for comprehensive code reviews and `rp-refactor` for finding refactoring opportunities - **Unified Git Tool** - New MCP tool for git operations (status, diff, log, show, blame) with token-efficient output and built-in safety features - **Git Diff Artifact Publishing** - Generate and publish git diff snapshots directly from the UI for sharing with AI agents - **Improvements:** Streamlined Context Builder UI, improved CLI tab awareness and help documentation, JSON-only apply\_edits for better multiline handling, performance optimizations
--- ## Classic Version 2.0 ### Classic Edition Version 2.0 Series The Classic Edition 2.0 series introduces RepoPrompt Agent, a fully integrated agent harness that brings interactive, agentic coding sessions directly into the app with first-class support for Codex, Claude Code, and Gemini. #### Key Features in 2.0 - **RepoPrompt Agent** - A completely new way to use RepoPrompt with interactive, agentic coding sessions powered by your choice of AI provider - **Full Native Codex Support** - Rich integration with the Codex app server for the best agent experience, including configurable tool preferences and reasoning effort - **Claude Code & Gemini Support** - Interactive agentic sessions via headless CLIs, with full native reasoning traces, steering, bash tool calls, and approval flows - **Context Builder Integration** - Agents can leverage RepoPrompt's context building workflows for deeper codebase understanding - **Optional Edit Review** - Review and approve each edit the agent makes before it's applied - **Agent Onboarding** - Guided wizard for setting up Agent Mode, including license activation, provider testing, and MCP server configuration
View detailed changelog (2.0) ##### 2.0.31 - March 30, 2026 Improvements - Restored GLM 5.0 as an API provider model for Oracle and Chat alongside 5.1 - Prompt export now strips meta-framing and defaults ambiguous requests to Plan mode Fixes - Fixed legacy chat markdown rendering at incorrect widths ##### 2.0.30 - March 30, 2026 Improvements - Smoother, more responsive chat scrolling with less jitter during streaming - Session handoff now preserves richer context when forking conversations - Collapsed history summaries render faster with precomputed details Fixes - Fixed chat scroll views getting stuck or not following new content - Fixed inconsistent transcript rendering when switching sessions ##### 2.0.29 - March 27, 2026 New Features - Codex agent mode now supports user input requests for clarification and approval Improvements - Improved transcript auto-scroll reliability with better layout settling and viewport detection Fixes - Fixed apply\_patch tool cards reverting from completed to running state when late output arrives - Fixed bash tool cards not auto-expanding inside grouped transcript blocks - Fixed Codex reconnection interrupting active threads ##### 2.0.28 - March 27, 2026 New Features - Added GPT-5.4 Fast service tier support for Codex CLI provider - Added GLM 5.1 model support for Z.AI - Tool search is now a separate preference in Claude Code agent mode, independent from MCP strict mode Improvements - Better tool result preservation during session handoff and migration - Improved transcript scrolling performance Fixes - Fixed Codex rejecting MCP tool calls when running context builder by adding proper operation annotations - Fixed crash when viewing archived sessions with duplicate sidebar tabs - Fixed Claude context usage displaying inflated values - Fixed crash in text editor when handling mention inputs - Fixed potential race condition in token calculations - Improved file system event handling stability and reduced memory allocations ##### 2.0.27 - March 27, 2026 Fixes - Fixed a regression from 2.0.26 that could strip detail from transcript turns during compaction - Disabled Codex app server elicitation support to prevent connection issues ##### 2.0.26 - March 26, 2026 New Features - Effort level picker — Choose between Low, Medium, High, and Max effort levels for Claude directly from the input bar - MCP strict mode toggle — Control whether Claude Code runs in strict MCP mode; disabling allows additional MCP servers Improvements - Smarter session sidebar — Better prioritization of active and archived sessions - Reduced memory usage — Older transcript content is now compacted more aggressively to keep sessions lightweight - Smoother scrolling — Fixed several scroll state bugs and improved scroll reliability Fixes - Fixed workflow and attachments lost on first message — Selected workflow and pending attachments now carry over correctly when starting a new session - Fixed MCP server registration — Corrected an issue where --env flags weren't parsed correctly when adding Claude MCP servers ##### 2.0.25 - March 23, 2026 Improvements - Improved chat auto-scroll reliability — auto-follow now recovers correctly after content settles - Streaming assistant responses render more smoothly with less layout thrashing - Improved performance and reliability of file tree updates, especially in large repos Fixes - Fixed auto-scroll getting stuck after streaming activity settles - Fixed unwanted scroll-to-bottom while actively scrolling ##### 2.0.24 - March 20, 2026 Improvements - IDE tabs preserved on close — Editor tabs are now stashed by default when closing, so your workspace is restored next time - Agent Oracle pill — Updated to use a brain icon for better clarity - Improved Claude Code integration — Better MCP environment defaults for more reliable connections - Agent mode performance — Improved scroll stability and reduced unnecessary re-renders during long sessions - Refined tool cards — Improved summaries and status indicators for agent tool results Fixes - Fixed transcript scroll getting stuck during long agent conversations - Fixed window session state not saving correctly on app quit - Fixed skill/command names failing with strict validators ##### 2.0.23 - March 19, 2026 New Features - GLM 5 Turbo support — New model option available for Claude Code integrations, with updated defaults (GLM 5 Turbo for Sonnet tier, GLM 4.7 for Haiku tier) - Codex automatic auth recovery — RepoPrompt now detects ChatGPT authentication failures and surfaces a login prompt to recover the session without manually reconnecting Improvements - Richer agent tool cards — Tool results show more status detail and better visual indicators during and after execution - Bash result cards auto-expand — Recent and in-progress bash commands automatically expand in the tool panel for easier monitoring - Smarter session creation — New tabs no longer create blank agent sessions when opened outside of agent mode ##### 2.0.22 - March 18, 2026 Improvements - Further improved auto-follow scroll behavior in agent chat when reaching the end of a run - Improved scroll behavior in unified diff views Fixes - Fixed missing session metadata causing incorrect sidebar titles and sort order for older sessions ##### 2.0.21 - March 17, 2026 New Features - Pin compose tabs to keep important sessions at the top of the sidebar - Confirmation prompt before closing windows with active MCP connections (Cmd+W) - Confirmation prompt before deleting a workspace to prevent accidental deletions Improvements - Improved unified diff rendering with accurate hunk positioning and line change stats - Better session continuity when interrupting and resuming Claude runs - Optimized agent mode chat view and improved scrolling behavior Fixes - Fixed skills being auto-invoked by Codex when they should require explicit invocation - Fixed active tab state not restoring correctly after switching sessions - Fixed auto-selected files losing their full selection when reading slices - Improved reliability and performance of git diff review workflows ##### 2.0.20 - March 12, 2026 Fixes - Fixed architect prompt being too language-specific ##### 2.0.19 - March 12, 2026 Improvements - Much improved scroll stability during agent runs Fixes - Fixed token count inflation in Manual preset when codemap was disabled - Fixed agent file tag context selection Agent Workflows - Refreshed agent workflow tooltips and descriptions for clarity MCP - New MCP commands for creating and closing compose tabs, with safe defaults for background automation - New tab management safety rules prevent closing the last tab, the active visible tab unless explicitly allowed, or tabs with live bound runs - MCP agents can now list chats and inspect chat history scoped to the current compose tab for more accurate multi-tab workflows ##### 2.0.18 - March 10, 2026 Fixes - Fixed several performance and stability issues introduced in the previous update - Fixed agent transcript rendering accuracy and tool execution state consistency - Fixed copy-to-clipboard button for generated plans in the Discover agent ##### 2.0.17 - March 10, 2026 New Features - Agent transcript now uses a structured turn-based model with smart compaction, keeping your most important context while managing long sessions efficiently - ChatGPT export now supports planning and code review workflows, designed for use with GPT-5.4 Pro Improvements - Transcript export now includes grouped history summaries with condensed tool previews - Tool previews in export now exclude failed or cancelled executions for cleaner output - Improved architect system prompt - Workflow selection UI improvements Fixes - Fixed git tool not using the system PATH, which could prevent tools like git LFS from being found - Fixed a breaking change with the Codex app server ##### 2.0.16 - March 5, 2026 Fixes - Fixed session scroll in Codex agent mode - Fixed tool boundary isolation for Codex ##### 2.0.15 - March 5, 2026 New Features - Added GPT-5.4 model support - Added Codex fast mode toggle and compact command Improvements - Improved search with smarter pattern matching and warnings when a search is auto-corrected - Codex reasoning messages are no longer shown in the feed - Agent instruction files are excluded from auto-selection - Performance improvements across file browsing, selection, and git diff operations Fixes - Fixed context builder token budget drift when called via MCP - Fixed crash when opening the workflows popover - Fixed Codex approval failures due to wire format mismatch - Fixed bash liveness detection causing hangs - Fixed agent mode model picker appearing too narrow ##### 2.0.14 - March 4, 2026 Improvements - **Agent Mode (Codex)**: Revamped system prompt encourages natural preamble output; reasoning messages now update the status bar instead of flooding the chat; improved tool card rendering - **Architect/Plan prompt** modernized for agentic workflows with better guidance for multi-step planning - **Plan & Build / rp-build** workflow is now more efficient - **MCP tool improvements**: Fixed incorrect search failures; improved path semantics across all tools in multi-root workspaces for more consistent behavior - Oracle Export is now clearly labeled as **ChatGPT Prompt Export**, making its purpose more obvious for ChatGPT Pro users - ChatGPT Prompt Export tool card now includes a **Copy Prompt button** for easily passing prompts from Agent Mode into external tools - Cleaner UX around model selection in Agent Mode - Codex provider stability improvements Fixes - Removed deprecated Gemini 3.0 Pro (being shut down) ##### 2.0.13 - March 2, 2026 New Features - Added Claude GLM as a Claude Code option using your confirmed Z.ai API key with native Claude environment support Improvements - Codex agent timeouts are now logged as warnings in the agent log instead of failing the run Fixes - Fixed delegate edit so file changes are reported more reliably - OpenRouter settings now update more reliably when configuration changes Note - If recent Codex CLI changes are causing connectivity issues, we currently recommend rolling back to Codex CLI 104 ##### 2.0.12 - March 1, 2026 Improvements - Codex agent sessions now detect stalls and automatically recover - Codex resume timeouts now fall back to a fresh session instead of getting stuck - Codex model list now syncs more reliably without unnecessary reloads - Upgraded Investigate workflow — more thorough and effective at diagnosing issues Fixes - Fixed agent sessions showing errors when switching tabs or restarting; sessions now recover automatically - Fixed background processes not cleaning up properly on exit - Fixed occasional hangs when closing windows or quitting the app - Fixed occasional UI glitches in the toolbar and MCP server panel ##### 2.0.11 - February 27, 2026 New Features - **Agent session handoff** — Transfer an agent chat transcript and context to a new tab or a different agent, preserving full conversation continuity - **Fork sessions from the transcript** — Create a new agent session branching from any message bubble in a transcript - **Agent-scoped slash command discovery** — Slash commands and skills are now discovered based on the active agent (Claude Code uses `.claude/commands/`, Codex/Gemini use `.agents/slash/`) - **Remember last-used agent** — New agent tabs now open with your previously selected agent (Claude/Codex/Gemini) instead of always defaulting to Claude Code Improvements - Significantly reduced token usage in Codex agent sessions - Greatly improved Codex session stability and recovery, including better cancellation handling and recovery from unresponsive states Fixes - Fixed Oracle UI and workflow selections leaking between multiple chat tabs - Fixed autocomplete suggestion overlay rendering at the wrong size when the first result set is empty - Fixed a race condition where Claude could miss tool results when steering interrupts were sent quickly - Transient stream connection errors are now handled gracefully instead of failing the request ##### 2.0.10 - February 25, 2026 New Features - **File tagging in agent chat** — Type `@filename` in agent messages to attach file contents directly as context. Includes a smart suggestion overlay with fuzzy matching and disambiguation for duplicate filenames - **Support for skills via `/` commands** — Skill files are now detected from all loaded workspace directories and the global skills folder, and can be invoked with `/skillname` in agent input with autocomplete suggestions - **GLM5 support in ZAI provider** — GLM5 is now available for chat and oracle Improvements - Steering messages to Claude now wait for active tool calls to finish before sending, preventing crashes and ensuring correct message ordering - Cancelled or failed steering drafts are restored to the input bar instead of being lost - Improved Codex stability and addressed hanging output Fixes - Fixed Claude tool call requests including wrong tools, causing prolonged and failing discovery and delegate edit runs - Fixed discovery agent not receiving the correct timeout setting ##### 2.0.9 - February 23, 2026 New Features - **Claude Agent Out of Beta** — Full support for native reasoning traces, steering, bash tool calls, and approval flows, powered by the headless CLI you already have installed - Added Gemini 3.1 Pro Preview model support Improvements - **Revamped Bash Tool Call Cards** — New cards for both Codex and Claude with auto-expansion for the latest completed command, better output rendering, and improved status tracking - Revamped Review prompt and tightened rp-review prompt - Reasoning effort preference is now saved across sessions - Tool configuration panels replaced with integrated menus for a cleaner, faster workflow Fixes - Fixed Codex agent failing to reconnect properly after disconnects - Fixed history panel auto-revealing during active agent runs or streaming ##### 2.0.8 - February 18, 2026 Improvements - Improved Codex agent connection routing reliability in multi-window environments - Enhanced connection recovery and session continuity during reconnects ##### 2.0.6 - February 18, 2026 Fixes - Reverted some Codex changes that caused instability ##### 2.0.5 - February 18, 2026 New Features - **Custom Agent Workflows** — Create, clone, and configure custom agent workflows with a new workflow manager UI - **Oracle Chat Log Tool** — New oracle\_chat\_log tool gives agents read-only access to recent chat history for better context recovery - **Context Builder Plan Streaming** — Context builder plans now stream in real-time with cancellation support Improvements - **Codex Streaming** — When using Codex CLI for oracle/chat models, responses now stream in real time instead of completing all at once - **Image Paste** — Reworked agent mode image pasting to resolve many cases of failed pastes - **Session Resume** — Improved agent session resume stability - **Skills Rework** — Skills for MCP/CLI have been reworked to use the correct structure Fixes - Fixed a rare crash with Codex - Fixed app hangs when scrolling back up through old sessions - Fixed an issue with Codex where third-party MCP tools were getting filtered out ##### 2.0.4 - February 14, 2026 Fixes - Fixed context builder calls failing to resolve the correct tab during agent mode chats ##### 2.0.3 - February 14, 2026 Fixes - Fixed dropped messages in Codex agent mode chats - Fixed memory leaks in agent mode during extended sessions with heavy tool usage - Improved event stream stability to prevent concurrency issues during agent runs ##### 2.0.2 - February 13, 2026 New Features - **Image pasting support** - Paste images directly into conversations - **Improved image support for Claude and Gemini** Improvements - **Significantly improved command execution reliability in Codex Agent Mode** - More accurate tracking of running processes, cleaner output display, and better session stability with retry logic - **Toggle to always expand tool cards in Agent Mode** - Available in the new agent settings menu - **Improved diff rendering** - More context lines and cleaner hunk separation - **Smoother UI performance** - Reduced unnecessary UI refreshes, optimized loading indicator, and improved autoscrolling behavior - **Improved model selection sorting** - Models sorted by version families with better default collapsing Fixes - Fixed auto model retrieval for Codex ##### 2.0.1 - February 11, 2026 New: RepoPrompt Agent A completely new way to use RepoPrompt. RepoPrompt Agent is a fully integrated agent harness that brings interactive, agentic coding sessions directly into the app. - **Full native support for Codex** - Rich integration with the Codex app server for the best agent experience - **Beta support for Claude Code and Gemini** - Interactive agentic sessions via headless CLIs (long chats may have limitations) - **First-class Context Builder integration** - Agents can leverage RepoPrompt's context building workflows for deeper codebase understanding - **Optional edit review** - Review and approve each edit the agent makes before it's applied - **Image support** - Paste or drag-and-drop images into agent conversations - **Session management** - Resume sessions, track token usage, and manage multiple agent conversations - **Configurable tool preferences (Codex)** - Control which tools agents can use, including approval policies and sandbox modes - **Selectable reasoning effort (Codex)** - Fine-tune agent behavior with adjustable reasoning effort levels New: Agent Onboarding - Guided onboarding wizard for setting up Agent Mode, including license activation, provider testing, and MCP server configuration
--- ## Classic Version 2.1 ### Classic Edition Version 2.1 Series The Classic Edition 2.1 series introduces MCP-controlled agents and cross-family sub-agents, allowing external MCP clients to start and steer Agent Mode sessions, and enabling agents to delegate work across CLI families. #### Key Features in 2.1 - **MCP-Controlled Agents** - Start and steer Agent Mode sessions from external MCP clients or the CLI via the new agent\_run and agent\_manage tools - **Cross-Family Sub-Agents** - Within Agent Mode, spin up sub-agents across different CLI families — Claude can steer Codex, Codex can steer Claude - **Agent Role Defaults** - Configure default models per agent role (explore, engineer, pair, design) with per-role override controls - **Cleaner MCP API** - Dedicated manage\_selection and prompt tools replace context\_state; chat tools renamed to oracle; new context\_bind for easy workspace binding via working directories
View detailed changelog (2.1.0 - 2.1.33) ##### 2.1.33 - June 19, 2026 Fixes - Fixed Context Builder runs being cancelled while finalizing their results. ##### 2.1.32 - May 27, 2026 New Features - RepoPrompt is now free to use, with licensing and activation prompts removed across the app. - Added a transition notice with links to the claim portal and next-chapter update. Improvements - Made long Agent Mode crawls refresh more quickly during active runs. - Reduced transcript jumping by keeping automatic tool-card expansion from animating. ##### 2.1.31 - May 20, 2026 Fixes - Fixed Codex Agent Mode waits so steering an active run no longer leaves parent or child waits stuck in the wrong state. - Fixed `manage_selection` slice updates so replacing slices for one file preserves the rest of the current selection. - Fixed generated Oracle and context builder exports so delegated agents can open them through MCP immediately. ##### 2.1.30 - May 19, 2026 Improvements - Made large file tree updates much faster, especially when many files are added or changed at once. - Reduced Agent Mode transcript layout churn so streaming responses feel smoother. - Improved Agent Mode transcript scrolling so session switches are less likely to land slightly above the latest message. Fixes - Fixed IDE file tree sorting after optimized initial loads. - Fixed Agent Mode composer and Stop controls so actions can’t accidentally target a stale or previously selected session. - Fixed composer refresh behavior after handoff or tab/window changes, including draft and pasted-image state. - Fixed Gemini ACP chats resuming reliably after app restart or cold resume. ##### 2.1.29 - May 16, 2026 Improvements - Explore agents are more capable when investigating projects, while delegated editing remains safely restricted. Fixes - Fixed agent transcripts that could fail to refresh until you scrolled or reopened the view. - Made background agent sessions refresh and save more reliably. ##### 2.1.28 - May 16, 2026 New Features - Added richer agent questions that can ask for multiple answers at once, including choices, custom responses, skipping, and timeouts. Improvements - Made Agent Mode smoother when several sessions are open in the background. - Improved reliability when restoring, switching, and finishing agent sessions. - Made Codex agent runs better at recovering from temporary stalls and waiting-for-input states. - Made file reads, searches, and edits reflect external file changes more reliably. - Updated the default Engineer role recommendation to GPT-5.5 Medium. - Agent runs now use the Pair role by default when no model is specified. Fixes - Removed the legacy Context Builder path to eliminate persistent performance overhead. - Fixed cases where MCP tools could see stale file contents after files changed on disk. - Fixed unnecessary background work from inactive Codex sessions. - Fixed several agent activation, status, and transcript persistence issues. ##### 2.1.27 - May 14, 2026 Improvements - Made scoped file searches faster and more reliable in large workspaces - Improved Agent Mode workspace switching so old session cleanup no longer slows down switching - Improved workspace root syncing when paths are edited from multiple windows or sessions - Reduced unnecessary file tree refreshes when workspace roots have not actually changed Fixes - Fixed workspace tools not always seeing files immediately after create, edit, or delete actions - Fixed concurrent scoped searches interfering with each other - Fixed Codex configuration repair for more TOML formatting styles - Fixed root folder reordering causing unnecessary UI churn ##### 2.1.26 - May 14, 2026 Improvements - Improved performance when updating large workspaces - Made chat previews faster and more responsive - Improved Deep Plan so generated plans keep more useful context - Made ignore pattern editing more reliable Fixes - Fixed copied prompts sometimes including a file tree even when file trees were disabled - Fixed Agent Mode permission recovery after moving to a new Mac - Fixed some Agent Mode tool summaries appearing incomplete - Fixed newly created files not appearing right away in workspace tools - Fixed a performance issue that could slow down file tree and preview updates ##### 2.1.25 - May 13, 2026 New Features - Added GPT-5.5 and GPT-5.5 Pro to Oracle when using your own OpenAI API key (already supported via Codex CLI) Improvements - Significantly reduced Agent Mode memory usage during long sessions - Slash skill commands now flow through your selected workflow, and reserved Codex commands route correctly - More resilient code syntax parsing to prevent rare crashes Fixes - Fixed file tree cleanup when deleting nested folders during heavy filesystem activity ##### 2.1.24 - May 9, 2026 Improvements - Codex /goal now works alongside selected app workflows, and typed goal objectives appear immediately as user bubbles in Agent Mode - Staged /goal drafts are now visible in the Agent Mode status row - ask\_user prompts no longer expire while you're typing your answer - Faster file tree updates during heavy filesystem activity Fixes - Fixed file tree churn when folders changed on disk - Fixed Oracle preview transcripts showing in the wrong chat - Fixed the prompt export copy button disappearing in long Agent Mode sessions - Fixed Codex goal tracking when using /goal control actions - Deep Plan now waits for you instead of silently defaulting when an involvement checkpoint times out Notes - The `agent_run` MCP/CLI surface no longer accepts the `native_workflow` parameter — Codex /goal and /computer-use remain available as in-app slash commands ##### 2.1.23 - May 8, 2026 New Features - Added Deep Plan, a new Agent Mode workflow for more thorough planning sessions - Added Codex /goal support so you can set or update a Codex thread goal directly from Agent Mode - Added Agent Workflows settings for managing built-in workflow visibility, featured workflows, custom workflow markdown, and cleanup guidance - Added Codex and Claude permission/runtime controls directly in CLI Providers settings Improvements - Reduced memory retained by codemap scanning in large workspaces - Faster rendering for long Agent Mode assistant transcripts - More compact `file_search` results with less noisy nested path output - Gemini headless agents now use the shared ACP path for more consistent permission handling - Updated agent defaults and recommendations to prefer GPT-5.5 Low for Explore and GPT-5.5 Medium for Engineer work - Clearer, more user-focused Agent Mode workflow descriptions ##### 2.1.22 - May 7, 2026 Improvements - Faster Agent Mode sidebar in large workspaces - Codex agent thread names now stay in sync with Agent Mode session names - Cleaner, more focused chat mode responses - Gemini agents now launch in untrusted workspaces when MCP is configured - Clearer error messages when agents fail to delete files - Improved coordination when agents delegate work to other agents Fixes - Fixed startup crashes related to socket setup - Fixed crashes when launching Codex, Claude, or Gemini agents - Fixed wrong file tree root labels in multi-root Agent Mode sessions - Gemini agent errors now show useful detail instead of "Internal error" ##### 2.1.21 - May 6, 2026 New Features - Codex auto review permission mode — automatically grants safe approvals during code review runs - Codex now supports a wider range of permission prompts in Agent Mode Improvements - Much faster workspace switching, especially when restoring chat sessions - Much faster chat token previews in large workspaces - Font scaling fixes — large and normal presets now update live across Agent Mode, Chat, file trees, Settings, workspace pickers, and Oracle without clipped or bloated layouts - Sub-agent permission settings now apply consistently to agents started over MCP - Oracle review status stays scoped to the originating Agent Mode thread instead of leaking into other tabs - Hardened Cursor / OpenCode lifecycle — addresses the crash reported in 2.1.20 - Stronger MCP routing isolation — restricted agents are no longer asked to call hidden routing tools, and stale clients can no longer claim run policies - Safer steering — Claude interrupts now wait for in-flight child agent waits to drain - Cleaner sidebar status plate — MCP-controlled rows align consistently with regular rows; running spinner no longer shows a disc behind the arc Fixes - Fixed Codex file-change approval stalls — agents now resume immediately after you approve - Tolerate Codex versions that don't yet support the optional memory mode - Fixed the agent image attachment picker — now opens for new compose tabs and anchors to the right window - Protected Codex model selections from being downgraded by older settings - Fixed MCP sub-agent permission activation ##### 2.1.20 - April 24, 2026 Improvements - Agent Mode sidebar shows persistent attention badges when background tabs complete, fail, or start waiting — so status changes in collapsed or off-screen sessions aren't missed - Faster session switching in Agent Mode — eliminated duplicate transcript and runtime refreshes when flipping between running sessions - Agent logs (`get_log`) now preserve assistant narration in correct chronological order around tool calls - Tightened agent sidebar row density, with collapsed threads propagating unseen status counts - Added debug-only Agent Mode diagnostics (Claude raw event logging, performance metrics) Fixes - Fixed multi-session agent waits waking prematurely on transient instruction-delivered or steering events - Fixed Claude tool cards staying stuck when provider completion IDs didn't align with MCP tracker IDs - Full agent session UUIDs are now preserved in multi-session tool output (previously truncated to 8 characters, breaking follow-up wait/poll calls) - Fixed stale workspace bindings left behind after MCP cleanup of child agent sessions - Stabilized runtime sidebar when collapsing/expanding session details ##### 2.1.19 - April 24, 2026 New Features - New rp-optimize skill — iterative performance optimization workflow with a measure-first loop and scoreboard tracking - Collapse/expand-all-threads button in the Agent Mode sidebar — tuck away nested sub-agent chats in one click Improvements - UX cleanup of the Agent Mode sidebar and composer - Reduced CPU usage from the cancel affordance animation and sidebar refresh Fixes - Quick Apply All recommendations now recomputes state so still-unsatisfied items remain visible - Chat session model selection no longer rewrites the global compose default - Codex apply-patch disable now uses the canonical override - Fixed Agent Mode compose button icon optical centering - Fixed rp-orchestrate/rp-refactor Codex-family role check ##### 2.1.18 - April 23, 2026 New Features - GPT-5.5 Codex models — new High/Medium variants, now preferred over GPT-5.4 across defaults and recommendations - Oracle support for Claude-compatible providers — Kimi and Custom backends are now selectable Oracle models - Collapsible sub-agent threads in the Agent Mode sidebar - Auto-archive of stale agent sessions, with Today/Yesterday/Previous date separators - MCP file deletes now go to Trash instead of being permanently removed - Optional MCP onboarding — Pro setup now leads with CLI Providers; Skip All drops you straight into Agent Mode Improvements - New "Agent Models" setting to prevent models from picking random models via MCP agent tools - Faster session list restore Fixes - Fixed Oracle recommendation upgrade detection — users on Gemini now correctly prompted to upgrade to Codex GPT-5.5 High after connecting Codex CLI - Fixed OpenCode ACP empty responses with Kimi K2.6 - Fixed Claude MCP steering queue race that could report accepted steers as failed - Fixed Claude Code model ordering ##### 2.1.17 - April 22, 2026 New Features - New Claude Code-compatible backends: CC Moonshot (Kimi), CC Custom, and CC Zai - New "Agent cleanup guidance" setting Improvements - Performance improvements to UI responsiveness and workspace opening - Improved investigate workflow with better sub-agent management - Improved sub-agent guidance to better coordinate with the orchestrator when help is required - Cleaner Agent Mode Overview settings page - Command execution now captures complete terminal output before finalizing Fixes - Fixed Claude steering queue race - Fixed session reuse issues when switching Claude backend variants ##### 2.1.16 - April 21, 2026 New Features - Design-role agents now produce a structured markdown report (Context, Findings, Recommendations) for review, architecture-critique, and analysis tasks. The report path is surfaced in the final summary so you can open it directly. Improvements - Expanded explore-agent dispatch guidance so agents make better judgment calls about when to spawn a sub-agent versus reading files inline - Progress updates now stream across all agent providers (previously Codex-only), so you see interleaved status messages regardless of model - Tightened role guidance in rp-orchestrate — smaller models stay within the assigned role (pair/engineer/design/explore) instead of fabricating model-based downgrades - Cleaner, grouped summaries in the agent control row - Quieter, coalesced status messages when running Context Builder with OpenCode Fixes - Fixed a crash when an agent message mentioned the same file more than once - Fixed sub-agent lineage mapping in the sidebar ##### 2.1.15 - April 21, 2026 Fixes - Fixed a deadlock that could hang the app when running multiple parallel agents (e.g. concurrent orchestration or investigation workflows). Force Quit was sometimes required to recover. - Agent handoff/fork from historical messages now uses the authoritative transcript, so forks no longer incorrectly include the latest conversation state - Invalid handoff cutoff IDs are rejected up front - OpenCode Discover Agent logs no longer flooded by context builder noise - Z.ai GLM activation and settings discoverability restored in CLI Providers Improvements - Agent Mode sidebar consolidated into two popovers: **Models** (Oracle/Plan model, Context Builder, sub-agent role defaults) and **Permissions** (sub-agent policy picker with deep links) - Agent Permissions Overview groups Direct and Sub-Agent scopes under one card, with the active sub-agent policy shown inline - Per-provider sub-agent permission levels — choose each provider's native permission levels instead of abstract policies - Agent Models settings surfaces related cross-links (Oracle Model Presets, Delegated Edits) in a Related Settings section ##### 2.1.14 - April 20, 2026 New Features - Redesigned Settings with a dedicated window, modernized sidebar, and agent-first organization that progressively reveals advanced options - Agent Models settings — a new home for configuring recommendations and model selection per agent role - Agent Permissions settings with separate scopes for direct and sub-agent permissions, and a tri-state sub-agent policy - Toolbar update pill — surfaces available Sparkle updates directly in the toolbar - App Settings MCP tool — query and update app preferences from MCP clients and the CLI, with an `options` op for discovering allowed values - Agent Explore tool — a lightweight, read-only exploration tool for sub-agent contexts Improvements - Secure storage for agent and provider permission preferences - Global settings now backed by JSON in Application Support; presets moved alongside - Refined Settings typography, spacing, and section layouts throughout - Claude reasoning now shown in live agent status - Claude Code auto permission mode supported for Opus 1M - Cleaner update notifications with separate passive vs. user-initiated flows - Copy button on agent error bubbles - Reorganized orchestration skills (rp-orchestrate, rp-investigate) for clearer delegation - Updated Gemini recommendation defaults Fixes - Hardened MCP transport lifecycle and compatibility edge cases - Agent file mention display and caret placement - Claude auto permission fallback behavior - `file_actions` now requires absolute paths to prevent ambiguity - `app_settings` accepts string-encoded booleans and numbers from MCP clients ##### 2.1.13 - April 17, 2026 New Features - Option to disable Code Maps in Advanced Settings — turn off code map generation across all workspaces - Codex "fast" model variants for GPT-5.3+ — pick fast variants directly in the model picker; replaces the separate fast mode toggle - Granular Claude Code CLI model options — more model choices in the Claude Code picker - Live Claude flag updates — permission and flag changes apply mid-session without restarting Improvements - Reduced VCS status command storms — fewer redundant git/jj status refreshes on large repos - Investigation, refactor, and orchestrate workflows now remind the caller agent to periodically poll sub-agents so pending permission approvals don't stall progress - Reordered agent composer capsules for clearer grouping — Pair/Interview/Workflow on the left, Oracle next to Fast/context on the right Fixes - Fixed crash when MCP file reads received paths containing NUL characters - Fixed Claude Code Auto (Preview) permissions not always initializing correctly on new sessions - Now warns when an MCP steer call's timeout is silently ignored ##### 2.1.11 - April 16, 2026 New Features - Claude Code Auto (Preview) permissions mode — auto-approves tool calls that pass background safety checks (research preview; behavior may change) - Compose tab capacity policy — background agent tabs can exceed the normal soft tab limit with auto-stashing that protects active or pinned agent sessions from eviction - Orchestration-style refactor workflow — redesigned around analyze → plan → dispatch → verify, with parallel agents for independent modules - Parallel exploration in the investigate workflow — dispatch explore agents alongside your own research to test hypotheses faster - Explore agents can now be used proactively without explicit invocation (engineer, pair, and design still require opt-in) Improvements - Faster sidebar loading via a new agent session metadata index - Long agent chats are better optimized — transcript handling stays responsive as conversations grow - Folder list in workspace roots now scrolls gracefully when many folders are present - Claude model picker ordering refinements and effort-level filtering aligned to supported models Fixes - Fixed MCP composer chrome tab switching - Fixed context builder cancel controls - Fixed Codex watchdog falsely triggering during agent\_run waits ##### 2.1.10 - April 15, 2026 New Features - Global keyboard shortcuts — rebindable hotkeys for Agent new chat, IDE/Agent mode toggle, and sidebar toggle - Dedicated Keyboard Shortcuts settings tab with a full rebindable catalog - Cursor ACP full access permissions Improvements - Live steering for ACP agents — safely interrupt and re-prompt active sessions; multiple steering prompts are queued and delivered in order - Scoped deep-link routing — clicking an agent notification opens the correct window, workspace, tab, and session - Agent handoff picker now reconciles with available agents and models, disabling unavailable options with clear UI feedback - Unified provider preferences — consistent permission handling across all agent providers - Cleaner transcripts — empty or whitespace-only assistant messages no longer appear in transcripts or summaries - Cleaner Cursor ACP tool cards — placeholder tool events are filtered out - Gemini session safety — model selection is locked during Gemini runs to prevent accidental overrides on resumed chats ##### 2.1.9 - April 14, 2026 Fixes - Fixed Cursor MCP configuration — removed transient project config writes during Cursor ACP launch to avoid unnecessary filesystem side effects ##### 2.1.8 - April 14, 2026 New Features - Cursor CLI agent support — full Agent Mode integration with dynamic model discovery, auto model fallback, and ACP session management - Workspace hiding — hide and restore workspaces from the manager - Agent handoff export — new MCP surfaces for exporting agent transcripts between windows and agents Improvements - Bounded memory usage in codemap and ignore caches for large repos - Generalized ACP tool lifecycle handling for more consistent tool cards across providers - Cleaner RepoPrompt tool name parsing from ACP session titles - OpenCode running tool updates render more smoothly - Suppressed noisy session resume replay events when reopening ACP agents - Selection CLI output respects full paths when requested Fixes - Fixed Tree-sitter scan crash - Fixed ACP auto-approval for RepoPrompt tools - Fixed stale codemap cache reuse across worktrees - Fixed OpenCode "none" variant grouping in model picker - Fixed agent input capsule vertical offset - Fixed markdown code block spacing - Restored persisted tool result subtitles after transcript reload - Fixed path regex anchor search in file finder Removed - Removed diff capability allowlists — model diff support is now universal ##### 2.1.7 - April 13, 2026 New Features - MCP permission override — new setting to turn off the enforced safe permission defaults for MCP sub-agents - Workspace cleanup UI — collapse duplicate workspace records and clean up stale entries - ACP image attachments — send images through ACP-connected agents Improvements - Much faster codemap generation - Faster search across large repos - Faster transcript refresh in long chats - Faster gitignore matching - Faster file edits - OpenCode models grouped by provider in model pickers for easier selection - Faster OpenCode/ACP model picker — model cache now warms in the background - Agent mode polish — stable attachment composer, refined window tint and titles - Better MCP regex errors — clearer compile error messages and more reliable auto-detection Fixes - Fixed OpenCode permission controls - Fixed agent sidebar rename - Fixed expanded user bubble height - Fixed Codex empty base instructions - Fixed Claude skill discovery roots - Fixed provider ID fallback from display name in model catalog - Sanitized persisted transcript tool payloads - Improved gitignore unignore handling - Blocked MCP agent runs without a workspace open ##### 2.1.6 - April 10, 2026 New Features - OpenCode Agent Provider — full support for OpenCode as an Agent Mode provider, including ACP integration, dynamic model polling, settings, and discovery Improvements - Agent providers gated by connected CLIs — Agent Mode only shows providers whose CLIs are actually available - Codex CLI path preflight — validates the Codex executable before launching, with clearer error messages when the CLI isn't found - Improved Codex connection flow — clearer setup and authentication UI for Codex - Improved CLI process launching — better detection of your PATH variables ensures CLI providers launch more reliably Fixes - Fixed agent transcript scrolling — restored transcripts now scroll correctly - Fixed prompt export — exports now correctly use the workspace root - Fixed Codex error reporting — errors are now shown instead of failing silently Removed - Sidebar terminal — removed the integrated terminal from the sidebar ##### 2.1.5 - April 8, 2026 New Features - context\_builder and oracle can now export their responses directly - Orchestrate workflow available as an MCP prompt and installable managed skill - GPT-5.4 Mini API model variants with low, high, and xhigh reasoning tiers Improvements - Agent mode elapsed timer stays accurate when steering active sessions - Improved scroll behavior in agent transcripts — better detection of manual scroll intent - Smarter workspace binding — bind\_context falls back to repo\_paths superset matching when no exact match exists - Orchestrate workflow uses phased verify-then-steer loop for more reliable agent delegation Fixes - Fixed Codex not being able to perform edits in Pro Edit mode - Fixed several issues related to ACP - Fixed stale agent sessions after app restart — orphaned active states are now properly cancelled ##### 2.1.4 - April 8, 2026 New Features - Gemini CLI now uses ACP — text streaming, permission support, bash tool access, automatic model detection, and significantly better performance - Orchestrate workflow — new agent workflow for planning tasks and delegating to sub-agents - Interview mode — agents can ask clarifying questions before starting a workflow to ensure clarity on the task - Reasoning levels for OpenAI custom models — choose reasoning effort when using custom OpenAI Responses API models - Claude CLI system prompt options — control how the RepoPrompt system prompt is delivered, including passing it as a user message - Provider filtering in recommendations — temporarily filter out providers hitting rate limits so the recommendation system steers you elsewhere - Await multiple agents — agent\_manage tool can now wait on multiple running agent sessions simultaneously Improvements - Elapsed runtime display on active agent runs - Run-scoped cancel button for active MCP tool cards - Per-provider model registry with persistence and dynamic picker - Improved sidebar session ordering and session state filtering - Agent views performance improvements Fixes - Fixed schema definition for a tool that caused intermittent issues with some agents - Fixed workspace restore session binding during tab switches - Fixed MCP agent sub-agent spawning permissions and approval handling - Added a fix button to unstick the agent scrollview when it gets stuck ##### 2.1.3 - April 4, 2026 Improvements - Smarter workspace binding — bind\_context now resolves workspaces by matching repo paths against open folders - Auto-switches workspace in the target window when the matched workspace isn't already active - Clearer bind\_context responses showing match method, candidate counts, and actionable error messages Fixes - Fixed branch comparison diffs showing wrong files — review mode and MCP diff tools now use merge-base semantics, preventing base branch changes from being misattributed as your work - Fixed bash tool cards auto-expanding when the agent stream returned to idle - Filtered noisy diagnostic output from discovery agent logs ##### 2.1.2 - April 3, 2026 Improvements - Restored backwards compatibility for list\_tabs and select\_tab actions, easing migration from 2.0.x - Unified MCP client ID matching for more reliable tool connections across different client variants - RepoPrompt MCP tool permissions are now auto-approved, reducing manual approval prompts during agent runs - Clearer error messages when MCP tools can't find a valid context Fixes - Fixed permissions not being properly handled for sub-agents in some cases - Fixed steering sub-agents not working correctly in some cases - Fixed only being able to start one sub-agent at a time via MCP - Fixed stale terminal snapshots from previous agent runs interfering with new runs ##### 2.1.1 - April 2, 2026 Fixes - Fixed Claude Code support over MCP ##### 2.1.0 - April 2, 2026 New Features - MCP-controlled agents and sub-agents — start and steer Agent Mode sessions from external MCP clients or the CLI, with cross-family sub-agent support (Claude can steer Codex, Codex can steer Claude) - Agent role defaults — configure default models per agent role (explore, engineer, pair, design) with per-role override controls Improvements - Faster window restore — consolidated session data loading for less main-thread blocking - Cleaner MCP API — dedicated manage\_selection and prompt tools replace context\_state; chat tools renamed to oracle for consistency - New context\_bind tool — easier workspace binding via working directories - Cmd+W now stashes compose tabs instead of closing them Fixes - Improved app stability — fixed crashes on deeply nested directory trees - Fixed memory retention issues for large repositories - Fixed file\_search hanging on regex patterns with .\* or .+ quantifiers - Fixed detached transcript jump-to-top restore
--- ## Code Reviews & Git RepoPrompt provides AI-powered code reviews that go far beyond simple diff analysis. By automatically mapping the full context of your changes—affected files, dependencies, and related code paths—reviews can understand not just *what* changed, but *why* it matters and *how* it fits into your codebase. ### Deep Code Reviews When you request a code review, RepoPrompt's Context Builder automatically: - **Maps your changes** – Identifies all modified, added, and deleted files - **Traces dependencies** – Finds files that call into or are affected by your changes - **Gathers context** – Selects the most relevant source files to understand intent - **Generates review artifacts** – Creates structured diff summaries optimized for review This curated context is then sent to a dedicated review model, enabling thorough analysis of correctness, security implications, API changes, error handling, and edge cases. #### What makes this different Traditional diff-based reviews show line changes in isolation. RepoPrompt's approach ensures the reviewer has enough surrounding context to catch issues that only become apparent when you understand how the code fits together—like a renamed function that breaks a caller in another file, or a new edge case that an existing test doesn't cover. ### Running a Code Review The easiest way to run a review is with the `/rp-review` command in Claude Code: ```text /rp-review ``` This surveys your repository state and launches a full context-aware review of uncommitted changes. #### Reviewing specific scopes You can also target specific change scopes: - **Uncommitted changes** (default) – Everything not yet committed - **Staged changes** – Only what's staged for commit - **Recent commits** – Review the last N commits (e.g., `back:3`) - **Branch comparison** – Compare against trunk with merge-base semantics (e.g., `main`, `mergebase:origin/main`, or `main...HEAD`) ### Git Tool The `git` tool provides quick access to repository information without leaving your AI conversation: - **Status** – See your current branch, staged/modified/untracked files, and sync status - **Diff** – View changes at different detail levels (summary, file list, truncated patches, or full patches) - **Log** – Browse recent commit history with stats - **Show** – Inspect a specific commit's changes - **Blame** – See who last modified specific lines #### Multi-repository workspaces If your workspace contains multiple repositories, the git tool can query all of them at once, giving you a unified view of changes across your entire project. #### Git Worktrees Full support for git worktrees allows you to compare diffs across linked checkouts. The git tool displays worktree metadata including branch names and main checkout references. - **Worktree detection** – Automatically identifies worktree vs main checkout - **Targeting** – Use `:worktree` or `:main` suffixes on repo\_root to target specific checkouts - **Aliases** – Use `main` or `trunk` in compare specs to diff against your main branch using merge-base semantics For explicit control, use `mergebase:X` for working tree vs merge-base with `X`. The explicit forms `uncommitted:main` and `staged:main` also use merge-base semantics against the detected trunk branch. ### Jujutsu (jj) Support RepoPrompt natively supports [Jujutsu (jj)](https://github.com/martinvonz/jj), a modern version control system that's gaining popularity as a Git alternative. When you open a jj-managed repository, RepoPrompt automatically detects it and uses jj commands under the hood. #### What works the same - Code reviews, diffs, logs, and blame all work as expected - Multi-repository workspaces can mix Git and jj repos - Context Builder fully supports jj repositories #### Key differences from Git Jujutsu has a different mental model than Git, which affects some workflows: - **No staging area** – jj doesn't have a Git-style index. If you request "staged" or "unstaged" changes, RepoPrompt shows all uncommitted changes instead. - **Working copy is always a commit** – In jj, your working directory is itself a commit that gets amended as you work. This makes "uncommitted changes" semantically different but functionally similar for review purposes. If you're a jj user, RepoPrompt works naturally with your workflow. If you're curious about jj, it's worth exploring—especially for complex branching and history rewriting. ### Tips for Better Reviews - **Guide the focus** – Tell the reviewer what to prioritize: "Focus on security implications" or "Pay attention to the database migration changes" - **Specify what to compare** – Ask to review against a specific branch, or just the last few commits since your feature started - **Review before committing** – Catch issues while they're easy to fix - **Keep changes focused** – Smaller, cohesive changesets get better reviews - **Follow up on findings** – After the initial review, ask clarifying questions or request deeper analysis of specific areas ### See Also - [MCP Tools Reference](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-tools/) – Full parameter documentation - [Workflow Commands](https://repoprompt.com/docs/classic-2.1.0/mcp-server/workflow-commands/) – Other automated workflows like `/rp-build` --- ## Using AI RepoPrompt gives you two powerful ways to use AI with your code: copy optimized prompts to external AI services, or use the integrated Chat with professional diff editing. ### Compose Mode Build context in RepoPrompt, then use it with any AI service - ChatGPT, Claude.ai, Gemini, or any other. #### Basic Copy Workflow 1. Select files and configure your context (full, slices, codemaps) 2. Write your prompt describing what you want 3. Click **Copy** (or `⌘+C`) 4. Paste into your AI of choice 5. Get your response #### Pro Edit Copy Workflow For powerful reasoning models that can follow structured instructions: 1. Select a **Pro Edit** copy preset from the preset dropdown 2. Copy and paste to external AI (ChatGPT, Claude.ai, etc.) 3. The model responds with structured XML change instructions 4. Paste the response back into RepoPrompt's Apply panel 5. Review changes in professional diff view, then apply :::tip **Best Models for Classic Edition (as suggested in June 2026):** GPT-5.5 Pro (ChatGPT Pro web only), GPT-5.5 High via Codex CLI, Gemini 3 Pro, Claude Opus 4.6 — strong models for instruction following and reasoning. ::: #### When to Use Compose Mode - **Deep reasoning tasks:** Use the most powerful models (GPT-5.5 Pro via ChatGPT Pro, Gemini 3 Pro) for architectural decisions - **Cost control:** Use your existing ChatGPT Plus/Pro subscription, and add Claude Pro only if you want a second editing-focused option - **Privacy preferences:** Some prefer keeping code in browser-based AI - **Specialized models:** Access models not available via API ### Chat Mode Have AI conversations directly in RepoPrompt with your code context automatically included. #### Starting a Chat 1. Select your files (they become the chat's context) 2. Write your prompt or question 3. Click **New AI Chat** (or `⌘+N`) 4. Choose your model and settings 5. Send your message #### Chat Modes | Mode | Purpose | When to Use | | --- | --- | --- | | **Chat** | Conversation & questions | Asking questions, getting explanations | | **Plan** | Architecture & design | Planning changes before implementing | | **Edit** | Code modifications | Making actual code changes | #### Reviewing & Applying Changes When AI suggests code changes in Edit mode: - Changes appear in a professional diff view with syntax highlighting - Review each file's modifications line-by-line - Apply all changes at once, or select specific files - Undo applied changes if needed ### CLI Providers Use your existing AI subscriptions instead of per-token API costs. This is one of RepoPrompt's most powerful features. #### Available Providers | Provider | Subscription | CLI Tool | Best Models | | --- | --- | --- | --- | | Claude Code | Claude Pro/Max ($20-200/mo) | `claude` | Opus 4.6, Sonnet 4.5 (optional for light UI work / quick fixes) | | Codex CLI | OpenAI Plus/Pro ($20-200/mo) | `codex` | GPT-5.5 Low for explore/discovery; GPT-5.5 Medium for engineer/default implementation; GPT-5.5 High for heavier planning/review/pair; GPT-5.4 Medium/High/XHigh still available | | Gemini CLI | Google AI subscription | `gemini` | Gemini 2.5 Pro/Flash | #### Why Use CLI Providers? - **No per-token costs:** Use models you're already paying for - **Latest models:** Access new releases through official CLIs - **Works everywhere:** Chat, Context Builder, Pro Edit all use CLI providers - **Familiar auth:** Uses CLI's existing authentication #### Setup Steps 1. **Install the CLI:** - Claude Code: `npm install -g @anthropic-ai/claude-code` - Codex: `npm install -g @openai/codex` - Gemini: `npm install -g @anthropic-ai/gemini-cli` 2. **Login:** Run `claude login`, `codex login`, or `gemini login` 3. **Connect:** In RepoPrompt, go to Settings → CLI Providers → Connect 4. **Test:** Verify connection with the test button ### API Keys For direct API access without CLI providers: 1. Go to **Settings → API Keys** 2. Add keys for your providers (OpenAI, Anthropic, Google, DeepSeek, etc.) 3. Keys are stored securely in macOS Keychain 4. Select your provider and model in Chat settings ### June 2026 Recommended Models Based on current performance and value: #### Fast & Affordable - **Gemini 2.5 Flash:** Excellent speed and quality balance - **GPT-5 Mini:** Fast, capable, good for simple edits - **DeepSeek Chat:** Very cheap with strong diff capabilities #### Complex Reasoning & Coding (as suggested in June 2026) - **GPT-5.5 High (Codex CLI):** Best all-around in-app coding and reasoning model in our current testing - **GPT-5.5 Pro (ChatGPT Pro web):** Best for deep planning and high-value reasoning sessions — use ChatGPT Export - **Claude Opus 4.6:** Still great for editing-heavy work and UI polish - **Grok 4:** Capable alternative with diff support #### Best Value (as suggested in June 2026) - **GPT-5.5 Low/Medium (Codex CLI):** Best value split for explore and Context Builder/discovery (Low) plus engineer/default implementation (Medium) if you already use Codex CLI via ChatGPT Plus/Pro - **Claude Sonnet 4.5:** Reliable, diff-capable, great balance for quick fixes - **Gemini 3 Pro Preview:** Strong performance with speed #### Context Window Champions (as suggested in June 2026) - **Gemini 3.0:** 200K standard, 1M+ at higher pricing - **Claude models:** 200K tokens - **GPT-5.4 family:** 272K–1M tokens depending on interface (still the family behind the OpenAI API and OpenRouter) :::tip **Where GPT-5.5 lives:** GPT-5.5 Low/Medium/High are Codex CLI-only. GPT-5.5 Pro is ChatGPT Pro web only. Neither is available via the OpenAI API, Azure OpenAI, or OpenRouter — those endpoints continue to serve GPT-5.4. ::: ### Choosing the Right Approach (as suggested in June 2026) | Use Case | Recommended Approach | | --- | --- | | Quick questions, explanations | Chat mode with fast model (Gemini Flash, GPT-5 Mini) | | Simple single-file edits | Chat mode in Edit mode | | Complex multi-file refactors | Chat mode with Pro Edit enabled | | Deep architectural planning | Compose + GPT-5.5 Pro (ChatGPT Pro) for plan → Chat with GPT-5.5 High (Codex CLI) for implementation | | Cost-sensitive usage | CLI Providers with existing subscription | | Large codebase context | Context Builder → Pro Edit with high-context models | :::tip **Pro Workflow:** Use Context Builder (default: GPT-5.5 Low via Codex CLI) to select files → Compose with GPT-5.5 Pro on ChatGPT Pro for a detailed plan → Chat with GPT-5.5 Medium via Codex CLI in RepoPrompt to implement (or High for heavier review/pair sessions) → optionally use Claude Code on Claude Pro for light UI polish or quick fixes. ::: ### Video Tutorials Learn these concepts in action: [![What is RepoPrompt for? — Using AI documentation illustration](https://img.youtube.com/vi/ncY6cqOCd_Y/maxresdefault.jpg) What is RepoPrompt for? Prompt building essentials. Try the interactive demo at repoprompt.com/prompt-anatomy](https://youtu.be/ncY6cqOCd_Y) [![Rapid iteration with RepoPrompt — Using AI documentation illustration](https://img.youtube.com/vi/LSQBi0Vx3Y4/maxresdefault.jpg) Rapid Iteration with RepoPrompt Multi-file edits via XML modes. Best with GPT 4.1, Claude Sonnet 4.5](https://youtu.be/LSQBi0Vx3Y4) [![Agent Workflows with RepoPrompt](https://img.youtube.com/vi/060MqOx-Ex0/maxresdefault.jpg) Fitting RepoPrompt into Agent Workflows Context Builder → GPT-5.5 Pro plan → GPT-5.5 High (Codex) implementation → review](https://youtu.be/060MqOx-Ex0) --- ## Integrated Chat RepoPrompt's integrated chat feature allows you to interact with AI models directly within the application, eliminating the need to copy/paste to external services. ### Setting Up API Access Before using integrated chat, you need to configure your AI provider API keys: 1. Open RepoPrompt's settings 2. Navigate to the "API Keys" section 3. Enter your API keys for the services you plan to use (OpenAI, Anthropic, etc.) 4. API keys are stored securely in your system's keychain ### Starting a Chat Session 1. Select the files and compose your instructions in the "Compose" tab 2. Click the "New AI Chat" button at the bottom right of the window 3. A new Chat panel opens with your prompt pre-filled 4. Select your desired AI model from the dropdown (e.g., "GPT-5.4", "Claude 4.5", or "GPT-5.5 Low/Medium/High" via Codex CLI) 5. Click the "Send" button (arrow icon) to send your prompt to the AI ### Working with Different Models RepoPrompt allows you to select from various AI models with different strengths: - **Task-based selection:** - For detailed in-app reviews and complex edits: GPT-5.5 High via Codex CLI, Claude Sonnet 4.5, DeepSeek V3, or GPT-5.4 High via API - For quick iterations on smaller files: Gemini 3.0 Flash or Claude Haiku 4.5 - For exploring ideas with no file changes: Any available model - **Edit format options:** - **Diff Mode:** The AI provides only the specific changes needed (requires compatible models) - **Whole Mode:** The AI rewrites entire files (works with all models) - **Temperature setting:** 0 by default for optimal code editing accuracy. Can be raised for usecases requiring more creativity ### Working with AI Responses When the AI responds, RepoPrompt handles the reply intelligently: - Normal text responses are displayed in the chat history - Code snippets are syntax-highlighted for readability - If the AI provides structured code changes (using RepoPrompt's expected format), they appear as distinct change blocks - You can click on a change block to see the specific code diff ### Applying Code Changes 1. When the AI suggests code changes, review them in the response 2. Click the "Merge Changes" button to enter the review mode 3. A diff review screen appears, showing the proposed modifications for each affected file 4. Review the diffs carefully, ensuring they match your expectations 5. Click "Accept All Files" to apply all changes, or review and accept individual files 6. Click "Reset All Files" to discard all changes 7. Click "Exit Review" when done to return to the chat ### Continuing the Conversation After receiving a response: 1. Type your follow-up question or request in the chat input box 2. Click "Send" to continue the conversation 3. The AI maintains context from earlier messages in the conversation :::tip **Tip:** The integrated chat provides the most streamlined workflow for applying AI-suggested changes to your codebase, as it understands the XML diff format natively and provides a visual diff review interface. ::: :::tip **GPT-5.5 note:** GPT-5.5 Low/Medium/High are accessed through the Codex CLI provider, not through API keys. GPT-5.5 Pro is available only on ChatGPT Pro web and isn't an in-app chat option — use the **ChatGPT Export** workflow for it. ::: --- ## Pro Mode Pro Edit is RepoPrompt's advanced editing system that breaks down complex changes into smaller, focused tasks - each handled by the most appropriate AI model. It works in both Chat mode (automatic) and Compose mode (for external AI responses). ### How Pro Edit Works #### In Chat Mode (Automatic) When you enable Pro Edit in Chat mode: - The planning model analyzes your request and breaks it into per-file changes - Each file edit runs through a **delegate agent** - a sandboxed helper with constrained tools - Multiple files can be edited in parallel for faster results - You see clean diffs - the XML format is handled invisibly #### In Compose Mode (External AI) Pro Edit also works with powerful external models like GPT-5.5 Pro on ChatGPT Pro (web): - Copy your context to an external AI with Pro Edit format enabled - The model reasons deeply and responds with structured XML changes - Paste the response back into RepoPrompt - Pro Edit applies each change through delegate agents ### Delegate Agents Delegate agents are sandboxed helpers that make Pro Edit safer and more reliable: - **Single-file focus:** Each agent only edits one allowed file - **Constrained tools:** Agents can only read, search, and apply edits - nothing destructive - **Clear reporting:** Each agent reports exactly what changed (or if nothing changed) - **Parallel execution:** Multiple agents can run simultaneously for faster results ### Multi-Model Routing Pro Edit automatically selects the best model for each edit based on complexity: - **Simple edits:** Fast, cost-effective models (e.g., Gemini Flash 2.0) - **Complex edits:** Powerful models (e.g., Claude Sonnet, DeepSeek V3) - **Large files:** Models optimized for high token counts This happens automatically - you don't need to configure it. The app evaluates file size and change complexity to make the best choice. ### Enabling Pro Edit #### In Chat Mode 1. Select files and compose your instructions 2. Click "New AI Chat" 3. Enable the "Pro" toggle in the chat panel 4. Send your message - Pro Edit handles the rest #### In Compose Mode 1. Select your copy preset that includes Pro Edit format 2. Copy and paste into your external AI (ChatGPT, Claude.ai, etc.) 3. Copy the AI's XML response 4. Use Apply in RepoPrompt to trigger Pro Edit ### Configuration (Optional) While automatic routing works well for most cases, you can customize: 1. Click the gear icon next to the model dropdown 2. Assign specific models for different edit types: - **Simple Edits Model:** For small, straightforward changes - **Complex Edits Model:** For intricate multi-step changes - **Large File Model:** For files exceeding the size threshold 3. Adjust the "Large File Threshold" as needed ### Why Use Pro Edit? - **Safer edits:** Sandboxed agents with constrained tools reduce mistakes - **Cost effective:** Simple edits use cheaper models automatically - **Faster results:** Parallel execution across multiple files - **External AI support:** Use powerful reasoning models on their native platforms - **Less setup:** Automatic model selection and path resolution ### Best Practices - **For diff editing:** Use Claude Sonnet 4.5 or DeepSeek V3 - they produce precise diffs that merge cleanly - **For external AI (ChatGPT Pro web):** GPT-5.5 Pro and Grok 4.1 work excellently with Pro Edit format for deep reasoning tasks - **For in-app Codex CLI agent/review:** GPT-5.5 Medium/High are the recommended Codex CLI models for implementation and review — they are not available via the OpenAI API or OpenRouter - **For speed:** Gemini Flash 2.0 excels at whole-file rewrites for smaller files :::tip **Tip:** Pro Edit shines for complex multi-file refactors. The delegate agent system ensures each file gets focused attention while the automatic model routing keeps costs down. ::: --- ## Supported Models RepoPrompt integrates with multiple AI providers through their APIs, offering access to a wide range of language models for your development needs. ### Supported AI Providers #### OpenAI - **Available Models:** GPT-5.4 family (including GPT-5.4 Pro via API), GPT-5 Mini - **API Setup:** Requires an OpenAI API key from [OpenAI Platform](https://platform.openai.com/docs/overview) - **Features:** Most models support diff editing for precise code changes - **GPT-5.5 note:** GPT-5.5 Low/Medium/High are available only through Codex CLI, and GPT-5.5 Pro is available only on ChatGPT Pro web. Do not try to configure GPT-5.5 as an OpenAI API model — the OpenAI API continues to serve the GPT-5.4 family. #### Anthropic - **Available Models:** Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3.7 Sonnet, Claude 3.7 Sonnet Thinking, Claude 3.7 Sonnet Thinking Max - **API Setup:** Requires an Anthropic API key from [Anthropic Console](https://console.anthropic.com/settings/keys) - **Features:** Claude 3.5 and 3.7 models excel at precise code editing and understanding context #### Gemini - **Available Models:** Gemini 1.5 Pro, Gemini 1.5 Flash, Gemini 1.5 Flash 8b, Gemini 2.0 Flash, Gemini Flash Thinking, Gemini 2.5 Pro - **API Setup:** Requires a Gemini API key from [Google AI Studio](https://aistudio.google.com) - **Features:** Gemini 2.0 Flash and Gemini 2.5 Pro offer excellent performance for whole file editing #### DeepSeek - **Available Models:** DeepSeek V3, DeepSeek R1 - **API Setup:** Requires a DeepSeek API key from [DeepSeek Platform](https://platform.deepseek.com/api_keys) - **Features:** Both models support diff editing with strong code understanding capabilities #### GitHub - **Available Models:** GitHub-hosted GPT models - **API Setup:** Authenticate with GitHub account - **Features:** Access to OpenAI models for GitHub users without requiring separate API keys #### Azure OpenAI - **Available Models:** Custom deployed models via Azure - **API Setup:** Requires Azure resource name, deployment ID, API version, and key - **Features:** Enterprise-grade deployment with custom resource management #### OpenRouter - **Available Models:** Access to models from various providers, including DeepSeek, Qwen, OpenAI, Anthropic, and Google - **API Setup:** Requires an OpenRouter API key - **Features:** Single API to access multiple providers, including options not directly supported #### Local Models (Ollama) - **Available Models:** Any model deployed through Ollama or other local services - **API Setup:** Configure URL (default: http://localhost:11434) and select available models - **Features:** Run models locally without sending data to external services #### Custom Provider - **Features:** Connect to any OpenAI-compatible API endpoint - **API Setup:** Configure base URL, API key, and other parameters - **Use Cases:** Self-hosted models or alternative API providers ### Setting Up API Keys To configure your API keys in RepoPrompt: 1. Open RepoPrompt's settings 2. Navigate to the "API Keys" tab 3. Enter your API key for each service you want to use 4. Click "Validate & Save" to securely store and verify your key API keys are stored securely in your system's keychain and never shared with external services beyond the respective AI provider. ### Model Capabilities Different models have different capabilities when it comes to code editing: - **Diff Editing Capable:** Models like Claude Sonnet 4.5, DeepSeek V3, GPT-5.4, and Gemini 3 Pro can provide precise diff edits that only modify the necessary parts of a file. - **Whole File Editing:** All models can rewrite entire files, with models like Gemini Flash 2.0 excelling at this task for smaller files. - **GPT-5.5 (Codex CLI / ChatGPT Pro):** GPT-5.5 Low/Medium/High are Codex CLI recommendations and should not be configured as OpenAI API or OpenRouter model IDs. GPT-5.5 Pro is ChatGPT Pro web only. You can customize model capabilities in the Model Overrides settings, enabling or disabling features like diff editing and streaming for specific models. ### Pro Edit Settings RepoPrompt's Pro Mode intelligently distributes editing tasks across different models: - **Planning:** The primary model you select handles overall planning and complex decisions - **Simple Edits:** Typically handled by faster, more cost-effective models like Gemini Flash 2.0 - **Complex Edits:** Assigned to powerful models like Claude 3.7 Sonnet for difficult changes - **Large Files:** Processed by models with high context windows and diff capabilities The application automatically adjusts editing strategies based on file size and complexity. --- ## Apply Mode Apply Mode is a powerful feature that lets you take code changes suggested by external AI services (like ChatGPT web interface or Claude) and apply them directly to your local files. ### When to Use Apply Mode Apply Mode is ideal when: - You're using a web-based AI interface rather than RepoPrompt's integrated chat - You have existing conversations with AI services that you want to implement - You prefer using specific external AI services for certain tasks ### The XML Diff Format For Apply Mode to work, the AI response must use a specific XML format that includes: - ``: Overall explanation of the changes - ``: Container for changes to a specific file - ``: Individual edit within a file - ``: The original code to find - ``: The new code to replace it with ### Asking the AI for the Correct Format 1. In the "Apply" tab, select the files relevant to your task 2. Enter your instructions in the "Instructions" text area 3. Click the "Copy with Diff Edit Prompt" button 4. Paste the complete prompt into your external AI service 5. This prompt includes special instructions that ask the AI to respond using the required XML format ### Applying AI Suggestions 1. Once the AI responds with XML-formatted changes, copy the entire response 2. In RepoPrompt, click the "Apply" tab 3. Paste the AI response into the "AI Response" text area on the right side 4. Click the "Merge Changes" button 5. RepoPrompt will parse the XML and display the proposed changes in a diff review screen 6. Review each change carefully 7. Click "Accept All Files" to apply all changes, or review and accept individual files 8. Click "Reset All Files" to discard all changes 9. Click "Exit Review" when done ### Troubleshooting Apply Mode If the AI response doesn't parse correctly: - Ensure the response contains the proper XML tags (``, ``, etc.) - Check that file paths in the response match your actual project structure - Verify that the `` blocks exactly match portions of your actual files - Try using the "Copy with Diff Edit Prompt" button again to generate a clearer prompt :::tip **Tip:** For complex edits across multiple files, you may get better results by breaking your request into smaller chunks, focusing on related files in each request. ::: --- ## Multi File Edits RepoPrompt excels at handling code changes that span multiple files, providing a streamlined workflow for reviewing and applying complex edits. ### Understanding Multi-File Edits When an AI suggests changes that affect multiple files, RepoPrompt: - Organizes the changes by file for easy navigation - Provides a comprehensive diff view for each affected file - Allows you to accept or reject changes on a per-file basis - Maintains the integrity of your codebase during the process ### The Diff Review Interface After receiving suggestions (via integrated chat or Apply mode), the diff review interface shows: - **File List:** All affected files, organized by change type (edit, create, delete) - **Diff View:** Side-by-side comparison of original and modified code - **Line Numbers:** For precise identification of changes - **Highlighting:** Added lines (green), removed lines (red), and unchanged context ### Reviewing Changes 1. When changes are proposed, click "Merge Changes" to enter the review interface 2. Navigate between files using the file list on the left 3. For each file, carefully review the highlighted changes 4. Use the checkboxes or buttons to accept or reject changes for individual files ### Applying Changes After reviewing the proposed edits, you have several options: - **Accept All Files:** Apply all changes across all files - **Accept Individual Files:** Apply changes only to specific files - **Reset All Files:** Discard all proposed changes - **Exit Review:** Close the diff view and return to the previous screen ### Working with File Operations RepoPrompt handles different types of file operations: - **Edits:** Modifications to existing files - **Creations:** Entirely new files added to your project - **Deletions:** Removal of existing files ### Safety Features To protect your code, RepoPrompt provides several safety mechanisms: - Changes are only applied after explicit confirmation - Individual file acceptance lets you apply only the changes you want - The diff view clearly highlights all modifications for verification - Hitting reset on a file or all files restores the file to the state before the changes were applied :::tip **Tip:** For complex refactoring operations, review changes in logical order rather than alphabetically. Start with core components or interfaces, then move to implementations to ensure everything remains consistent. ::: --- ## Building Context The key to good AI responses is giving the right context - not too much, not too little. RepoPrompt Classic Edition gives you precise control over what context your AI sees. ### Multi-Root Workspaces RepoPrompt 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. ### Selection Modes (Classic Edition) Every file can be included in one of three ways, giving you fine-grained control over token usage: | 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 (Classic Edition) - **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 (Classic Edition) 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 (Classic Edition) 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. ### Codemaps (Classic Edition) 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 (Classic Edition) | 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 (Classic Edition) When you select files in Full or Slices mode, RepoPrompt 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. :::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. ::: ### File Tree (Classic Edition) The file tree helps AI understand your project structure and navigate relationships between files. #### Tree Options | 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 | #### Codemap Markers (Classic Edition) Files with available codemaps show a `+` marker in the tree. This helps AI know which files have structural information available. ### Presets Presets save and restore your complete context configuration - file selection, prompt, and app settings - in one click. #### What Presets Store - **File selection:** Which files are selected and in what mode - **Prompt content:** Your instruction text - **Copy format:** How the prompt is formatted for export - **App settings:** File tree mode, codemap mode, etc. #### Built-in Presets | Preset | Purpose | | --- | --- | | **Standard** | Clean formatting for any AI (ChatGPT, Claude, etc.) | | **Pro Edit** | XML format for structured changes - paste response back to apply | | **Plan** | Optimized for architectural planning and design discussions | ### Stored Prompts (Classic Edition) Save frequently-used instructions separately from presets. Stored prompts are reusable text snippets you can inject into any context. #### Creating Stored Prompts 1. Write your instruction in the prompt area 2. Click the prompt menu → "Save Prompt" 3. Name it (e.g., "Code Review Guidelines", "Refactoring Instructions") #### Using Stored Prompts - Access from the prompt dropdown menu - Click to insert into current prompt - Combine multiple stored prompts as needed ### Token Management The token counter shows your current context size. Different models have different limits: | 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 (Low/High) or ChatGPT Pro web (Pro); it is not an API model. | | 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 | #### Token Reduction Strategies If you're hitting token limits: - **Use codemaps:** Switch reference files from Full to Codemap mode - **Use slices:** Include only relevant sections of large files - **Be selective:** Remove files that aren't essential for the task - **Simplify tree:** Use "Selected" tree mode instead of "Full" - **Consider Gemini:** For massive contexts, Gemini's 1M+ tokens helps ### Context Builder (Classic Edition) Let AI select your context automatically. The Context Builder explores your codebase and recommends files based on your task. #### How It Works 1. Describe what you're trying to accomplish 2. Context Builder analyzes your codebase structure 3. Files are selected and organized by relevance 4. Review the selection, then use it for Chat or Compose #### Best Results - Be specific about your task ("Add dark mode to settings page") - Works best with CLI Providers (Claude Code or Codex) connected - Results include both files and a generated prompt summarizing context - You can refine the selection after it runs - For Codex users, the Context Builder default is GPT-5.5 Low for repeated discovery and explore passes. Use GPT-5.5 High (Codex CLI) for heavier planning, review, or pair work after discovery. #### Workflow Integration (Classic Edition) Context Builder works great as the first step in complex workflows: 1. Run Context Builder with your task description 2. Review and adjust the file selection 3. Use Compose to get a plan from a powerful model 4. Use Chat with Pro Edit to implement the plan ### Video Tutorials See context building in action: [![What is RepoPrompt for? — Building Context documentation illustration](https://img.youtube.com/vi/ncY6cqOCd_Y/maxresdefault.jpg) What is RepoPrompt for? Interactive prompt anatomy demo at repoprompt.com/prompt-anatomy](https://youtu.be/ncY6cqOCd_Y) [![Context Builder 2.0 — Building Context documentation illustration](https://img.youtube.com/vi/qHl116OG2DM/maxresdefault.jpg) Context Builder 2.0 AI-powered context selection with CLI Providers (Codex, Claude, Gemini)](https://youtu.be/qHl116OG2DM) [![Accelerate Agent Orientation — Building Context documentation illustration](https://img.youtube.com/vi/9tQijoWr-QM/maxresdefault.jpg) Accelerate Agent Orientation Bootstrap agents with rich context, skip the research phase](https://youtu.be/9tQijoWr-QM) --- ## API Keys Common questions about using API keys with RepoPrompt. ### Security Your API keys are stored securely on your local machine. They are never transmitted anywhere except directly to the respective API provider during requests. ### Adding/Removing Keys Manage your API keys in the RepoPrompt settings panel. ### Multiple Keys You can add keys for multiple supported API providers. --- ## MCP Troubleshooting MCP (Model Context Protocol) Server integration connects RepoPrompt with external editors and CLI agents. Whether you're using Cursor as an MCP client or running Cursor CLI as an Agent Mode provider, these troubleshooting steps cover common issues. ### Quick Diagnostics Before diving into specific issues, check these fundamentals: - **Server Status:** Verify MCP Server is enabled in RepoPrompt Settings → MCP Server Settings - **Service Running:** Look for the MCP server status indicator in RepoPrompt's toolbar - **Configuration:** Use "Copy Configuration" in MCP settings for system-specific paths ### Connection Issues #### Editor Can't Find CLI Server **Symptoms:** External editor reports "server not found" or "command not found" **Solutions:** - Use "Copy Configuration" in RepoPrompt's MCP Settings - paths are system-specific - Verify the CLI server path in the configuration points to your RepoPrompt.app bundle - Check that RepoPrompt is installed in /Applications/ or update the path accordingly - For Cursor: Try the "Install in Cursor" deeplink button instead of manual configuration #### Connection Refused **Symptoms:** Editor connects to CLI but gets "connection refused" errors **Solutions:** - Ensure MCP Server is enabled in RepoPrompt settings - Ensure RepoPrompt is running - the app must be open to accept connections - Restart RepoPrompt to reinitialize the MCP service - Check that no other RepoPrompt instance is running with conflicting socket ownership #### Permission Denied **Symptoms:** Connection attempts are blocked or rejected **Solutions:** - Look for pending approval prompts in RepoPrompt - all connections require user approval - Check the allowlist in MCP Settings if you previously approved this client - Review tool permissions - some tools might be disabled in settings - Restart the editor after approving the connection in RepoPrompt ### Tool Access Issues #### Tools Not Available **Symptoms:** Editor connects but MCP tools don't appear or are greyed out **Solutions:** - Check tool availability in MCP Settings - tools can be individually enabled/disabled - Ensure the client is properly approved in RepoPrompt's allowlist - Try disconnecting and reconnecting the editor #### Planning Tools Failing **Symptoms:** `request_plan` tool returns errors or no results **Solutions:** - Configure a planning model in MCP Settings → Planning Model - Verify API keys are valid for your selected planning model - Check that the model provider is responding (try a simple chat in RepoPrompt) - Ensure sufficient API credits/quota for the planning model #### File Operations Denied **Symptoms:** File reading or selection tools return permission errors **Solutions:** - Check workspace permissions - RepoPrompt needs access to your project folders - Verify file paths are within loaded workspaces - Ensure files aren't locked by other applications - Try refreshing the workspace in RepoPrompt ### Setup-Specific Issues #### Cursor Integration Problems (MCP Client) ##### Deeplink Installation Failed - Try manual configuration using "Copy Configuration" - Ensure Cursor is properly installed and up to date - Check that Cursor's MCP feature is enabled (may require Cursor Pro) - Manually add the configuration to Cursor's settings file ##### Cursor Shows Connection but No Tools - Restart Cursor after configuration - Check Cursor's MCP panel for connection status - Verify the configuration JSON is valid - Try disconnecting and reconnecting in Cursor's MCP settings #### Cursor CLI Agent Problems ##### CLI Not Found - Ensure the `cursor` command is available on your PATH - Try running `cursor --version` in your terminal to verify - On macOS, you may need to install the CLI command from Cursor's command palette ("Install 'cursor' command") ##### Model Discovery Fails - Test the Cursor CLI connection in Agent Mode settings - Ensure you're signed into your Cursor Pro or Business account - Check that Cursor is up to date — older versions may not support ACP - Try restarting Cursor and retesting the connection ##### Agent Session Won't Start - Verify Cursor CLI is properly authenticated - Check that no other Cursor agent session is conflicting - Ensure your workspace path is accessible to the Cursor process - Try starting with a simple workspace first to isolate the issue #### CLI Server Not Launching **Symptoms:** Editor can't start the CLI server process **Solutions:** - Check RepoPrompt installation integrity - reinstall if necessary - Verify system permissions for running the CLI executable - Ensure RepoPrompt is running - the CLI requires the app to be open - Try running the CLI server manually from Terminal to see error messages ### Performance Issues #### Slow Response Times **Solutions:** - Limit concurrent tool usage - avoid multiple heavy operations simultaneously - Optimize file selections - large selections can slow down operations - Check system resources - ensure adequate memory and CPU - Use `token_stats` tool to monitor context size #### Memory Issues **Solutions:** - Reduce the number of files in active selections - Use code maps instead of full file contents when possible - Close unused workspaces in RepoPrompt - Restart RepoPrompt periodically for long sessions ### Connection Stability Issues #### Frequent Disconnections **Symptoms:** Client repeatedly disconnects and reconnects **Solutions:** - Ensure RepoPrompt remains open during your session - Check the MCP dashboard for connection diagnostics - The CLI automatically reconnects after RepoPrompt restarts - allow a few seconds for reconnection - If connections keep failing, try restarting both RepoPrompt and your editor #### Client Shows Wrong Name **Symptoms:** Connection appears with incorrect client name in dashboard **Solutions:** - This typically resolves after the first message exchange with the client - Update RepoPrompt to the latest version and restart your MCP client ### Advanced Troubleshooting #### Multiple Connections Conflicting Only one editor should connect at a time for optimal performance: - Disconnect other MCP clients before connecting a new one - Check the allowlist in MCP Settings for active connections - Restart RepoPrompt to clear all connections - Use different RepoPrompt windows for different editors if needed #### Configuration Debugging For persistent issues, manually verify your configuration: - Check that the CLI server path exists: `/Applications/RepoPrompt.app/Contents/Resources/repoprompt-mcp` - Verify the configuration JSON syntax is valid - Test the CLI server manually: run it from Terminal to see direct error messages - Compare working configurations from "Copy Configuration" button ### Getting Additional Help If these solutions don't resolve your issue: - Check the MCP server status in RepoPrompt's toolbar for additional information - Try the configuration with a minimal test case (small workspace, few files) - Document the exact error messages and steps to reproduce :::tip **Pro Tip:** The "Copy Configuration" button in MCP Settings always generates the correct configuration for your specific system. When in doubt, use this rather than manual configuration to avoid path and permission issues. ::: --- ## Prompt Caching Details about how RepoPrompt handles prompt caching for efficiency. ### Caching Implementation Yes, when using Anthropic directly, prompt caching is employed. However, due to the complexity of file editing workflows, chat history is generated to ensure only the latest files are sent with each message, and as a result, this can interfere with some prompt caching techniques. --- ## Solo Project Information about the development team behind RepoPrompt. ### Development Team Yes, RepoPrompt is currently a solo project. --- ## What Is RepoPrompt [Watch the What Is RepoPrompt video walkthrough](https://youtu.be/ncY6cqOCd_Y?si=xODzv6OePJYZp_si) RepoPrompt is built to make your AI prompts laser-focused by grounding them in the most relevant files from your project. Instead of guessing what to include, you assemble rich, accurate context in just a few clicks. Use the Context Builder or the MCP Discover preset to automatically surface the files that matter. Let an AI model scan your codebase, understand the task, and curate the exact snippets the assistant needs—no more manual hunting around. Once the context is ready, RepoPrompt Chat delivers surgically precise edits. Keep full control as you review every change, or hand the wheel to your agent to drive longer workflows with industry-leading results. Want to see the anatomy of a great prompt? Explore the [visual prompt assembly demo](https://repoprompt.com/) for a guided breakdown. ### Rapid Iteration Because of RepoPrompt's efficient use of context, you can also use it to rapidly iterate on code using it's efficient XML Editing workflows. See how you can get complex multi file edits handled in seconds, with a tool that respects your time. [Watch the What Is RepoPrompt video walkthrough](https://youtu.be/LSQBi0Vx3Y4?si=iETS1YjzndhrRezy) ### Agent Orientation Every new agent session is like on-boarding a new hire into your codebase. Effective orientation can make all the difference because the initial tokens in a context window are so important to getting good results. Use RepoPrompt to kickstart every new session with the right context around your task to get better results faster. [Watch the What Is RepoPrompt video walkthrough](https://youtu.be/9tQijoWr-QM?si=ineT5WUNc65SvEIj) If that explanation doesn't cut it for you, see what Trevor (Gauntlet AI cohort 2 Alumn) has to say about it: Community explanation of context management: retain necessary information, omit irrelevant content, use codemaps, and distribute edits --- ## Windows Linux Information regarding the availability of RepoPrompt on Windows and Linux platforms. ### Current Status RepoPrompt is currently only available for macOS. ### Future Plans This is something being considered, but RepoPrompt is a native macOS app, which means it is built with deep mac native API integration. This is important for performance reasons (large repositories can tax your app quite easily), and also because file systems between operating systems require a lot of careful consideration. The current near term priority remains to support the mac version, but you can join the waitlist to be notified if platform availability changes: [https://forms.gle/TGx1ZuT3oqng7EuKA](https://forms.gle/TGx1ZuT3oqng7EuKA) --- ## Context Builder (File-selection) The Context Builder is RepoPrompt's most sophisticated feature - an AI-powered system that analyzes your entire codebase using advanced language models to intelligently recommend the most relevant files for your task. It combines tree-sitter syntax analysis, parallel query processing, and token-aware optimization to deliver precise context building for any development workflow. ### What is the Context Builder? The Context Builder uses AI to analyze your codebase and your prompt, then recommends files organized by priority (high, medium, low) that are most relevant to your task. This helps you: - Save time by automating file selection - Identify files you might have overlooked - Optimize token usage by focusing on the most relevant files - Organize files by importance to better structure your context ### Generating Recommendations 1. In RepoPrompt, navigate to the "Context Builder" tab 2. The builder will use your prompt from the main instructions area (or an override prompt if specified) 3. Select an AI model from the dropdown menu 4. Click the "Generate" button to start analyzing your codebase 5. A progress indicator will show the analysis stages 6. Once complete, recommended files will appear organized by priority ### Understanding Priorities Recommended files are categorized into three priority levels: - **High Priority (Red):** Most critical files directly related to your task - **Medium Priority (Orange):** Supporting files that provide important context - **Low Priority (Blue):** Files with some relevance that could be helpful Each priority level has a toggle button allowing you to show or hide files of that priority. A counter shows how many files are in each category. ### Token Estimation The Context Builder provides token estimation to help you understand the impact on your token usage: - **Tree:** Tokens used by the file tree structure - **Map:** Tokens used by the code map - **Prompt:** Tokens used by your instructions and other text This helps you stay within token limits for your selected AI model. ### Applying Recommendations After generating recommendations, you have two ways to apply them: - **Add:** Adds recommended files to your existing selection - **Replace:** Replaces your current selection with the recommended files You can also remove individual files from the recommendations by clicking the 'X' button next to each file. ### Context Controls For advanced users, the Context Controls section offers additional configuration options: - **Include File Tree:** Toggle to include or exclude the file structure in analysis - **Include Code Map:** Toggle to include or exclude the code map in analysis - **Parallel Queries:** Enable to process larger codebases by splitting analysis into smaller chunks - **Max Tokens per Query:** When using Parallel Queries, adjust this slider to control the token limit for each query chunk - **Override Prompt:** Use a custom prompt specifically for the Context Builder instead of the main instructions ### Model Considerations Different AI models have different characteristics when used with the Context Builder: - **GitHub-hosted models:** Have tight rate limits and a maximum context input of 8K tokens, making them less suitable for the Context Builder - **Gemini Pro 2.5:** Works better with "Parallel Queries" disabled due to rate limit constraints - **Empty Code Map:** If your code map appears empty (very low token count), consider updating your File Settings to use Auto or Complete Code Map mode ### Managing Recommendations After generating recommendations, you can: - **Save as Preset:** Save the current recommendations as a named preset in your workspace - **Revert:** Return to your previous file selection (before applying recommendations) - **Filter:** Toggle between high, medium, and low priority files to focus on what's most important ### Troubleshooting If you encounter issues with the Context Builder: - If an error occurs, check if your selected model has sufficient rate limits, especially when using parallel queries - If no recommendations are found, ensure your code map is present and consider adjusting your prompt to be more specific - If all recommendations are filtered out, enable at least one priority level (High, Medium, or Low) ### Advanced Features & Architecture Under the hood, the Context Builder leverages several sophisticated technologies: - **Multi-Model Architecture:** Separate model selection for Context Builder vs Chat allows optimization for different task types - **Tree-Sitter Integration:** Language-specific syntax analysis for 10+ programming languages (Swift, JavaScript, Python, C/C++, Rust, Go, Java, Dart, C#, TypeScript) - **Parallel Query Processing:** Intelligent codebase chunking with rate limit management for analyzing large projects - **Token-Aware Optimization:** Real-time token counting with model-specific limits to prevent context overflow - **Cross-Repository Analysis:** Multi-repository workspace support for complex project structures - **State Persistence:** Context Builder settings and results are saved with your workspace ### Performance Optimization For best performance with large codebases: - Enable "Parallel Queries" for projects with high token counts - Use Code Maps to reduce token overhead while maintaining semantic understanding - Choose models with higher token limits and better rate limit allowances - Consider using workspace presets to save optimized Context Builder configurations - Monitor token usage in real-time to stay within model limits ### Integration with Pro Features Context Builder integrates seamlessly with other Pro features: - **Pro Mode:** Context Builder selections automatically optimize for multi-model workflows - **MCP Integration:** External editors can trigger Context Builder analysis via MCP protocol - **Workspace Management:** Advanced preset system includes Context Builder configurations :::tip **Tip:** For optimal results, try different combinations of Context Controls settings. Smaller projects often work best with Parallel Queries disabled, while larger codebases may require it. Always use specific, detailed prompts about what you're trying to accomplish to help the AI better identify relevant files. ::: --- ## Filtering Files To prevent unnecessary files (like build artifacts or node\_modules) from cluttering your workspace view, RepoPrompt provides powerful filtering options using ignore patterns. ### Setting Up Ignore Patterns 1. Click the "Filters" button above the file tree panel 2. The "Ignore Patterns" modal window will appear with two tabs ### Global Default Patterns These patterns apply to all workspaces in RepoPrompt: 1. Click the "Global Default" tab in the Ignore Patterns modal 2. Edit the patterns in the text area (RepoPrompt includes sensible defaults) 3. Patterns follow `.gitignore` syntax 4. Common patterns include: `node_modules/`, `*.log`, `.git/`, etc. ### Local Folder Patterns These patterns apply only to specific folders in your workspace: 1. Click the "Local Folder" tab in the Ignore Patterns modal 2. Select the specific folder within your workspace using the "Select Folder" dropdown 3. Edit the patterns in the text area 4. If a `.repo_ignore` file exists in that folder, its contents will be loaded automatically ### Pattern Precedence When determining which files to show or hide: - Local folder patterns override global defaults - More specific patterns take precedence over general ones After saving your filter changes, files matching the ignore patterns will be hidden from the file tree, reducing clutter and making it easier to find relevant files. :::tip **Tip:** You can create a `.repo_ignore` file in your project repository to share filtering rules with team members. ::: --- ## Searching Files The search function in RepoPrompt helps you quickly locate specific files in large workspaces. ### Basic Search 1. Locate the "Search files" input box above the file tree panel 2. Type your search query (e.g., a file name or part of it) 3. The file tree will dynamically filter to show only matching files and their parent folders 4. Clear the search box to restore the full file tree view ### Advanced Search Patterns RepoPrompt supports pattern-based searching: - **Wildcards:** Use `*` to match any sequence of characters - Example: `*.css` shows only CSS files - Example: `*.test.*` might find test files with any extension - **Basic Regex:** Use regular expression patterns for more complex searches :::tip **Tip:** Combine searching with filtering to quickly isolate the specific files you need for your prompt context. ::: --- ## Selection Methods One of RepoPrompt's core features is the ability to selectively include files for context when working with AI models. This helps optimize token usage and improves the quality of AI responses. ### Selecting Files and Folders 1. In the file tree panel, browse to the files or folders relevant to your current task 2. Click the checkbox next to a file name to select it (the content will be included in the prompt) 3. Click the checkbox next to a folder name to select all files within that folder (including subfolders) 4. Selected files will appear as cards in the "Selected Files" panel on the right side 5. Deselect items by unchecking their corresponding checkboxes ### Drag and Drop For quick file selection from your system: - Drag files or folders from Finder/Explorer directly onto the RepoPrompt window - Dropped items will be added to your workspace and automatically selected ### Selection Best Practices - **Be selective:** Only include files directly relevant to your query - **Watch token limits:** Monitor the token count at the bottom of the window - **Include related files:** Add interface/type definition files that help understand structure - **Consider Code Maps:** For large files, consider using Code Maps instead of full content :::tip **Tip:** Selecting only the most relevant files not only saves tokens but also improves the focus and quality of the AI's response by reducing noise. For complex tasks, prioritize including files that define core interfaces or types first. ::: --- ## Sorting Files RepoPrompt offers flexible sorting options for both the main file tree and your selected files. ### Sorting the File Tree 1. Locate the "Sort" button in the toolbar above the file tree panel 2. Click the "Sort" button to open a dropdown menu 3. Choose your desired sorting criteria: - **Name (A-Z or Z-A):** Alphabetical sorting by file name - **Extension (A-Z or Z-A):** Group files by their type/extension - **Date (Newest or Oldest):** Sort by modification date ### Sorting Selected Files 1. In the "Selected Files" panel on the right, locate the "Sort" button 2. Click this "Sort" button to choose how the selected file cards are ordered: - **Name (A-Z or Z-A):** Alphabetical sorting by file name - **Tokens (Low-High or High-Low):** Sort by token usage ### Changing Selected Files View Next to the "Sort" button in the Selected Files panel, there are view toggle buttons: - **Folder icon:** Group selected files by their parent folders - **File list icon:** Show all selected files in a flat list :::tip **Tip:** Sorting by tokens is particularly useful for optimizing context size when working with token-limited LLMs. ::: --- ## Getting Started (Getting-started) :::caution Historical source This archived guide mixes later CE availability wording with historical IDE/Apply and token-limit descriptions. It is preserved for reference, not as the current CE feature or pricing specification. ::: ### Your First Steps Start by reading the **What is RepoPrompt for?** overview to learn how RepoPrompt assembles context for you. The video below showcases our latest presets and how they accelerate your first workflow: [Watch the Getting Started video walkthrough](https://youtu.be/-J3CwrTrAlE?si=x9-5PNQj_gKG90Ib) For more in-depth tutorials, check out our [RepoPrompt 101 Playlist](https://youtube.com/playlist?list=PLFg9suyZ1OnLh3Tv5bP6jvWXcKKTlI_4m) or the complete [Tutorial Playlist](https://www.youtube.com/playlist?list=PLFg9suyZ1OnIKYyoCbAGBaFB-QOAk1nSq). ### Free and Open Source RepoPrompt Community Edition is free and includes: - Access to all core features with a 32k token limit for copying and chatting - The ability to connect to your own AI providers (OpenAI, Anthropic, etc.) with your API keys - Full file selection, workspace management, and Apply Mode capabilities The 32k token limit is sufficient for most use cases, as model response quality tends to degrade beyond this limit. If you find yourself hitting this limit frequently, consider being more selective with your file choices to create more focused and effective prompts. Download the latest Community Edition release: - Visit the [latest GitHub release](https://github.com/repoprompt/repoprompt-ce/releases/latest) - Download the macOS build and follow the installation instructions - Visit the [source repository](https://github.com/repoprompt/repoprompt-ce) to contribute :::tip **Tip:** Focus on selecting the files most relevant to your task. Smaller, intentional context often produces more precise AI responses. ::: --- ## Multiple Workspaces RepoPrompt allows you to open multiple folders simultaneously, which is useful when working with related projects, referencing documentation, or including external libraries. ### Adding Another Folder 1. With a workspace already open, locate the toolbar above the file tree panel 2. Click the folder icon button ("**Open a new folder**") in this toolbar 3. Use the system dialog to select another folder you wish to add 4. The newly added folder will appear as another root item in the file tree panel ### Use Cases for Multiple Folders - **Related Projects:** Include both a frontend and backend repository - **Documentation:** Add a documentation folder alongside your code - **External Libraries:** Reference library source code while working on your project - **Package Dependencies:** Include package source code for better AI context :::tip **Tip:** You can select files from any of the open folders to include in your prompt, allowing you to provide the AI with a more complete picture of your codebase. ::: --- ## Navigating File Tree After opening a workspace, the panel on the left displays your project's file structure. ### Basic Navigation - Click the arrow icons (▶︎/▼) or on the folder name itself to expand or collapse a folder - Files within folders are displayed with appropriate file type icons - Use the scrollbar to move through larger file structures ### Folder Structure The file tree displays a hierarchical view of your project, similar to what you'd see in your system's file explorer or IDE: - Root folder (your workspace) - Subfolders (nested according to your project structure) - Files (shown within their parent folders) This familiar tree structure makes it easy to locate specific files or understand the organization of your project. --- ## Opening Workspace The first step in using RepoPrompt is opening a workspace containing the code files you want to work with. ### Opening a Project Folder When you launch RepoPrompt, you'll see the main interface with the "Workspaces" section on the left: 1. Click the "**Open Folder**" button to browse for a project directory 2. Navigate to your desired project folder in the system dialog that appears 3. Select the folder and click "Open" ### Using Recent Workspaces For folders you've previously opened: 1. Look for the folder name in the "**Recent workspaces**" list 2. Click the workspace name to open it directly Once opened, the folder's name will appear as the root in the file tree panel on the left, and its contents will be displayed below it. :::tip **Tip:** RepoPrompt remembers your workspace settings (selected files, active prompts, etc.) between sessions if you save your workspace. ::: --- ## Quick Start Get from download to your first AI prompt in under 5 minutes. ### 1. Install RepoPrompt - **Mac App Store:** Search "RepoPrompt" or visit [the App Store listing](https://apps.apple.com/app/repo-prompt/id6720712141) - **Direct Download:** Get the latest version from [repoprompt.com](https://repoprompt.com) ### 2. Open Your First Workspace 1. Launch RepoPrompt 2. Click **Open Folder** or drag a project folder onto the window 3. Your file tree appears in the left sidebar :::tip **Multi-Root Workspaces:** You can add multiple folders to analyze related projects together. Use File → Add Folder or drag additional folders. ::: ### 3. Select Files for Context Click checkboxes next to files you want to include. The token count updates in real-time. **Selection modes** (Pro feature for slices/codemaps): - **Full:** Complete file content (default) - **Slices:** Specific line ranges only - **Codemap:** Just function/type signatures - 10x token savings ### 4. Copy Your First Prompt 1. Write instructions in the prompt area (or use a preset) 2. Click **Copy** 3. Paste into ChatGPT, Claude, or any AI That's it! Your prompt includes your files, instructions, and formatting that helps AI understand your codebase. ### 5. (Optional) Set Up AI Integration #### Option A: CLI Providers (Use Existing Subscriptions) If you have Claude Pro/Max, ChatGPT Plus/Pro, or Google AI - use those subscriptions in RepoPrompt: 1. Go to Settings → CLI Providers 2. Connect your provider (requires CLI tool installed and logged in) 3. Use Chat mode without API costs #### Option B: API Keys For direct API access: 1. Go to Settings → API Keys 2. Add keys for OpenAI, Anthropic, Google, etc. 3. Select models in Chat mode ### What's Next? - **Learn context building:** Master codemaps and slices for efficient prompts - **Try Chat mode:** Have AI conversations with your code context - **Explore Pro Edit:** Let AI edit multiple files with professional diff review - **Set up MCP:** Use RepoPrompt with Claude Code or Cursor :::tip **Video Tutorials:** Check out the [RepoPrompt 101 Playlist](https://youtube.com/playlist?list=PLFg9suyZ1OnLh3Tv5bP6jvWXcKKTlI_4m) for visual walkthroughs. ::: --- ## Code Maps Code Maps are a powerful feature in RepoPrompt that provide LLMs with structural understanding of your code without sending the entire file content, significantly saving on token usage. ### What are Code Maps? Code Maps extract and summarize key structural elements from your code, such as: - Class and interface definitions - Function and method signatures - Type declarations This gives the AI a "map" of your codebase structure without needing the full implementation details. CodeMaps are designed to extract essential information about how to use a file from its public definitions, helping models avoid hallucinating function calls or enum definitions. ### Supported Languages CodeMaps currently support the following languages: - Swift (swift) - JavaScript (js) - C# (cs) - Python (py) - PHP (php) - C (c) - Rust (rs) - C++ (cpp) - Go (go) - Java (java) - Dart (dart) - TypeScript (ts, tsx) **Coming soon:** Ruby and Scala support. ### Configuring Code Maps 1. Click the gear icon next to the "Code Map" tab to open Code Map settings 2. Under "Code Map Usage", choose an option: - **None:** No code map is included - **Auto:** (Default) RepoPrompt automatically detects definitions based on available tokens and relevance - **Complete:** Includes all definitions found in the scanned files (use with caution, can be large) 3. Under "File Tree", choose how the file structure is represented: - **Auto:** Balance between token usage and context - **Full"** Include all files in the workspace - **Selected:** Only include selected files - **None:** Don't include file tree information ### Language Types and CodeMap Behavior CodeMaps behave differently based on language type: - **Strongly Typed Languages:** For languages like TypeScript, Swift, Java, etc., the Auto mode will automatically detect references to other files and include relevant file APIs in the final prompt. - **Dynamically Typed Languages:** For languages like JavaScript or Python, the Auto mode may not pick up all references. Complete mode may be more suitable for these languages to ensure comprehensive coverage. ### Benefits of Code Maps - **Token Efficiency:** Significantly reduces token usage for large files - **Structural Understanding:** Helps the AI understand code organization - **Type Awareness:** Preserves type information for better code analysis - **Expanded Context:** Allows including more files within token limits ### CodeMap Modes in Detail - **Auto Mode:** Balances token usage and context by intelligently selecting relevant definitions. - **Complete Mode:** Includes all extracted file APIs for files that are not selected, helping models gain a complete picture of the codebase at lower resolution than the files you're working with. This is particularly useful for understanding the broader codebase structure. ### Best Practices - Code Maps work best with strongly-typed languages (TypeScript, Swift, Java, etc.) - For small files or specific implementation details, include the full file instead - Use "Auto" mode for most cases to let RepoPrompt optimize token usage - Use "Complete" mode when the structural relationships are complex and critical, or when working with dynamically typed languages :::tip **Tip:** When you're asking for high-level architectural insights or structural changes, Code Maps are often more useful than full file content, as they help the AI focus on relationships between components. Try setting codemap to complete and deselecting all files. ::: --- ## Composing Prompts The core workflow in RepoPrompt involves composing prompts that combine your instructions with selected file context, then sending them to an AI for processing. ### The Compose Tab Workflow 1. Select relevant files from the file tree panel (they'll appear in the "Selected Files" panel) 2. Activate any stored prompts you want to use via the prompt tabs 3. Click on the "Instructions" tab if not already selected 4. Type your specific instructions or query in the main text area 5. Review the selected files and approximate token count at the bottom ### Copying for External Use To use your prompt with an external AI service (like ChatGPT web interface): 1. After composing your prompt as described above, click the "Copy" button at the bottom left 2. The fully formatted prompt (including instructions, file map, file contents, and system messages) is copied to your clipboard 3. Paste this complete prompt into your preferred external LLM chat interface ### Understanding the Generated Prompt The prompt RepoPrompt generates typically includes: - **System instructions:** From your active stored prompts - **Your specific query:** From the Instructions text area - **File map:** A structured outline of the selected files - **File contents:** The actual code from selected files - **Code Maps:** If enabled, structured summaries of code definitions :::tip **Tip:** For best results, be specific in your instructions about what you want the AI to do with the provided code. Mention file names explicitly when referring to them in your instructions. ::: --- ## Storing Prompts RepoPrompt's stored prompts feature allows you to save and reuse system prompts to guide the AI's role and output format. ### Understanding Stored Prompts Stored prompts in RepoPrompt are reusable system messages that: - Provide consistent instructions to the AI across different sessions - Define specific AI roles (like the built in "Architect" or "Engineer") - Structure the AI's output format for better consistency - Can be combined with your specific instructions ### Using Stored Prompts 1. Active stored prompts appear above the instructions text box. 2. Hover over a prompt tab to preview its content 3. Active prompts will be prepended to your instructions in the "Meta prompts" section when generating the final prompt ### Managing Stored Prompts 1. Click the "Prompts" button on the far right of the prompt tab bar 2. A dropdown list appears with available prompts 3. Clicking on a prompt will toggle it 4. Use the "Create New" or "Edit" options to manage your prompt library 5. You can import and export stored prompts from the advanced settings menu, using a bespoke json format. ### Creating Custom Prompts To create a new stored prompt: 1. Click the "Prompts" button and select "Create New" 2. Enter a name for your prompt (e.g., "Code Reviewer") 3. Write the prompt content in the editor 4. Save your new prompt to make it available in the prompts list :::tip **Tip:** Create specialized prompts for different tasks, such as code review, architecture planning, bug fixing, or feature implementation to maintain consistency across similar AI interactions. ::: --- ## Reference :::caution Historical source This archived guide mixes later CE availability wording with historical IDE/Apply and token-limit descriptions. It is preserved for reference, not as the current CE feature or pricing specification. ::: ### Supported AI Providers #### API Providers | Provider | Top Models | Context | | --- | --- | --- | | **OpenAI** | GPT-5.4 family, GPT-5 Mini | 272K–1M | | **Anthropic** | Claude Opus 4.6, Claude Sonnet 4.5, Claude Haiku 4.5 | 200K | | **Google** | Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 3 Pro | 1M+ | | **DeepSeek** | DeepSeek V3, DeepSeek R1 | 128K | | **xAI** | Grok 4 | 128K | | **Azure OpenAI** | Custom deployments | Varies | | **OpenRouter** | Access to multiple providers | Varies | | **Fireworks** | Qwen3, Kimi K2, GLM-4 | Up to 32K | | **Ollama** | Local models | Varies | | **Custom** | Any OpenAI-compatible endpoint | Varies | #### CLI Providers (Use Existing Subscriptions) | Provider | Subscription | CLI | Best Models | | --- | --- | --- | --- | | **Claude Code** | Claude Pro/Max | `claude` | Opus 4.6, Sonnet 4.5 (optional for light UI work / quick fixes) | | **Codex CLI** | OpenAI Plus/Pro | `codex` | GPT-5.5 Low for explore/discovery; GPT-5.5 Medium for engineer/default implementation; GPT-5.5 High for heavier planning/review/pair; GPT-5.4 Medium/High/XHigh still available | | **Gemini CLI** | Google AI | `gemini` | Gemini 2.5 Pro/Flash | ### Model Recommendations #### Fast & Affordable - **Gemini 2.5 Flash:** Excellent speed/quality, diff-capable - **GPT-5 Mini:** Fast, good for simple edits - **DeepSeek Chat:** Very cheap with strong diff support #### Complex Coding & Reasoning - **GPT-5.5 High (Codex CLI):** Best all-around in-app coding and reasoning model in our current testing - **GPT-5.5 Pro (ChatGPT Pro web):** Best for deep planning and high-value reasoning sessions - **Claude Opus 4.6:** Still excellent for editing-heavy work and UI polish - **Grok 4:** Capable alternative with diff support #### Best Overall Value - **GPT-5.5 Low/Medium (Codex CLI):** Best value split for explore and Context Builder/discovery (Low) plus engineer/default implementation (Medium) if you already use Codex CLI via ChatGPT Plus/Pro - **Claude Sonnet 4.5:** Reliable, diff-capable, great for quick fixes - **Gemini 3 Pro Preview:** Strong performance with speed Our current recommendation is to center your setup on OpenAI Plus/Pro so you can run GPT-5.5 Low/Medium/High via Codex CLI and GPT-5.5 Pro on ChatGPT Pro web. If you want Claude Code as a secondary option, Claude Pro is usually enough for light UI work and fast fixes. :::tip **GPT-5.5 availability:** GPT-5.5 Low, Medium, and High are Codex CLI-only, and GPT-5.5 Pro is ChatGPT Pro web only. GPT-5.5 is not offered through the OpenAI API, Azure OpenAI, or OpenRouter — those continue to serve GPT-5.4. ::: ### Keyboard Shortcuts | Shortcut or gesture | Action | | --- | --- | | `⌘+C` | Copy prompt to clipboard | | `⌘+N` | Start new AI chat | | `⌘+O` | Open folder/workspace | | `⌘+F` | Search files | | `⌘+,` | Open Settings | | `⌘+T` | New compose tab | ### URL Scheme Open workspaces directly via URL: ```text repoprompt://open?path=/path/to/folder ``` ### Availability RepoPrompt Community Edition is free and open source. Download releases or contribute through the [Community Edition repository](https://github.com/repoprompt/repoprompt-ce). ### Platform - **macOS:** Available now (Mac App Store or direct download) - **Windows/Linux:** Not currently available - RepoPrompt is built natively with Swift/SwiftUI ### Support & Community RepoPrompt is developed by a solo developer. Get help: - **Discord:** [Join the community](https://discord.gg/NtbFDAJPGM) ### Video Tutorials Watch the complete tutorial playlist: [![MCP + Cursor Oracle — Reference documentation illustration](https://img.youtube.com/vi/hdaOxCE-dbI/maxresdefault.jpg) MCP + Cursor Oracle Pair MCP with Cursor, use CLI providers as API backends](https://youtu.be/hdaOxCE-dbI) [RepoPrompt 101 Full Tutorial Playlist Complete walkthroughs covering all RepoPrompt features](https://www.youtube.com/playlist?list=PLFg9suyZ1OnIKYyoCbAGBaFB-QOAk1nSq) --- ## File Operations RepoPrompt provides several ways to interact with files beyond just selecting them for prompts. ### Previewing File Content To quickly examine a file's content without selecting it: 1. In the "Selected Files" panel on the right, hover over a file card 2. Click the magnifying glass icon that appears 3. A modal window will pop up showing the content of that file 4. Close the preview by clicking outside the modal or using its close button ### File Context Menu Right-clicking on any file or folder in the main file tree provides access to additional operations: - **Copy:** Copies the file's content to your clipboard - **Reveal in Finder/Explorer:** Opens the file's location in your system's file explorer - **Copy Relative Path:** Copies the file's path relative to the workspace root - **Copy Full Path:** Copies the file's absolute path on your system - **Select All Children:** (For folders) Selects all files within the folder - **Deselect All Children:** (For folders) Deselects all files within the folder ### Working with Multiple Files The file context menu also enables batch operations: - Right-click on a folder and use "Select All Children" to quickly include all files - Use "Deselect All Children" to remove all files in a folder from your selection - Hold Shift while checking boxes to select consecutive files :::tip **Tip:** The "Copy Relative Path" option is particularly useful when you want to explicitly reference a file in your prompt instructions. ::: --- ## File Watching RepoPrompt automatically monitors your workspace folders for changes, ensuring the file tree always reflects the current state of your project. ### Automatic File System Watching With file watching, RepoPrompt detects and reflects the following changes automatically: - **File additions:** New files appear in the file tree - **File deletions:** Removed files disappear from the tree - **File modifications:** Changed files are updated in selections - **Renames:** Renamed files are updated in the file tree - **Folder structure changes:** Moved or new folders are reflected ### Benefits of File Watching - Seamlessly work between RepoPrompt and your code editor - No need to manually refresh when files change - Always work with the most current version of your code - Changes made through the AI's suggestions are immediately available for next prompts ### Manual Refresh While rarely needed due to automatic watching, a manual refresh option is available: 1. Locate the "Refresh" button (circular arrow icon) above the file tree 2. Click this button to force RepoPrompt to rescan your workspace folders --- ## Managing Workspaces RepoPrompt allows you to save and manage workspaces, preserving your setup of open folders, selected files, instructions, and active prompts between sessions. ### Workspace Management Options The name of the currently open workspace is displayed in a dropdown menu at the top center of the window. Click this dropdown to access workspace management options: ### Saving a Workspace 1. Set up your workspace with the desired folders, file selections, and prompts 2. Click the workspace name dropdown at the top center 3. Select "Save Workspace" to preserve the current state 4. Your workspace configuration will be saved locally ### Switching Between Workspaces 1. Click the workspace name dropdown 2. Select a previously saved workspace from the list 3. RepoPrompt will load that workspace configuration, including open folders, selected files, and active prompts ### Closing a Workspace To save and close the current workspace: 1. Click the workspace name dropdown 2. Select "Save & Exit Workspace" 3. This will save the current state and return you to the initial screen ### Managing Specific Folders To close a specific root folder within the current workspace: 1. Locate the folder in the file tree panel 2. Click the "X" button next to its name 3. The folder will be removed from the current workspace, but the workspace itself will remain open ### Advanced Workspace Management 1. Click the workspace name dropdown 2. Select "Manage Workspaces..." 3. A modal will appear allowing you to rename, duplicate, or delete saved workspaces :::tip **Tip:** Create separate workspaces for different projects or tasks to quickly switch between them without losing your carefully curated file selections and prompts. ::: --- ## URL Scheme RepoPrompt supports a flexible URL scheme that allows you to open projects, workspaces, specific files, and pre-fill prompts directly from external applications or shortcuts. ### URL Scheme Format The basic format for RepoPrompt's URL scheme is: ```text repoprompt://open/[folderPath]?[parameters] ``` ### Components - **folderPath (Optional):** Appears immediately after repoprompt://open/. This can be: - An absolute path (/Users/...) - A path containing ~ for the home directory - May contain percent-encoded characters (e.g. %20 for spaces) - **Query Parameters:** Follow ? and can be combined with & - **workspace:** Opens or creates a workspace named "MyWorkspace" - **files:** Comma-separated list of files to select in the file tree - **prompt:** Pre-fills the prompt text in the main prompt area or chat - **ephemeral:** When set to true, creates a temporary workspace that isn't saved - **persist:** When set to false, prevents saving the workspace to disk - **focus:** When set to true, attempts to focus an existing window with the target workspace ### Examples #### Open a specific folder: ```text repoprompt://open/~/Documents/MyProject ``` #### Open a workspace named "Personal": ```text repoprompt://open?workspace=Personal ``` #### Open a folder and select specific files: ```text repoprompt://open/~/Projects?files=README.md,script.sh ``` #### Open a workspace and pre-fill prompt text: ```text repoprompt://open?workspace=Work&prompt=Review%20the%20latest%20updates ``` #### Create a temporary workspace that won't be saved: ```text repoprompt://open/~/Dev/TempProject?ephemeral=true ``` #### Focus an existing window with the target workspace: ```text repoprompt://open?workspace=Demo&focus=true ``` #### Full example with folder, workspace, files, and prompt: ```text repoprompt://open/~/Code?workspace=Demo&files=main.swift,AppDelegate.swift&prompt=Implement%20authentication%20logic&focus=true ``` ### Important Notes - Spaces or special characters must be percent-encoded (e.g., spaces become %20) - You can specify multiple files parameters or a comma-separated list for multiple files - Multiple prompt parameters will concatenate into one message - If ephemeral=true or persist=false, the workspace will not be saved to disk - focus=true tries to focus an existing window with the target workspace - Tilde (~) is automatically expanded to your home directory in all paths ### Use Cases The URL scheme is particularly useful for: - Creating desktop shortcuts to frequently used workspaces - Integration with automation tools like Shortcuts, Alfred, or Keyboard Maestro - Linking to specific project configurations from documentation - Setting up custom launch configurations for different development tasks :::tip **Tip:** Create Shortcuts on macOS to quickly open specific project configurations with pre-selected files and prompt text. This can dramatically speed up repetitive development tasks. ::: --- ## 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, RepoPrompt 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: 1. Right-click the file in the tree 2. Select "Show as API only" 3. The file is included as a codemap (10x fewer tokens) #### For Architecture Questions To understand your codebase structure: 1. Set Codemap mode to "Complete" in settings 2. Don't select any files in Full mode 3. 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 --- ## Context Overview The key to good AI responses is giving the right context - not too much, not too little. RepoPrompt gives you precise control over what context your AI sees. [![What is RepoPrompt for? — Context Overview documentation illustration](https://img.youtube.com/vi/ncY6cqOCd_Y/maxresdefault.jpg) What is RepoPrompt for? Overview of context building fundamentals](https://youtu.be/ncY6cqOCd_Y) ### The Anatomy of a RepoPrompt Every prompt you create in RepoPrompt 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 →](https://repoprompt.com/) ### Multi-Root Workspaces RepoPrompt 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 1. Browse the file tree and click files to select them 2. Use search to find specific files or content 3. Adjust selection modes (Full, Codemap, Slices) per file 4. Write your prompt and copy to AI #### AI-Powered Discovery 1. Open Context Builder and describe your task 2. Let the AI agent explore and select relevant files 3. Review and refine the selection 4. 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 RepoPrompt 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. More actions menu with Filters highlighted between Sort and Refresh **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`) Ignore Patterns editor with Local Folder and Global Default scopes and a list of excluded paths :::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 panel showing pending changes and diff inclusion options **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. ::: --- ## First Prompt Let's build your first AI prompt with rich code context. This takes about 2 minutes. ### Step 1: Open Your Project 1. Launch RepoPrompt 2. Go to **File → Open** (or `⌘+O`) 3. 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: ```text Add input validation to the login form. Check that: - Email is a valid format - Password is at least 8 characters - Show error messages below each field ``` 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 1. Click **Copy** (or `⌘+C`) 2. Paste into ChatGPT, Claude.ai, or any AI 3. Get your response 4. If it contains code changes, paste back into Apply view #### Option B: Use Built-in Chat 1. Click **New AI Chat** 2. Select your model and settings 3. Send - your context is automatically included 4. Review changes in the diff view ### Step 5: Apply Changes When the AI suggests code changes: 1. Review each file's changes in the diff view 2. Click **Apply All** or select specific files 3. Changes are written to your files 4. Use **Undo** if needed ### Watch It In Action [![Rapid Iteration with RepoPrompt — First Prompt documentation illustration](https://img.youtube.com/vi/LSQBi0Vx3Y4/maxresdefault.jpg) Rapid Iteration with RepoPrompt See the complete prompt-building workflow in action](https://www.youtube.com/watch?v=LSQBi0Vx3Y4) --- ## Interface Overview RepoPrompt'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. Compose View showing the file tree, selected files panel, and prompt area **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. Chat View showing the conversation thread, input bar, and model selector **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. Apply View showing Pro Edit XML ready for processing with parallel edits **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. Review View showing diff comparison and apply controls **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. ::: --- ## Classic IDE Mode Overview IDE Mode is part of the older RepoPrompt Classic Edition experience — a purpose-built workspace for crafting precise, token-efficient prompts that give AI models the deep understanding they need to write better code. ### What Is the old IDE Mode? IDE Mode (only available in the Classic Edition) gives you full manual control over what context your AI sees. Select files, choose how much of each file to include (full content, line slices, or API signatures), write your instructions, and send the result to any AI model — through built-in chat, copy-paste, or the MCP server. This is the approach that reasoning models like GPT-5.5 Pro (ChatGPT Pro web), Claude, and Gemini work best with: complete context upfront, so they can spend their thinking budget on your problem instead of searching for files. For in-app Codex CLI sessions, GPT-5.5 Medium/High are the recommended implementation and review models, while Low remains the explore/discovery default. ### The Four Views within the Classic Edition **Compose** Build context by selecting files, writing instructions, and choosing a copy preset. The primary workspace where everything starts. **Chat** Have AI conversations with your selected files automatically included as context. Switch models, use Pro Edit mode, and maintain history. **Apply** Paste AI responses containing code changes. Parses XML or Pro Edit format and queues edits for review. **Review** Side-by-side diff view to inspect, approve, or reject each file change before applying it to your codebase. ### Context Building Tools (Classic Edition) IDE Mode from the Classic Edition gives you precise control over what goes into your AI prompts: - **File Selection:** Click files in the tree to include them. Right-click for selection modes — full content, line slices, or codemap (API signatures only) - **Codemaps:** Tree-sitter powered function and type signatures. Include 10x more files in your context using a fraction of the tokens - **Line Slices:** Select specific line ranges from large files to include only the relevant sections - **Multi-Root Workspaces:** Load multiple project folders into a single workspace. Analyze monorepos, microservices, and related projects together - **Token Counter:** Real-time token count shows exactly how much context you're using ### Copy Presets (Classic Edition) Copy presets control how your context is formatted when you copy or send it. Each preset is designed for a specific workflow: - **Standard:** Clean format for pasting into any AI chat (ChatGPT, Claude, etc.) - **Plan:** Includes instructions for generating an architectural plan - **XML Edit / Pro Edit:** Formats for AI-assisted code editing with diff review - **MCP Builder:** Primes an MCP-connected agent with your context and the builder workflow - **MCP Pair:** Sets up a pair programming workflow between a driver agent and RepoPrompt's chat - **MCP Agent:** Gives an MCP agent general awareness of your project structure and tools ### Context Builder (Classic Edition) Don't want to manually select files? The **Context Builder** is an AI-powered tool that automatically explores your codebase and selects the right files for your task. It's a two-stage pipeline: 1. **Discovery Agent** — Explores your project structure, searches for relevant files, and builds a curated selection within a token budget 2. **Analysis Model** — Receives the curated context and produces plans, reviews, or answers grounded in your actual code Run Context Builder from the toolbar or use it through the MCP server and Agent Mode workflows. ### Built-in Chat (Classic Edition) The Chat view lets you talk to AI models with your full file context included automatically. Features include: - Multiple AI provider support (your own API keys or CLI providers) - Pro Edit mode for generating code changes that can be reviewed and applied - Conversation history with session tabs - Model selector for switching between different AI models ### Applying Changes (Classic Edition) Whether changes come from the built-in chat, a web AI, or an MCP agent, the Apply and Review views give you a consistent workflow for reviewing and applying them: 1. Paste the AI's response in the Apply view (or use chat's Pro Edit mode) 2. RepoPrompt parses the code changes and shows a diff for each file 3. Review each change, then apply the ones you approve --- ## 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 Copy presets dropdown for choosing a prompt format Chat Presets Chat preset menu for choosing instructions and included context ### Manual Controls Select "Manual" from either preset dropdown to configure each setting individually: Manual preset controls showing individual toggles for system prompt, file tree, git, and codemaps ### 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 1. Configure your selection, prompt, and settings 2. Click the preset dropdown → "Save as Preset" 3. Name your preset descriptively 4. 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. Stored prompts panel showing built-in categories and saved custom prompts #### 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: 1. Click "New" in the stored prompts panel 2. Write your instruction text 3. Name it descriptively (e.g., "Code Review Guidelines") 4. 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. ::: --- ## 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 RepoPrompt 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 --- ## Workflows IDE Mode in the Classic Edition supports several workflows for different task types — from quick questions to complex multi-file implementations. Choose the right workflow based on your task's complexity. ### Quick Reference (Classic Edition) | Workflow | When to Use | Best For | | --- | --- | --- | | **Copy & Paste** | Quick tasks, 1-2 files | Questions, small fixes, using web AI | | **Built-in Chat** | Interactive conversation | Iterating on ideas, code exploration | | **Architectural Planning** | 3+ files, complex tasks | New features, refactors, system changes | | **XML Pro Edit** | Multi-file code changes | When you need diff review before applying | | **Pair Programming** | Very large, iterative tasks | Major system changes, 10+ files | ### Copy & Paste (Classic Edition) The simplest workflow — and often all you need for small tasks: 1. Select the relevant files in the file tree 2. Write your instructions in the compose area 3. Choose a copy preset (Standard for most cases) 4. Copy and paste into your preferred AI (ChatGPT, Claude, Gemini, etc.) 5. Optionally paste the response back into the Apply view to review and apply code changes ### Architectural Planning (Classic Edition) For complex tasks, get a plan *before* you start implementing. This workflow uses Context Builder and a reasoning model to create an informed architectural plan: 1. **Describe your task** — Write what you want to accomplish 2. **Run Context Builder** — It explores your codebase and selects relevant files 3. **Copy with the Plan preset** — Sends context to a reasoning model (like GPT-5.5 Pro on ChatGPT Pro web, or GPT-5.4 Pro via API if you prefer direct API billing) 4. **Get an architectural plan** — The model generates a step-by-step implementation plan grounded in your actual code 5. **Hand off to implementation** — Give the plan to a coding agent (via MCP Builder preset) or implement manually. For Codex CLI implementation/review, GPT-5.5 Medium/High are our recommended models. This two-step approach (plan first, then implement) consistently produces better results than asking a model to both plan and implement in one shot. ### XML Pro Edit (Classic Edition) XML Pro Edit lets you apply multi-file code changes from AI responses with full diff review: - **XML Edit:** Paste XML-formatted code changes from web AI conversations into the Apply view. RepoPrompt parses the XML and shows each edit as a reviewable diff. - **Pro Edit:** Use the built-in chat with Pro Edit mode enabled. The AI generates structured changes that are automatically queued for review — no copy-paste needed. Both modes support multi-file changes and give you a side-by-side diff before anything touches your code. ### Pair Programming (Classic Edition) For very large changes spanning many files, the Pair Programming workflow uses two context windows working together: - **Driver agent** (Claude Code, Codex, etc.) — Manages the overall plan, selects files, coordinates tasks - **RepoPrompt Chat** — Receives curated context and writes the code, with fresh context for each step The driver breaks the plan into steps and sends each one to the chat with just the right files selected. The chat writes the code, the driver reviews it, and the cycle continues until the task is complete. ### Choosing the Right Workflow within the Classic Edition A simple decision tree: - **Small task (1-2 files)?** → Copy & Paste or Built-in Chat - **Need a plan before coding?** → Architectural Planning - **Want diff review of AI changes?** → XML Pro Edit - **Huge task, many files?** → Pair Programming - **Want fully automated?** → Switch to [Agent Mode workflows](https://repoprompt.com/docs/agent-mode/workflow-templates/) :::tip **Pro Tip:** If you're still using the Classic Edition, start with Architectural Planning for any task touching 3+ files. The upfront planning time pays for itself in fewer iterations and better code quality. ::: --- ## RepoPrompt Classic 2.1.0 ### About this archive This archive preserves the Classic documentation and historical guides, including older material no longer linked from the source navigation. Commands, model recommendations, prices, limits, and feature descriptions reflect the source rather than a newly verified current specification. For CE installation and agent workflows, start with [current RepoPrompt CE documentation](https://repoprompt.com/docs/). :::note Version history All Classic changelogs are retained here. The CE Version 1 changelog belongs to the [current CE documentation](https://repoprompt.com/docs/changelog/ce-version-1-0/). ::: ### Documentation table of contents #### MCP Server - [Overview](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-overview/) - [Setup Guide](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-setup/) - [Tools Reference](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-tools/) - [App Settings Tool](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-app-settings/) - [Transport Modes](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-transport/) - [Settings & Presets](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-settings/) - [Connection Management](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-connections/) - [Workflow Commands](https://repoprompt.com/docs/classic-2.1.0/mcp-server/workflow-commands/) #### Workflows - [Context Over Convenience](https://repoprompt.com/docs/classic-2.1.0/workflows/overview/) - [Discovery (Context Builder)](https://repoprompt.com/docs/classic-2.1.0/workflows/discovery/) - [Architectural Planning](https://repoprompt.com/docs/classic-2.1.0/workflows/architectural-planning/) - [MCP Builder Workflow](https://repoprompt.com/docs/classic-2.1.0/workflows/mcp-builder/) - [Orchestration](https://repoprompt.com/docs/classic-2.1.0/workflows/pair-programming/) - [Model Recommendations](https://repoprompt.com/docs/classic-2.1.0/workflows/model-recommendations/) #### AI Providers - [API Providers](https://repoprompt.com/docs/classic-2.1.0/ai-providers/api-providers/) - [CLI Providers](https://repoprompt.com/docs/classic-2.1.0/ai-providers/cli-providers/) - [OpenRouter](https://repoprompt.com/docs/classic-2.1.0/ai-providers/openrouter/) - [Custom Providers](https://repoprompt.com/docs/classic-2.1.0/ai-providers/custom-providers/) #### Code Reviews - [Code Reviews & Git](https://repoprompt.com/docs/classic-2.1.0/code-reviews/overview/) #### rp-cli - [Command Line Guide](https://repoprompt.com/docs/classic-2.1.0/rp-cli/cli-guide/) - [App Settings from the CLI](https://repoprompt.com/docs/classic-2.1.0/rp-cli/cli-app-settings/) #### Reference - [Keyboard Shortcuts](https://repoprompt.com/docs/classic-2.1.0/reference/shortcuts/) #### IDE Mode (Classic Edition) - [Overview](https://repoprompt.com/docs/classic-2.1.0/ide-mode/overview/) - [Workflows](https://repoprompt.com/docs/classic-2.1.0/ide-mode/workflows/) - [Context Overview](https://repoprompt.com/docs/classic-2.1.0/ide-mode/context-overview/) - [Interface Overview](https://repoprompt.com/docs/classic-2.1.0/ide-mode/interface/) - [File Selection](https://repoprompt.com/docs/classic-2.1.0/ide-mode/file-selection/) - [First Prompt](https://repoprompt.com/docs/classic-2.1.0/ide-mode/first-prompt/) - [Codemaps](https://repoprompt.com/docs/classic-2.1.0/ide-mode/codemaps/) - [Token Management](https://repoprompt.com/docs/classic-2.1.0/ide-mode/tokens/) - [Presets & Prompts](https://repoprompt.com/docs/classic-2.1.0/ide-mode/presets/) #### Changelog - [Classic Version 2.1](https://repoprompt.com/docs/classic-2.1.0/changelog/version-2-1/) - [Classic Version 2.0](https://repoprompt.com/docs/classic-2.1.0/changelog/version-2-0/) - [Classic Version 1.6](https://repoprompt.com/docs/classic-2.1.0/changelog/version-1-6/) - [Classic Version 1.5](https://repoprompt.com/docs/classic-2.1.0/changelog/version-1-5/) - [Classic Version 1.4](https://repoprompt.com/docs/classic-2.1.0/changelog/version-1-4/) - [Classic Version 1.3](https://repoprompt.com/docs/classic-2.1.0/changelog/version-1-3/) - [Classic Version 1.2](https://repoprompt.com/docs/classic-2.1.0/changelog/version-1-2/) - [Classic Version 1.1](https://repoprompt.com/docs/classic-2.1.0/changelog/version-1-1/) - [Classic Version 1.0](https://repoprompt.com/docs/classic-2.1.0/changelog/version-1-0/) #### Historical guides - [Using AI](https://repoprompt.com/docs/classic-2.1.0/historical-guides/ai/using-ai/) - [Integrated Chat](https://repoprompt.com/docs/classic-2.1.0/historical-guides/api-integration/integrated-chat/) - [Pro Mode](https://repoprompt.com/docs/classic-2.1.0/historical-guides/api-integration/pro-mode/) - [Supported Models](https://repoprompt.com/docs/classic-2.1.0/historical-guides/api-integration/supported-models/) - [Apply Mode](https://repoprompt.com/docs/classic-2.1.0/historical-guides/applying-changes/apply-mode/) - [Multi File Edits](https://repoprompt.com/docs/classic-2.1.0/historical-guides/applying-changes/multi-file-edits/) - [Building Context](https://repoprompt.com/docs/classic-2.1.0/historical-guides/context/building-context/) - [API Keys](https://repoprompt.com/docs/classic-2.1.0/historical-guides/faq/api-keys/) - [MCP Troubleshooting](https://repoprompt.com/docs/classic-2.1.0/historical-guides/faq/mcp-troubleshooting/) - [Prompt Caching](https://repoprompt.com/docs/classic-2.1.0/historical-guides/faq/prompt-caching/) - [Solo Project](https://repoprompt.com/docs/classic-2.1.0/historical-guides/faq/solo-project/) - [What Is RepoPrompt](https://repoprompt.com/docs/classic-2.1.0/historical-guides/faq/what-is-repo-prompt/) - [Windows Linux](https://repoprompt.com/docs/classic-2.1.0/historical-guides/faq/windows-linux/) - [Context Builder](https://repoprompt.com/docs/classic-2.1.0/historical-guides/file-selection/context-builder/) - [Filtering Files](https://repoprompt.com/docs/classic-2.1.0/historical-guides/file-selection/filtering-files/) - [Searching Files](https://repoprompt.com/docs/classic-2.1.0/historical-guides/file-selection/searching-files/) - [Selection Methods](https://repoprompt.com/docs/classic-2.1.0/historical-guides/file-selection/selection-methods/) - [Sorting Files](https://repoprompt.com/docs/classic-2.1.0/historical-guides/file-selection/sorting-files/) - [Getting Started](https://repoprompt.com/docs/classic-2.1.0/historical-guides/getting-started/getting-started/) - [Multiple Workspaces](https://repoprompt.com/docs/classic-2.1.0/historical-guides/getting-started/multiple-workspaces/) - [Navigating File Tree](https://repoprompt.com/docs/classic-2.1.0/historical-guides/getting-started/navigating-file-tree/) - [Opening Workspace](https://repoprompt.com/docs/classic-2.1.0/historical-guides/getting-started/opening-workspace/) - [Quick Start](https://repoprompt.com/docs/classic-2.1.0/historical-guides/getting-started/quick-start/) - [Code Maps](https://repoprompt.com/docs/classic-2.1.0/historical-guides/prompt-management/code-maps/) - [Composing Prompts](https://repoprompt.com/docs/classic-2.1.0/historical-guides/prompt-management/composing-prompts/) - [Storing Prompts](https://repoprompt.com/docs/classic-2.1.0/historical-guides/prompt-management/storing-prompts/) - [Reference](https://repoprompt.com/docs/classic-2.1.0/historical-guides/reference/reference/) - [File Operations](https://repoprompt.com/docs/classic-2.1.0/historical-guides/workspace-management/file-operations/) - [File Watching](https://repoprompt.com/docs/classic-2.1.0/historical-guides/workspace-management/file-watching/) - [Managing Workspaces](https://repoprompt.com/docs/classic-2.1.0/historical-guides/workspace-management/managing-workspaces/) - [URL Scheme](https://repoprompt.com/docs/classic-2.1.0/historical-guides/workspace-management/url-scheme/) ### Agent session handoff image This screenshot accompanied the later [CE Agent Sessions guide](https://repoprompt.com/docs/agent-mode/overview/). It is retained in this archive as historical interface media, not as a Classic feature specification. Handoff dialog showing session context and Oracle chats moving to a new agent --- ## App Settings Tool (3) The `app_settings` MCP tool lets agents read and write 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. Anything dangerous, secret, or workspace-specific is deliberately not exposed. :::tip **Companion pages:** Use this page for the MCP/JSON surface. For the same controls from a shell, see [App Settings from the CLI](https://repoprompt.com/docs/classic-2.1.0/rp-cli/cli-app-settings/). For the in-app UI equivalents, see [Settings Reference](https://repoprompt.com/docs/reference/settings/). ::: ### When to Use It - Match the user's preferred appearance or prompt packaging before building a copy preset. - Flip `mcp.auto_start` from setup scripts so RepoPrompt's listener launches with the app. - Reset `models.planning_model` to `null` so RepoPrompt falls back to defaults. - Temporarily disable Code Maps globally via `code_maps.globally_disabled` during large refactors. - Toggle edit-format defaults (`editing.file_edit_format`) before sending an edit-producing request. ### Operations | `op` | Selectors | Purpose | | --- | --- | --- | | `list` | optional `group` | Browse the allowlist catalog. Each entry includes the current value and, for keys that have them, `options_available: true`. | | `get` | exactly one of `key`, `keys`, `group` | Read one or more setting values. Selectors are mutually exclusive. | | `set` | `key` and `value` | Update exactly one setting. `keys` and `group` are rejected on `set`. | | `options` | `key`, optional `agent`, `limit`, `detailed` | List candidate values for keys that advertise `options_available: true` (today: the model settings). | #### Parameters | Parameter | Type | Notes | | --- | --- | --- | | `op` | `list \| get \| set \| options` | Required. | | `group` | string | `ui \| prompt_packaging \| editing \| models \| context_builder \| mcp \| code_maps`. Used by `list` and as a selector for `get`. | | `key` | string | Fully-qualified key (e.g. `ui.appearance_mode`). Required for `set`; optional selector for `get`. | | `keys` | array of string | Multi-key selector for `get`. Mutually exclusive with `key` and `group`. | | `value` | boolean \| number \| string \| null | Required on `set`. Accepted types match the entry's declared `type` in the catalog. | | `agent` | string | For `options` on model settings: filter candidates to one CLI backend (e.g. `claudeCode`, `codexExec`, `gemini`). | | `limit` | integer | For `options`: maximum number of candidates returned (1–200, default 60). | | `detailed` | boolean | For `options`: include descriptions and model metadata in each candidate. | ### Groups The allowlist is organized into seven groups so an agent can browse narrowly before reaching for `set`. If you are not sure about the exact key, type, or allowed values, call `list` first; `set` validates strictly and rejects unknown or out-of-range values without partial application. #### `ui` — Appearance and chrome | Key | Type | Details | | --- | --- | --- | | `ui.appearance_mode` | string enum | `System` \| `Light` \| `Dark`. App appearance mode. | | `ui.show_tooltips` | boolean | Whether RepoPrompt shows app tooltips. | | `ui.enable_keyboard_shortcuts` | boolean | Global keyboard shortcuts. New/changed shortcuts may only take effect after reopening a window. | #### `prompt_packaging` — How prompts are assembled | Key | Type | Details | | --- | --- | --- | | `prompt_packaging.prompt_sections_order` | JSON string array | Serialized ordering of prompt sections; must contain each prompt section exactly once. Call `{"op":"list","group":"prompt_packaging"}` first and read the `allowed_items` array for this key to get the canonical list of prompt section raw values before sending `set`. | | `prompt_packaging.duplicate_user_instructions_at_top` | boolean | Whether user instructions are duplicated at the top of packaged prompts. | | `prompt_packaging.file_path_display_option` | string enum | `Full` \| `Relative`. How file paths are displayed in packaged context. | | `prompt_packaging.selected_files_sort_method` | string enum | `nameAscending` \| `nameDescending` \| `tokenAscending` \| `tokenDescending`. | | `prompt_packaging.include_datetime_in_user_instructions` | boolean | Whether packaged user instructions include the current date/time. | #### `editing` — Edit-format defaults | Key | Type | Details | | --- | --- | --- | | `editing.file_edit_format` | string enum | `Diff` \| `Whole` \| `None`. Preferred edit format for edit-producing requests. | | `editing.allow_diff_models_to_rewrite` | boolean | Whether diff-oriented models may fall back to whole-file rewrites when needed. | | `editing.complex_edit_strategy` | string enum | `Single query` \| `Parallel split` \| `Sequential split`. | #### `models` — Model selection and inference defaults | Key | Type | Details | | --- | --- | --- | | `models.preferred_compose_model` — **Built-in Chat Model** | string \| null | Preferred Built-in Chat model raw identifier, if set. Advertises `options_available: true`. Set `null` to clear. | | `models.planning_model` — **Oracle Model** | string \| null | Preferred Oracle model raw identifier, if set. Advertises `options_available: true`. Set `null` to clear. | | `models.sync_chat_model_with_oracle` — **Sync Built-in Chat with Oracle** | boolean | Whether the Built-in Chat model is kept in sync with the Oracle model. | | `models.temperature` | number | Range `0.0`–`2.0`. Only applied when `models.temperature_enabled` is `true`. | | `models.temperature_enabled` | boolean | Whether the global temperature is sent with model requests. | | `models.custom_planning_prompt` — **Custom Oracle System Prompt** | string | Custom system prompt used by the Oracle. Empty string restores the built-in default. | #### `context_builder` — Context Builder agent & model | Key | Type | Details | | --- | --- | --- | | `context_builder.agent` | string enum | CLI agent used by the Context Builder MCP tool. Allowed values come from the installed discover backends (for example `claudeCode`, `codexExec`, `gemini`); call `list` and read `allowed_values` for the current set. Writes preserve that backend's remembered model when one exists, or fall back to its default. | | `context_builder.model` | string \| null | Model raw identifier used by the Context Builder MCP tool. Reads and writes the remembered model for the currently selected `context_builder.agent`; set `null` to clear that slot. Advertises `options_available: true`; by default, `op=options` scopes candidates to the current backend. | #### `mcp` — MCP server preferences | Key | Type | Details | | --- | --- | --- | | `mcp.auto_start` | boolean | Whether the MCP listener auto-starts when RepoPrompt launches. Does not immediately stop or start the current listener. | | `mcp.show_model_presets` | boolean | Whether MCP model preset recommendations are shown. | #### `code_maps` — Global Code Maps toggle | Key | Type | Details | | --- | --- | --- | | `code_maps.globally_disabled` | boolean | When `true`, Code Maps are globally disabled and the MCP `get_code_structure` tool is suppressed. | ### Examples (MCP JSON) Each example shows the arguments object passed to `app_settings`: ```text // Browse the full catalog (values always included) { "op": "list" } // Inspect one group { "op": "list", "group": "ui" } // Batch read a few keys { "op": "get", "keys": ["ui.appearance_mode", "mcp.auto_start"] } // Toggle a boolean { "op": "set", "key": "ui.show_tooltips", "value": false } // Update an enum { "op": "set", "key": "ui.appearance_mode", "value": "Dark" } // Clear an optional model (null is valid for nullable keys) { "op": "set", "key": "models.planning_model", "value": null } // Change a numeric setting { "op": "set", "key": "models.temperature", "value": 1.25 } // Switch the Context Builder agent (remembered model is preserved) { "op": "set", "key": "context_builder.agent", "value": "codexExec" } // List candidate models for the current Context Builder backend { "op": "options", "key": "context_builder.model" } // Narrow candidates to one CLI backend { "op": "options", "key": "models.planning_model", "agent": "codexExec", "limit": 25 } ``` ### Error Behavior - **Unknown keys:** Rejected with a clear error. Call `list` (or `list` with a `group`) to discover the correct key. - **Wrong types:** Booleans, numbers, strings, and `null` are each validated against the entry's declared `type`. - **Out-of-range values:** Numeric ranges (e.g. `models.temperature` 0.0–2.0) and enum values are enforced. - **No partial application:** Validation fails closed — if any check fails, nothing is written. - **One key per `set`:** Passing `keys` or `group` on `set` is rejected. ### Safety & Deliberately Excluded This surface is intentionally narrow. The following are **not** reachable through `app_settings` and must be managed in the Settings UI: - API credentials for any provider. - MCP tool ACLs and agent permission documents. - Workspace approvals and workspace-scoped chat/copy settings. - Agent-mode scalars and model override dictionaries. - Internal/migration-style flags and experimental toggles. If a preference is dangerous, secret, or workspace-specific, it is kept UI-only by design. Agents can still discover what *is* reachable with `op=list`. ### See Also - [App Settings from the CLI](https://repoprompt.com/docs/classic-2.1.0/rp-cli/cli-app-settings/) — the same allowlist via `rp-cli`. - [MCP Tools Reference](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-tools/) — schemas for every MCP tool. - [Settings Reference](https://repoprompt.com/docs/reference/settings/) — the in-app Settings UI equivalents. - [MCP Server Overview](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-overview/) — IDE-for-agents framing and capability map. --- ## Connection Management (3) RepoPrompt 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, RepoPrompt 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 RepoPrompt 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: ```text // List all workspaces across windows { "action": "list" } // Switch a window to a different workspace { "action": "switch", "workspace": "MyProject", "window_id": 2 } // Open workspace in a NEW window and bind connection to it { "action": "switch", "workspace": "MyProject", "open_in_new_window": true } // Returns: { "action": "switch", "status": "ok", "window_id": 3 } // Create a new workspace { "action": "create", "name": "NewProject" } // Create a new workspace and switch to it { "action": "create", "name": "NewProject", "switch_to_created": true } // Create a new workspace in a NEW window { "action": "create", "name": "NewProject", "open_in_new_window": true } // Returns: { "action": "create", "status": "ok", "window_id": 3 } // Add folder to workspace { "action": "add_folder", "workspace": "MyProject", "folder_path": "/path/to/folder" } ``` ### Tab Management Compose tabs allow parallel work contexts within a single window. MCP clients can manage tabs programmatically: #### Listing Tabs ```text // List tabs in current window { "action": "list_tabs" } // 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: ```text // Bind to a specific tab for consistent context { "action": "select_tab", "tab": "Feature-Auth", "focus": false } // 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. ```text // Create a blank background tab and bind this MCP connection to it { "action": "create_tab", "name": "Bugfix", "bind": true, "focus": false } // Fork an existing tab into a new background tab { "action": "create_tab", "mode": "fork", "source_tab": "Feature-Auth", "name": "Feature-Auth Follow-up" } ``` `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 RepoPrompt applies safety checks to prevent destructive or confusing behavior. ```text // Close a non-active tab by name or UUID { "action": "close_tab", "tab": "Bugfix" } // Explicitly allow closing the currently visible tab { "action": "close_tab", "tab": "Bugfix", "allow_active": true } ``` - 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. ```text // List recent chats for the currently bound tab { "action": "list", "scope": "tab" } // Read recent messages from the current tab's most recent chat { "action": "log", "scope": "tab", "limit": 10 } // Inspect a specific tab explicitly { "action": "list", "scope": "tab", "tab_id": "TAB-UUID-HERE" } ``` When `scope` is `tab` and `tab_id` is omitted, RepoPrompt 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: 1. **Server Start:** RepoPrompt opens listening socket/creates filesystem inbox 2. **Client Launch:** External tool spawns `repoprompt-mcp` CLI 3. **Handshake:** CLI establishes connection and exchanges capabilities 4. **Approval:** User approves (or connection auto-approved from allowlist) 5. **Active:** Tool calls flow bidirectionally 6. **Disconnect:** Client closes or user stops server 7. **Cleanup:** Resources released, filesystem folders deleted ### Reconnection Behavior Connection management was significantly improved in 1.5.41: - **App Restart:** Connections automatically rebind when RepoPrompt 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. ::: --- ## MCP Server Overview (3) ### 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. RepoPrompt'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](https://repoprompt.com/docs/classic-2.1.0/rp-cli/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. MCP Server popover showing server controls, chat model presets, and context builder configuration **Key settings to configure:** - **Auto-Start:** Enable this so MCP is always available when you launch RepoPrompt - **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 RepoPrompt was ready. Restart your client (Cursor, Claude Code, etc.) to pull the updated list. ::: #### RepoPrompt as an IDE for Agents Think of RepoPrompt'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 RepoPrompt'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](https://repoprompt.com/docs/classic-2.1.0/mcp-server/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](https://repoprompt.com/docs/classic-2.1.0/mcp-server/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 → RepoPrompt 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`](https://repoprompt.com/docs/classic-2.1.0/rp-cli/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](https://repoprompt.com/docs/classic-2.1.0/rp-cli/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 RepoPrompt'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. ::: --- ## Settings & Presets (3) 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. MCP Server popover showing server controls, chat model presets, and context builder configuration 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. :::info **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. ```text // Agent discovers available models list_models → returns preset IDs and descriptions // Agent selects appropriate model for task chat_send(message: "...", model: "FastChat") ``` ### 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: 1. Analyzes the task requirements 2. Explores the codebase to find relevant files 3. Builds an optimized selection within token limits 4. 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. ```bash # After installation, you can run commands like: rp-cli tree # Show file tree rp-cli search "TODO" # Search codebase rp-cli context --all # Export full context ``` #### 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 ```bash # Instead of running: claude # Run: claude-rp # This automatically: # - Points to RepoPrompt's MCP config # - Enables strict MCP mode (ignores other configs) # - Disables Claude's built-in Read, Write, Edit, Glob, Grep tools ``` :::info **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: ```json { "mcpServers": { "RepoPrompt": { "command": "/path/to/repoprompt-mcp", "args": [] } } } ``` :::info **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](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-transport/) and [Connection Management](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-connections/) for details. --- ## Setup Guide (3) Get RepoPrompt's MCP server connected to your preferred AI tool in minutes. The server enables external agents to use RepoPrompt's powerful context building, code intelligence, and editing capabilities. ### Quick Setup 1. Open **Settings → MCP Server** 2. Enable the **MCP Server** toggle 3. Click the install button for your client (or copy configuration) 4. Restart your client and approve the connection in RepoPrompt ### Client-Specific Instructions #### Cursor (One-Click) 1. Open **Settings → MCP Server** in RepoPrompt 2. Click **"Install in Cursor"** 3. Restart Cursor 4. When Cursor connects, approve in RepoPrompt (check menu bar for dialog) #### Claude Code 1. Open **Settings → MCP Server** in RepoPrompt 2. Click **"Copy Configuration"** 3. Open Claude Code's MCP settings (`claude mcp add` or edit config file) 4. Paste the configuration 5. Restart Claude Code 6. Approve the connection when prompted in RepoPrompt #### Codex CLI (One-Click) 1. Open **Settings → MCP Server** in RepoPrompt 2. Click **"Install for Codex"** 3. This automatically configures your `codex.toml` with extended timeouts 4. Restart Codex and approve the connection #### Other MCP Clients 1. Open **Settings → MCP Server** 2. Click **"Copy Configuration"** to get the JSON config 3. Add to your client's MCP server configuration 4. The client will launch `repoprompt-mcp` automatically via stdio 5. Approve the connection in RepoPrompt ### Configuration Format The copied configuration follows the MCP standard format: ```json { "mcpServers": { "repoprompt": { "command": "/Applications/RepoPrompt.app/.../repoprompt-mcp", "args": [] } } } ``` 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, RepoPrompt 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 RepoPrompt has focus or look for a notification. ::: ### Verifying the Connection Once connected, you'll see the connection status in RepoPrompt'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 RepoPrompt 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 RepoPrompt 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 (3) Complete reference for all MCP tools available in RepoPrompt. 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: \[{start\_line, end\_line, description}\]} | | `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` | {extensions, exclude, paths} | | `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 {search, replace, all} 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`: ```bash rp-cli -e 'call apply_edits {"path":"file.ts","search":"old","replace":"new"}' 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 RepoPrompt'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](https://repoprompt.com/docs/classic-2.1.0/code-reviews/overview/) 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:** ```bash # Browse the catalog (values always included) { "op": "list" } # Inspect one group { "op": "list", "group": "ui" } # Batch read { "op": "get", "keys": ["ui.appearance_mode", "mcp.auto_start"] } # Toggle a flag { "op": "set", "key": "ui.show_tooltips", "value": false } # Clear an optional model { "op": "set", "key": "models.planning_model", "value": null } # Switch the Context Builder agent (remembered model is preserved) { "op": "set", "key": "context_builder.agent", "value": "codexExec" } # List candidate values for a setting that advertises options_available { "op": "options", "key": "models.planning_model", "agent": "codexExec" } ``` **See the standalone** [App Settings Tool](https://repoprompt.com/docs/classic-2.1.0/mcp-server/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 RepoPrompt'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:** 1. Call `agent_run op=start message="..."` → receive `session_id` 2. Call `agent_run op=wait session_id="..."` → blocks up to 5 min (or custom `timeout`) until input needed or terminal 3. When `status=waiting_for_input`, call `agent_run op=respond` with the returned `interaction_id` and an appropriate `response` 4. 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 ```bash # Discover available agents and workflows agent_manage op=list_agents agent_manage op=list_workflows # List recent sessions, filter by state agent_manage op=list_sessions limit=10 agent_manage op=list_sessions state=failed # Read a session transcript agent_manage op=get_log session_id="" limit=5 # Stop a running session agent_manage op=stop_session session_id="" # Clean up old MCP-originated sessions agent_manage op=cleanup_sessions session_ids=["",""] # Start a run and control it agent_run op=start message="Investigate the auth flow" agent_run op=wait session_id="" agent_run op=wait session_id="" timeout=10 # Steer and wait for result in one call agent_run op=steer session_id="" message="Now fix it" wait=true # Respond to a pending approval agent_run op=respond session_id="" interaction_id="" response="accept" # Respond to a question agent_run op=respond session_id="" interaction_id="" response="Use the staging API" # Start a workflow-backed run agent_run op=start workflow_id="" message="Add logout support" # Then use agent_run to wait/respond on the returned session_id # Orchestrate: start multiple agents in parallel, wait for the first to finish agent_run op=start model_id="engineer" message="Task A" detach=true # → session_id_1 agent_run op=start model_id="engineer" message="Task B" detach=true # → session_id_2 agent_run op=wait session_ids=["",""] timeout=60 # Poll all agents at once for a dashboard view agent_run op=poll session_ids=["","",""] # Use the orchestrate workflow for automatic planning and delegation agent_run op=start workflow_name="orchestrate" message="Refactor auth into separate module" ``` :::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 (3) RepoPrompt'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 RepoPrompt, the CLI bridge establishes a secure local socket connection: 1. External client launches `repoprompt-mcp` via stdio 2. CLI bridge connects to RepoPrompt through a local UNIX socket 3. Messages are forwarded bidirectionally between the client and RepoPrompt 4. 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 RepoPrompt 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 RepoPrompt 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. ::: --- ## Workflow Commands (3) Once connected, your agent gains access to workflow commands that dramatically uplevel its capabilities. These guide the agent through a complete cycle: understand the task, use Context Builder to explore all relevant code, generate an informed plan, then implement the full solution — with minimal steering required from you. Type `/repo` to see available commands like `/rp-build` for implementation workflows and `/rp-investigate` for deep bug investigation. Claude Code showing RepoPrompt slash commands for implementation and bug investigation workflows MCP Server onboarding showing quick install, workflow skills, and supported clients ### How Workflow Commands Work Each workflow command triggers a Context Builder pipeline through the MCP server. When an agent runs a command like `/rp-build`, here's what happens behind the scenes: 1. **Discovery Agent activates** — A specialized research model explores your entire codebase, following imports, references, and architectural patterns to find every relevant file 2. **Context is curated** — The discovery agent selects files within a token budget, using codemaps for reference files and full content for key files 3. **Analysis model reasons** — A powerful model receives the curated context and produces deep output — a plan, review, or investigation report 4. **Agent acts on the result** — Your agent receives the analysis and proceeds with implementation, fixes, or next steps This separation means the agent gets architecturally-grounded guidance without spending its own context window on exploration. The agent stays focused on implementation while Context Builder handles the research. ### Available Commands **/rp-build** End-to-end implementation workflow. Context Builder gathers all relevant files and architectural patterns, the analysis model creates a detailed implementation plan, then the agent implements it directly. Best for new features and significant additions. **/rp-review** AI-powered code review. Publishes git diffs alongside full codebase context so the review model understands not just what changed, but the surrounding architecture. Catches issues that surface-level reviews miss. **/rp-refactor** Two-pass refactoring. First pass analyzes the codebase for improvement opportunities, second pass plans the implementation while preserving existing behavior. Great for cleaning up technical debt with confidence. **/rp-investigate** Systematic bug investigation. Context Builder explores the codebase to gather evidence, traces through code paths, and builds a root cause analysis. The agent keeps investigating until the issue is found. **/rp-oracle-export** Builds optimized codebase context for your task, then exports a prompt file you can paste directly into GPT Pro models on ChatGPT. Useful when you want a second opinion on a complex problem from a capable external model. ### Context Builder Response Types The workflows above use the Context Builder's `context_builder` MCP tool with different response types. You can also invoke these directly for custom workflows: - **clarify** — Build file context only, returns curated selection for manual use (default) - **plan** — Generate an implementation plan grounded in your actual code patterns - **question** — Answer a question about the codebase using deep context - **review** — Generate a code review with git diff context and architectural understanding ### Git Integration The `git` tool provides safe, token-efficient git operations for MCP agents: status, diff, log, show, blame, and snapshot management. Use it to understand repository state and review changes before committing. For deep code reviews with full context mapping, see [Code Reviews & Git](https://repoprompt.com/docs/classic-2.1.0/code-reviews/overview/). ### Custom Skills Beyond the built-in workflow commands, you can create your own skills — markdown prompt templates with YAML frontmatter that agents discover and run as slash commands. Skills let you codify your team's workflows and share them across projects. Learn how to create and install custom skills in [Skills & Slash Commands](https://repoprompt.com/docs/agent-mode/skills/). :::tip **Getting Started:** After setting up the MCP connection, type `/repo` in Claude Code to see all available RepoPrompt commands. For more detail on each workflow and the Context Builder pipeline, see [Agent Mode Workflow Commands](https://repoprompt.com/docs/agent-mode/workflow-templates/). ::: --- ## Keyboard Shortcuts (Reference) Keyboard shortcuts for faster navigation and common actions. ### General | Shortcut or gesture | Action | | --- | --- | | `⌘+,` | Open Settings | | `⌘+O` | Open folder/workspace | | `⌘+W` | Close current tab | | `⌘+Q` | Quit RepoPrompt | ### Compose | Shortcut or gesture | Action | | --- | --- | | `⌘+C` | Copy prompt to clipboard | | `⌘+T` | New compose tab | | `⌘+F` | Search files | | `⌘+Shift+F` | Search file content | ### Chat | Shortcut or gesture | Action | | --- | --- | | `⌘+N` | Start new AI chat | | `⌘+Return` | Send message | | `Escape` | Stop generation | ### Navigation | Shortcut or gesture | Action | | --- | --- | | `⌘+1` | Switch to Compose view | | `⌘+2` | Switch to Chat view | | `⌘+3` | Switch to Apply view | | `⌘+[` | Previous tab | | `⌘+]` | Next tab | ### File Selection | Shortcut or gesture | Action | | --- | --- | | `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. ::: --- ## App Settings from the CLI Flip RepoPrompt preferences from scripts, agents, and Bash without opening the Settings UI. `rp-cli` exposes the same `app_settings` tool the MCP server does, plus a `settings` tool group for schema discovery. :::tip **Full allowlist and safety story:** The list of keys, types, and deliberately excluded categories lives on the MCP page — see [App Settings Tool](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-app-settings/) for the authoritative registry. This page focuses on how to drive the same surface from a shell. ::: ### Quick Reference ```bash # Browse the catalog (each entry includes the current value) rp-cli -e 'app_settings op=list' # Inspect one group rp-cli -e 'app_settings op=list group=ui' # Read a single setting rp-cli -e 'app_settings op=get key=ui.appearance_mode' # Toggle a boolean rp-cli -e 'app_settings op=set key=ui.show_tooltips value=false' # Change an enum rp-cli -e 'app_settings op=set key=ui.appearance_mode value=Dark' # Fractional numbers or null — use JSON via 'call' rp-cli -e 'call app_settings {"op":"set","key":"models.temperature","value":1.25}' rp-cli -e 'call app_settings {"op":"set","key":"models.planning_model","value":null}' # List candidate values for a setting that advertises options_available rp-cli -e 'app_settings op=options key=models.planning_model agent=codexExec' ``` Groups: `ui`, `prompt_packaging`, `editing`, `models`, `context_builder`, `mcp`, `code_maps`. ### When to Use Shorthand vs `call` `rp-cli` parses `key=value` arguments before handing them to the MCP tool, so most everyday writes work with the shorthand form. Reach for `call app_settings {...}` when you need types the shorthand cannot express. | Use shorthand for | Use `call` JSON for | | --- | --- | | - Booleans (`true`/`false`) - Integer values - Enum strings (`Dark`, `Relative`, …) - Enum values with spaces — quote the value (e.g. `value="Parallel split"`) - Single-key reads/writes - Batch `get` with a JSON array (e.g. `keys=["ui.appearance_mode"]`) | - Fractional numbers (e.g. `1.25`) - Explicit `null` values - JSON files piped via `-j @args.json` or `-j @-` - Anything that is easier to express as a literal JSON object | ```bash # Enum value with spaces — quote the value rp-cli -e 'app_settings op=set key=editing.complex_edit_strategy value="Parallel split"' # Batch get via shorthand (generic parser accepts JSON arrays in key=value form) rp-cli -e 'app_settings op=get keys=["ui.appearance_mode","mcp.auto_start"]' # Same batch via explicit JSON rp-cli -c app_settings -j '{"op":"get","keys":["ui.appearance_mode","mcp.auto_start"]}' # Read args from a file (.json is auto-detected, @ is optional) rp-cli -c app_settings -j settings-change.json rp-cli -c app_settings -j @settings-change.json # Read args from stdin cat change.json | rp-cli -c app_settings -j @- ``` ### `settings` Tool Group The CLI groups tools by role. `app_settings` lives in the `settings` group, which is filterable from `tools` and `tools --schema`: ```bash rp-cli -e 'tools --groups' # List available tool groups rp-cli -e 'tools settings' # List tools in the settings group rp-cli -e 'tools settings --schema' # Full JSON schema for app_settings rp-cli -d app_settings # Human-readable help (describe) rp-cli -d app_settings --verbose # Include raw JSON schema ``` Use `tools settings --schema` when you need a machine-readable description — for example, generating agent skill prompts or validating a script's argument shape before sending it. ### Script Patterns #### Read, mutate, write inside a `.rp` script Chain a read to decide the next write. The CLI's `--raw-json` flag emits parsable output that a small helper can inspect. ```bash # toggle-dark-mode.sh current=$(rp-cli -e 'app_settings op=get key=ui.appearance_mode' --raw-json \ | python3 -c 'import json,sys; print(json.load(sys.stdin)["values"]["ui.appearance_mode"])') if [ "$current" = "Dark" ]; then rp-cli -e 'app_settings op=set key=ui.appearance_mode value=Light' else rp-cli -e 'app_settings op=set key=ui.appearance_mode value=Dark' fi ``` #### Flip MCP auto-start in a postinstall step ```bash # postinstall.sh # Ensure the MCP listener launches with RepoPrompt going forward. rp-cli --wait-for-server 5 -e 'app_settings op=set key=mcp.auto_start value=true' ``` #### Set a temperature before a planning session ```bash rp-cli -e ' app_settings op=set key=models.temperature_enabled value=true && call app_settings {"op":"set","key":"models.temperature","value":0.4} && plan "Design the auth migration" ' ``` #### Disable Code Maps globally during a large refactor ```bash rp-cli -e 'app_settings op=set key=code_maps.globally_disabled value=true' # ... do work ... rp-cli -e 'app_settings op=set key=code_maps.globally_disabled value=false' ``` ### Notes & Caveats - **One key per write.** `op=set` accepts exactly one `key`; `keys` and `group` are rejected. - **Always non-destructive.** Validation fails closed — unknown keys, bad types, or out-of-range values are rejected with a clear error and nothing is partially applied. - **Listener state is not force-cycled.** Flipping `mcp.auto_start` affects future launches; it does not stop or start the current MCP listener. - **Allowlist only.** Secrets, tool ACLs, and workspace-scoped settings are intentionally unreachable. See the [MCP page](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-app-settings/) for the full exclusion list. ### See Also - [App Settings Tool (MCP)](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-app-settings/) — full allowlist, parameter schema, and safety details. - [rp-cli Command Line Guide](https://repoprompt.com/docs/classic-2.1.0/rp-cli/cli-guide/) — exec mode, quoting, JSON argument sources, and multi-window rules. - [Settings Reference](https://repoprompt.com/docs/reference/settings/) — in-app Settings UI equivalents. --- ## 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 RepoPrompt 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 RepoPrompt's settings for the CLI to connect. The shorthand verbs below map to the same MCP tools documented in the [MCP Tools Reference](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-tools/); use `rp-cli -d ` or `rp-cli tools --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](https://repoprompt.com/docs/classic-2.1.0/rp-cli/cli-app-settings/) for the shell-focused guide and [App Settings Tool](https://repoprompt.com/docs/classic-2.1.0/mcp-server/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 independent | Persistent - binds once per agent session | | **Window/Tab targeting** | Must pass `-w` and `-t` on every call | Bind once with `select_tab`, persists for session | | **Command chaining** | Yes - use `&&` to chain commands | No - one tool call per request | | **Output redirection** | Yes - pipe to files with `>` | No - results returned in response | | **Token efficiency** | Higher - formatted text output | Lower - structured JSON responses | | **Setup complexity** | None - just call via Bash | Requires 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 RepoPrompt with other shell tools - You don't want MCP tool schemas loaded into every agent session—CLI is on-demand, keeping conversations lighter when RepoPrompt 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 RepoPrompt and benefits from having tool schemas always available ### Getting Started Before using `rp-cli`, you'll need three things: RepoPrompt running on your Mac, the MCP Server enabled in settings, and the CLI installed to your PATH. To install the CLI, open RepoPrompt, go to Settings → 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: ```bash rp-cli --version ``` ### Exec Mode: The Primary Mode for Agents Exec mode is designed for AI agents and scripts. Run commands with `-e` and they execute immediately: ```bash rp-cli -e 'tree' # Show file tree rp-cli -e 'workspace list' # List workspaces rp-cli -e 'select set src/ && context' # Select files, get context rp-cli -e 'search "TODO" --extensions .swift' # Search code rp-cli -e 'chat How does auth work?' # Send to AI chat ``` #### 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. ```bash # Manual workflow rp-cli -e 'manage_selection op=set paths=["src/"]' # Build selection rp-cli -e 'chat_send message="How does this work?"' # Chat sees selection # Auto workflow with context_builder # Builds file selection, optionally generates a response rp-cli -e 'context_builder task="find auth code"' # Build context only rp-cli -e 'context_builder task="explain auth" response_type=question' # Build → answer → chat_id rp-cli -e 'builder "add feature" --type plan' # Build → plan → chat_id # Continue the conversation using the returned chat_id rp-cli -e 'chat_send message="What about edge cases?" chat_id=' ``` #### MCP Tools Reference The CLI provides shorthand commands that map to MCP tools. Use `-d ` to see full parameter documentation including types, required/optional, and valid values: ```bash rp-cli -d file_search # Full parameter docs with types and enums rp-cli -d chat_send # See all options and modes rp-cli -d manage_selection # Selection operations and modes rp-cli -d file_search --verbose # Also show raw JSON schema ``` | 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](https://repoprompt.com/docs/classic-2.1.0/rp-cli/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 RepoPrompt 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](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-tools/) for full documentation. ::: #### Common Examples by Tool ```bash # 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 {"op":"set","key":"models.temperature","value":1.25}' rp-cli -e 'call app_settings {"op":"set","key":"models.planning_model","value":null}' 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 {"path":"src/f.ts","search":"old","replace":"new"}' rp-cli -e 'call apply_edits {"path":"src/f.ts","search":"old","replace":"new","all":true}' rp-cli -e 'call apply_edits {"path":"src/f.ts","search":"a\nb","replace":"c\nd"}' # Multiline rp-cli -e 'call file_actions {"action":"create","path":"src/new.ts"}' # Create file rp-cli -e 'call file_actions {"action":"create","path":"f.ts","content":"hello"}' # Create with content rp-cli -e 'call file_actions {"action":"move","path":"old.ts","new_path":"new.ts"}' # 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: ```bash # 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={"extensions":[".swift",".ts"]}' # 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":{"paths":["src/"]}}' ``` #### 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 {json}`) 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: ```bash # Continue current chat (new_chat=false, default for 'chat') rp-cli -e 'chat_send message="Follow-up question"' rp-cli -e 'chat "Follow-up question"' # Start new chat (new_chat=true) rp-cli -e 'chat_send message="New topic" new_chat=true' rp-cli -e 'chat "New topic" --new' # plan and review shorthands START NEW CHATS by default (new_chat=true) rp-cli -e 'plan "Design the auth system"' # Starts NEW chat in plan mode rp-cli -e 'review "Check this code"' # Starts NEW chat in review mode rp-cli -e 'plan "Continue planning" --continue' # Continue existing chat rp-cli -e 'review --continue' # Continue in review mode ``` #### Chaining Commands Commands can be chained with `&&` within a single `-e` flag. State like workspace selection carries through the chain: ```bash rp-cli -e 'workspace MyProject && select set src/ && context --all' rp-cli -e 'workspace create MyProject --new-window && tree' rp-cli -e 'workspace create MyProject --switch && context --all' rp-cli -e 'workspace switch MyProject --new-window && tree' ``` #### Output Redirection Commands support output redirection with `>` to write results directly to a file: ```bash rp-cli -e 'tree > /tmp/structure.txt' rp-cli -e 'workspace MyProject && context > ~/Desktop/context.md' ``` #### Prompt Export and Presets Export full LLM-ready context (files, tree, codemaps) to a file, or manage copy presets: ```bash rp-cli -e 'prompt export ~/context.md' # Export full context to file rp-cli -e 'prompt presets' # List available copy presets rp-cli -e 'prompt preset "My Preset"' # Select a copy preset by name ``` 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 ```text -e, --exec Execute command(s) -w, --window Target window ID -t, --tab Target tab (name or UUID) -c, --call Call tool directly -j, --json JSON for --call (see below) --tools-schema Dump all tools as MCP tools/list JSON -q, --quiet Suppress non-essential output --raw-json Raw JSON output (for scripting) --verbose Show debug/timing info --fail-fast Stop on first error in chain ``` #### JSON Argument Sources (-j / --json) The `-j` flag accepts JSON arguments in multiple formats: ```bash # Inline JSON rp-cli -c tool -j '{"key":"value"}' # 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 '{"key":"value"}' | 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. ```bash rp-cli -i # Start interactive REPL rp-cli -i -w 1 # Start with window pre-selected ``` 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: ```bash rp-cli -l # List all available MCP tools rp-cli -l explore # List tools in the 'explore' group rp-cli -l settings # List tools in the 'settings' group (app_settings) rp-cli --tools-schema # Dump all tools as MCP tools/list JSON (machine-readable) rp-cli -d search # Describe a specific command rp-cli -c read_file -j '{"path":"/tmp/test.txt"}' # 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 RepoPrompt 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. ```bash rp-cli -e 'windows' # Discover available windows rp-cli -w 1 -e 'workspace tabs' # List tabs in window 1 rp-cli -w 1 -t MyTab -e 'context' # Target window + tab ``` :::warning **Important for AI Agents** When multiple windows are detected, AI agents **must**: 1. Run `windows` to discover available windows 2. Pass `-w ` on every CLI invocation 3. Pass `-t ` 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: ```bash rp-cli -w 1 -e 'tabs' # List available tabs (shorthand) rp-cli -w 1 -e 'workspace tabs' # Same as above rp-cli -w 1 -t "Feature Work" -e 'context' # Target by name rp-cli -w 1 -t "UUID-HERE" -e 'chat Hello' # Target by 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: ```bash # daily-export.rp # Export context from multiple projects workspace switch Frontend select set src/components/ context --all > ~/exports/frontend.md workspace switch Backend select set src/api/ context --all > ~/exports/backend.md ``` Run with: ```bash rp-cli --exec-file ~/scripts/daily-export.rp ``` #### Workflow Shorthand Flags Common workflows have shorthand flags that compile to exec commands: ```text -w, --window Target window (required with multiple windows) -t, --tab Target tab (name or UUID) --workspace Switch to workspace --select-add Add files to selection --select-set Replace selection --export-context Export context to file (JSON snapshot) --export-prompt Export full LLM-ready context to file --chat Send chat message --builder Build context (add --type plan to generate plan) ``` Example: ```bash rp-cli -w 1 -t MyTab --workspace MyProject --select-set src/ --export-prompt ~/out.md ``` ### Getting Help The CLI has tiered help for different needs: ```bash rp-cli --help # Exec mode quick reference rp-cli --help-interactive # REPL mode details rp-cli --help-scripting # Script files and workflow flags rp-cli --help-advanced # Tab targeting, routing parameters rp-cli -d # Detailed help for a specific command rp-cli --tools-schema # All tool schemas as JSON (for MCP clients/docs) ``` ### Complete Tool Schema Reference Below is the complete schema documentation for all MCP tools. Use `rp-cli -d --verbose` to also see the raw JSON schema. #### manage\_selection Manage the current file selection (context for chat). Shorthand: `select` ```text 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): [{start_line, end_line, description}] - 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` ```text Parameters: instructions (string) Your request. Use XML tags: for goal, for background, for agent hints. response_type (string): plan | question | review | clarify 'clarify' (default): Returns context only 'question': Answers using built context 'plan': Generates implementation plan 'review': Generates code review with git diffs ``` #### chat\_send Send message to AI chat. Shorthands: `chat`, `plan`, `review` ```text Parameters: new_chat (boolean, required) Start a new chat session message (string) Your message to send mode (string): chat | plan | edit | review [default: chat] Operation mode chat_id (string) Chat ID to continue a specific chat chat_name (string) Set or update the chat session name model (string) Model preset ID or name (call list_models first) selected_paths (array) File paths for context (overrides current selection) include_diffs (boolean) Include edit diffs in reply (default: true) use_tab_prompt (boolean) Use compose tab's prompt instead of message ``` #### read\_file Read file contents. Shorthands: `read`, `cat` ```text Parameters: path (string, required) File path start_line (integer) Line to start from (1-based). Negative for tail behavior (-N reads last N lines) limit (integer) Number of lines to read ``` #### file\_search Search by file path and/or content. Shorthands: `search`, `grep` ```text Parameters: pattern (string, required) Search pattern (regex by default) mode (string): auto | path | content | both [default: auto] Search scope regex (boolean) [default: true] Use regex matching filter (object) File filtering: - extensions (array): e.g., [".swift", ".ts"] - paths (array): Limit to specific paths - exclude (array): Skip matching patterns context_lines (integer) Lines of context before/after matches max_results (integer) [default: 50] Maximum results to return whole_word (boolean) Match whole words only count_only (boolean) Return only match count ``` #### get\_file\_tree ASCII directory tree. Shorthand: `tree` ```text Parameters: type (string): files | roots [default: files] Tree type to generate mode (string): auto | full | folders | selected [default: auto] Filter mode (for 'files' type only) max_depth (integer) Maximum depth (root = 0) path (string) Starting folder for subtree ``` #### get\_code\_structure Get codemaps (function/type signatures). Shorthand: `structure` ```text Parameters: scope (string): paths | selected [default: paths] Scope of operation paths (array) File or directory paths (when scope='paths') max_results (integer) [default: 25] Maximum codemaps to return ``` #### workspace\_context Snapshot of workspace state. Shorthand: `context` ```text 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: {id?, kind?, name?} ``` #### prompt Get or modify shared prompt/instructions. ```text 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: {id?, kind?, name?} copy_preset (string | object) Override for export. String: UUID, kind, or name. Object: {id?, kind?, name?} ``` #### apply\_edits Apply file edits. **JSON format required** - use `call apply_edits {...}` :::tip **Usage:** No shorthand available. Use JSON format for reliable escape handling: ```bash # Inline JSON rp-cli -e 'call apply_edits {"path":"file.ts","search":"old","replace":"new"}' rp-cli -e 'call apply_edits {"path":"file.ts","search":"line1\nline2","replace":"new"}' # 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:** ```bash 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 {search, replace, all} 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: ```bash # Inline JSON rp-cli -e 'call file_actions {"action":"create","path":"src/new.ts"}' rp-cli -e 'call file_actions {"action":"create","path":"f.ts","content":"line1\nline2"}' rp-cli -e 'call file_actions {"action":"move","path":"old.ts","new_path":"new.ts"}' # 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. ::: ```text Parameters: action (string, required): create | delete | move Operation to perform path (string, required) File path (absolute required for delete) content (string) File content (for create) new_path (string) Destination path (for move) if_exists (string): error | overwrite [default: error] Behavior if file exists (for create) ``` #### chats List chats or view history. ```text Parameters: action (string): list | log [default: list] Action to perform scope (string): workspace | tab [default: workspace] Scope for list/log operations tab_id (string) Optional compose tab UUID filter. With scope=tab and no tab_id, RepoPrompt uses the current bound tab when available, otherwise the active UI tab. chat_id (string) Chat ID for log action include_diffs (boolean) Include diff summaries in log limit (integer) Max items (list: default 10, log: default 3) ``` #### list\_models List available AI model presets. Shorthand: `models` ```text (no parameters) ``` #### 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. ::: ```text Parameters: action (string, required): list | switch | create | delete | add_folder | remove_folder | list_tabs | select_tab | create_tab | close_tab Action to perform workspace (string) Workspace UUID or name (for switch, delete, add_folder, remove_folder) name (string) New workspace name (for create) or optional tab name (for create_tab) folder_path (string) Absolute folder path (for add_folder, remove_folder) tab (string) Tab UUID or name (for select_tab, close_tab) mode (string): blank | fork [default: blank] For create_tab: create an empty tab or fork an existing one source_tab (string) For create_tab with mode=fork: source compose tab UUID or name bind (boolean) [default: true] For create_tab: bind this connection to the new tab window_id (integer) Target window ID focus (boolean) [default: false] For select_tab or create_tab: switch UI to show selected tab allow_active (boolean) [default: false] For close_tab: allow closing the currently visible tab open_in_new_window (boolean) For create/switch: open workspace in a new window and bind the connection switch_to_created (boolean) [default: true] For create: switch to the newly created workspace Safety: close_tab refuses to close the last remaining tab, the visible active tab unless allow_active=true, or any tab with live bound runs. ``` #### list\_windows List open RepoPrompt windows. Shorthand: `windows` ```text (no parameters) ``` #### app\_settings Read/update allowlisted RepoPrompt app-wide preferences. Part of the `settings` tool group. See [App Settings Tool](https://repoprompt.com/docs/classic-2.1.0/mcp-server/mcp-app-settings/) (MCP) for the full registry, and [App Settings from the CLI](https://repoprompt.com/docs/classic-2.1.0/rp-cli/cli-app-settings/) for shell-focused examples. ```bash 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 {"op":"set","key":"models.temperature","value":1.25}' rp-cli -e 'call app_settings {"op":"set","key":"models.planning_model","value":null}' 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.** ```text Parameters: op (string, required): start | poll | wait | cancel | steer | respond Operation to perform message (string) Instruction text (required for start, steer) session_id (string) Session UUID for poll, wait, cancel, steer, and respond. Do not pass for start — use steer to continue an existing session. timeout (number) Maximum seconds to wait (optional for start/wait, defaults to 300). Fractional values allowed. Use 0 for immediate non-blocking check. wait (boolean) [steer] Wait for an interesting/terminal state after steering. Implied when timeout_seconds is provided. timeout_seconds (number) [steer] Max wait seconds when wait=true. Default 300. session_name (string) Name for a new session (optional for start) model_id (string) Role label (explore, engineer, pair, design) or specific model_id from agent_manage.list_agents (optional for start) workflow_id, workflow_name (string) Start a workflow-backed run (optional for start, steer, respond) detach (boolean) Return immediately instead of waiting (optional for start, default false) interaction_id (string) Pending interaction UUID (required for respond) response (string), answers (object), amendment (string) Response fields for respond Responses include failure_reason on failed/cancelled runs: process_crash, timeout, agent_error, cancelled Use rp-cli -d agent_run for the full schema with types and enums. See the MCP Tools Reference for detailed operation documentation. ``` #### agent\_manage Session and workflow management. **Advanced, policy-gated.** ```text Parameters: op (string, required): list_agents | list_sessions | get_log | create_session | resume_session | stop_session | cleanup_sessions | list_workflows Operation to perform session_id (string) Session UUID (for get_log, resume_session, stop_session) session_ids (array of strings) Session UUIDs to delete (required for cleanup_sessions). Only MCP-originated sessions are eligible. session_name (string) Name for new session (for create_session) model_id (string) Role label or specific model_id (for create_session, resume_session) limit (integer), offset (integer) Pagination (for list_sessions, get_log) state (string) Filter by state (for list_sessions, e.g. failed, completed, running) Use rp-cli -d agent_manage for the full schema with types and enums. See the MCP Tools Reference for detailed operation documentation. ``` ### Troubleshooting #### "command not found: rp-cli" The CLI isn't installed or isn't on your PATH. Install from RepoPrompt's settings, then open a new terminal. #### Connection Failures Make sure RepoPrompt 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 RepoPrompt UI. If a command hangs, check the app for a dialog. :::warning **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 RepoPrompt 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. ::: --- ## 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 RepoPrompt into Agent Workflows](https://img.youtube.com/vi/060MqOx-Ex0/maxresdefault.jpg) Fitting RepoPrompt 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 1. **Run Context Builder** with your task description 2. **Review the selection:** Ensure all relevant files are included 3. **Switch to Plan preset:** Select the "Plan" copy preset 4. **Copy and paste to GPT-5.5 Pro:** Use ChatGPT's Pro plan for best results 5. **Get your architectural plan:** GPT-5.5 Pro excels at breaking down architectures 6. **Refine if needed:** Ask follow-up questions in the same chat 7. **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 - **RepoPrompt 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. ::: --- ## 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 RepoPrompt workflow. [![Context Builder 2.0 — Discovery (Context Builder) documentation illustration](https://img.youtube.com/vi/qHl116OG2DM/maxresdefault.jpg) Context Builder 2.0 AI-powered context selection with CLI Providers](https://youtu.be/qHl116OG2DM) ### How Context Builder Works 1. **Task analysis:** You describe what you're trying to accomplish 2. **Codebase exploration:** The agent uses MCP tools to search and read your code 3. **File selection:** Relevant files and codemaps are identified 4. **Token optimization:** Selection is refined to fit your token budget 5. **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 1. Open your workspace in RepoPrompt 2. Click **Context Builder** in the toolbar 3. Describe your task clearly and specifically 4. Wait for the agent to explore and select files 5. Review the selection and handoff prompt 6. 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) --- ## MCP Builder Workflow `/rp-build` is a structured Agent Mode workflow that automates the discovery→plan→implement pipeline. It uses [Context Builder](https://repoprompt.com/docs/classic-2.1.0/workflows/discovery/) to gather deep context, generates an architectural plan, then implements directly — all in a single agent session. ### How It Works The workflow runs through four phases, each with a clear purpose: #### Phase 1: Quick Scan The agent makes 2–3 tool calls max — typically `get_file_tree` and a few targeted searches — just enough to get oriented in the codebase. It reformulates your prompt with codebase-specific references (file paths, module names, API surfaces) so the next phase has grounded input to work with. This phase is intentionally brief. The heavy lifting happens in Context Builder. #### Phase 2: Context Builder The agent calls `context_builder` with `response_type: "plan"`. This is the core of the workflow — a sub-agent autonomously explores the codebase, selects the most relevant files, and generates an architectural plan grounded in actual code. The plan includes which files to modify, what changes to make, and how they connect. The agent trusts this plan by default — it's produced by a model that has read the selected files in full, not just signatures. #### Phase 3: Oracle Clarification (Optional) If navigating the selected code is difficult or the plan leaves a concrete gap, the agent can follow up with an oracle call to deep-reason over the selected files. This is *not* a default step — it only fires when there's an actual ambiguity to resolve. Important: the oracle only sees files in the current selection. If coverage is wrong, the right move is to rerun Context Builder with refined instructions, not to manually curate the selection. #### Phase 4: Direct Implementation The agent implements the plan using `apply_edits` and `file_actions` — creating, modifying, and moving files as needed. It works directly from the builder's plan without routing through an oracle edit mode. ### When to Use /rp-build vs /rp-orchestrate | Workflow | How It Works | Best For | | --- | --- | --- | | `/rp-build` | Single-session pipeline: scan → plan → implement | Tasks that fit in one agent's scope — a feature, a refactor, a bug fix | | `/rp-orchestrate` | Plans (or accepts a plan), decomposes into sub-tasks, delegates to multiple agents | Complex multi-part work that benefits from parallel execution across providers | ### Triggering #### 1. Slash Command (Primary) Run `/rp-build ` in any Agent Mode session. The agent runs the full pipeline from scratch — quick scan, context building, planning, and implementation. See [Workflow Commands](https://repoprompt.com/docs/classic-2.1.0/mcp-server/workflow-commands/) for more on slash commands. #### 2. Copy Preset (Secondary) For Classic Edition IDE Mode users, the **MCP Builder** copy preset gives the agent a head start with pre-selected codemaps. This provides: - **Project structure** — the file tree so the agent understands your codebase layout - **Preselected files as codemaps** — token-efficient function signatures for files you've already identified - **Task description** — your instructions from the compose area MCP Builder copy preset in RepoPrompt — MCP Builder Workflow documentation illustration Copy the preset and paste it into Claude Code or another MCP-connected agent. The agent uses your provided context to skip part of the quick scan, then proceeds through Context Builder and implementation as usual. :::tip **Key principle:** Don't skip Context Builder. Even when using the copy preset with pre-selected files, the builder does the heavy lifting — it reads the actual code, discovers dependencies you may have missed, and produces a plan grounded in what it found. The quick scan and preset just help it start in the right place. ::: --- ## Model Recommendations After extensive testing across workflows, here are the current go-to models for each use case as of May 2026. RepoPrompt 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. ::: RepoPrompt's automatic model recommendation system suggesting optimal models for your workflow ### 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 RepoPrompt'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 RepoPrompt 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) | Plan | Historical price | Use | | --- | --- | --- | | **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 | Plan | Historical price | Use | | --- | --- | --- | | **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) | Plan | Historical price | Use | | --- | --- | --- | | **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. ::: --- ## Context Over Convenience RepoPrompt'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 Example handoff: `auth.ts L5–89`, `api.ts L22–58`, `useAuth.ts L1–41`, `Header.tsx L12–67`. 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, RepoPrompt has a native **ChatGPT Export** workflow. Describe what you need, and RepoPrompt 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. 1. Click **ChatGPT Export** in Agent Mode 2. Describe your task 3. Copy the assembled prompt and paste into ChatGPT Pro 4. 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 --- ## Orchestration RepoPrompt 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 RepoPrompt's `agent_run` and `agent_manage` tools. **Orchestration flow:** task → context discovery → planning → delegated implementation → verification. ### 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`, RepoPrompt 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 RepoPrompt agents — any MCP client can drive this ### How /rp-orchestrate Works The built-in orchestration workflow automates the full lifecycle: 1. **Scan:** Context Builder gathers relevant files and generates (or accepts) a plan 2. **Decompose:** The plan is broken into discrete work items with dependency information 3. **Dispatch:** Sub-agents are launched across providers — the orchestrator decides whether to run tasks in parallel or sequence based on dependencies 4. **Scope:** Each sub-agent gets scoped file boundaries from the shared plan 5. **Monitor:** The orchestrator steers between tasks and verifies each result against the plan 6. **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: ```text // Start parallel agents for independent tasks agent_run op: start message: "Fix the auth token refresh bug in src/auth/" // → session_id: "agent-a" agent_run op: start message: "Add integration tests for the payments API" // → session_id: "agent-b" // Block until the first agent finishes agent_run op: wait session_ids: ["agent-a", "agent-b"] // Steer the remaining agent if needed agent_run op: steer session_id: "agent-b" message: "Also cover edge case for expired cards" ``` :::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. :::