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.

Agent Mode

agent_run + agent_manage are RepoPrompt's external control plane for Agent Mode: use them when you need to drive a long-running per-tab subagent session, not just make one-off MCP file/chat calls.

• Use agent_run for run lifecycle: start, wait/poll, respond, steer, cancel
• Use agent_manage for durable metadata: discover agents/workflows, list sessions, and export handoff transcript
• Use agent_manage op="extract_handoff" to pull into your context a handoff transcript of the subagent's context. It exports a <forked_session ...> payload; set output_path to write a file, or omit it for inline XML.
• Session state uses MCP-facing values such as running, waiting_for_input, completed, and failed; waiting_for_input means reply with agent_run op="respond"
• agent_manage op="list_workflows" includes orchestrate for planning, decomposition, and sub-agent dispatch
• agent_run op="wait" / op="poll" accept either session_id or session_ids; multi-wait wakes on the first interesting session
• If you start sub-agents, do not end your turn while any started session is still unattended; always wait/poll and handle pending input first
• MCP-started orchestrate runs may spawn sub-agents, but nested sub-agents cannot recursively start more agent runs

Asynchronous Context Builder and Oracle

Through rp, context_builder and generic oracle_send are asynchronous: the start call returns a job_id; call the matching context_builder_wait or oracle_send_wait, and if it returns running, repeat that same wait as the next action. Waits observe the original request and never resubmit it; /rp oracle remains synchronous.

context_builder instructions="..." [response_type="clarify|question|plan|review"]

Context Builder explores the codebase and curates file selection automatically.

• response_type="clarify" (default): Returns context for handoff or manual refinement
• response_type="question": Answers using built context
• response_type="plan": Generates an implementation plan
• response_type="review": Generates a code review with git diff context

For question, plan, and review responses, use the chat_id from the terminal wait result with oracle_send new_chat=false chat_id="..." for follow-up.

For a shareable handoff artifact, set export_response=true; the terminal wait result includes oracle_export_path.

These operations are token-costly; invoke them explicitly when the user requests them or during planning phases, not automatically.

Edit Discipline

• Re-read the target region of a file before editing if: (a) the last read was >2 turns ago, (b) you edited the same file since last reading it, or (c) you switched RP windows since last reading it
• After an apply_edits failure, always re-read before retrying - never guess at what changed
• When making multiple edits to the same file, apply them one at a time (each edit shifts content for subsequent ones)
• Confirm you are bound to the correct RP window before any apply_edits - relative paths resolve against the bound workspace

Start Here

When the task involves a repository, use rp as your toolkit for exploration, reading, editing, and file operations.

1. rp({ windows: true })
2. If already bound and roots are correct, keep it; otherwise rp({ bind: { window: N } })
3. When routing matters across repeated tool calls, use rp({ call: "bind_context", args: { op: "list" } }), then rp({ call: "bind_context", args: { op: "bind", context_id: "..." } })
4. Then use get_file_tree, file_search, read_file, etc.

Use Pi-native ls/find/grep/read/edit/write only when rp is unavailable after one retry.

Unexpected output is usually a routing issue-wrong workspace, wrong window, wrong tab-not a tool failure. Check routing before falling back.

Repository startup contract

• For repo-scoped work, default to RepoPrompt via rp, not native repo-file tools or bash
• If the user refers to the current cwd/project, verify it first with pwd
• If the user names a repo path, treat that path as the repo of interest and resolve RepoPrompt routing before using native tools
• Before repo-scoped work, inspect windows and roots, then bind the correct window/tab, then confirm the target root
• Do not bind a random window just because it is available
• Do not guess RepoPrompt tool interfaces; use rp({ describe: "tool_name" }) when exact parameters matter

Text-file changes

Never use the terminal to modify text files. Always use rp's apply_edits (or Pi's edit if rp unavailable). Modifying files via terminal is only acceptable if rp is not available and you need to do large-scale find/replace operations or similar on files. In such cases, explicitly get the user's permission before using it.