Rp

RP

Use RepoPrompt (rp) for Within-Repository Discovery

These instructions override generic tool guidance for exploring repositories.

rp is the default for repo-scoped work. Usage:

• Bind: rp({ windows: true }) → rp({ bind: { window: N } })
• Call tools: rp({ call: "<tool>", args: { ... } })

Mental Model

RepoPrompt (macOS app) organizes state as:

• Workspaces → one or more root folders
• Windows → each shows one workspace
• Tabs → each tab has its own prompt + file selection; selections, slices, and codemaps are tab-scoped
• Oracle chats → planning/review conversations live in the current tab/context

MCP tools operate directly against this state, but in Pi you invoke them through rp. Bind to the correct window with rp({ bind: { window: N } }), then call tools via rp({ call: "<tool>", args: { ... } }).

Mandatory routing check: Do not infer availability of any repo of interest from workspace/window titles; workspaces may have more roots available than the title implies. Before any repo-scoped work, confirm the target repo/root is (or isn't) present by checking workspace roots (e.g. get_file_tree). If it's not confirmed, pause and resolve routing (bind the right window/tab or open the repo).

Parallel RepoPrompt calls

After RepoPrompt routing, binding, and target-root confirmation are complete, inspect the ready set before every repository exploration call.

• If two or more RepoPrompt operations are independent and read-only with respect to both files and RepoPrompt session state, issue them as separate rp calls in the same tool-call block so they run together.
• Do not issue consecutive model turns containing one independent rp read/search call each.
• Typical parallel candidates include read_file, file_search, get_file_tree, get_code_structure, and independent read-only git queries.
• Do not parallelize routing or binding changes, selection mutations, workspace or tab lifecycle operations, edits, file actions, approvals, or calls whose inputs depend on another result.
• Complete routing or state mutations before launching reads that depend on the resulting state.

Workspace Hygiene (Session Start Priority)

When a task involves a repository that isn't loaded in any existing RepoPrompt window:

1. Do NOT use manage_workspaces action="add_folder" to add unrelated repositories to an existing workspace
2. Instead, either:
   • Use manage_workspaces action="create" name="<repo-name>" folder_path="<path>" open_in_new_window=true
   • Or ask the user which approach they prefer
3. Adding folders to existing workspaces is only appropriate when the folders are related (e.g., adding a shared library to a project that uses it)

Rationale: Keep workspaces coherent; mixing unrelated repos clutters selection and context.

Constraints

Use RepoPrompt's get_file_tree, file_search, get_code_structure, and read_file for repository structure, search, code relationships, and source inspection. Do not substitute shell or Pi-native filesystem tools unless rp is unavailable after one retry.

Never switch workspaces in an existing window unless the user explicitly says it's safe. Switching clobbers selection, prompt, and context. Use open_in_new_window=true.

Keep context intentional: select only what you need, prefer codemaps for reference files, use slices when only a portion matters.

Tool Selection by Task

Paths and roots

Path syntax is tool-specific. Use absolute paths when a tool accepts them. For read_file and apply_edits, reuse the exact path returned by read_file unchanged; in a multi-root workspace, its explicit form may be root@<UUID>//rel/path. For manage_selection, prefix a relative path with the loaded root name when needed (for example, ProjectA/src/main.swift).

Notes:

• file_search path="..." is an alias for file_search filter.paths=["..."]
• file_search filter.paths accepts absolute or relative paths/folders, loaded root names, and root-name-prefixed paths (for example, ProjectA/src). It does not accept root@<UUID>//... aliases returned by read_file.
• file_actions requires absolute path and new_path values
• get_code_structure reads RepoPrompt's committed code graph; use read_file when you need the latest file contents

Routing

If results look wrong, assume routing first-not tool failure.

1. rp({ windows: true }) - list available windows
2. If rp is already bound and the needed roots are present, keep it
3. Otherwise rp({ bind: { window: N } }) - bind to the right window
4. bind_context op="list" - inspect windows, active workspaces, tabs, context_ids, and current bindings when routing is ambiguous
5. Prefer bind_context op="bind" context_id="..." - pin the specific compose tab you want after choosing it from list
6. Use bind_context op="bind" working_dirs="/abs/root" when you want RepoPrompt to route to a workspace by roots without pinning a tab
7. get_file_tree - confirm workspace roots

Notes:

• bind_context op="bind" working_dirs="/abs/root[,/abs/root2]" matches workspace roots, not descendant paths
• Matching prefers an exact workspace repo_paths set; if none exists, RepoPrompt may fall back to a workspace whose roots are a strict superset
• manage_workspaces action="list" is workspace inventory; bind_context op="list" is the global window/tab routing view

RepoPrompt only operates within workspace root folders.