{"id":48419410,"url":"https://github.com/tmdgusya/roach-pi","last_synced_at":"2026-05-11T15:20:50.314Z","repository":{"id":349312204,"uuid":"1201853927","full_name":"tmdgusya/roach-pi","owner":"tmdgusya","description":"Strict engineering discipline and multi-agent orchestration for the pi coding agent","archived":false,"fork":false,"pushed_at":"2026-04-28T09:11:35.000Z","size":1710,"stargazers_count":107,"open_issues_count":8,"forks_count":12,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T09:32:29.206Z","etag":null,"topics":["extensions","pi","pi-coding-agent"],"latest_commit_sha":null,"homepage":"https://tmdgusya.github.io/roach-pi/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmdgusya.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-05T08:56:40.000Z","updated_at":"2026-04-28T09:11:39.000Z","dependencies_parsed_at":"2026-04-10T12:02:16.363Z","dependency_job_id":null,"html_url":"https://github.com/tmdgusya/roach-pi","commit_stats":null,"previous_names":["tmdgusya/pi-engineering-discipline-extension","tmdgusya/roach-pi"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/tmdgusya/roach-pi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmdgusya%2Froach-pi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmdgusya%2Froach-pi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmdgusya%2Froach-pi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmdgusya%2Froach-pi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmdgusya","download_url":"https://codeload.github.com/tmdgusya/roach-pi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmdgusya%2Froach-pi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32486223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["extensions","pi","pi-coding-agent"],"created_at":"2026-04-06T08:02:25.508Z","updated_at":"2026-05-11T15:20:50.298Z","avatar_url":"https://github.com/tmdgusya.png","language":"TypeScript","funding_links":[],"categories":["Extensions"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/hero.svg\" alt=\"ROACH PI — engineering discipline for pi\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eEngineering discipline, agentic orchestration, and power-user tools for the pi coding agent.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"CHANGELOG.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/changelog-keep-22C55E?style=flat\u0026colorA=111827\" alt=\"Changelog\"\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-58A6FF?style=flat\u0026colorA=111827\" alt=\"MIT license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/badlogic/pi-mono\"\u003e\u003cimg src=\"https://img.shields.io/badge/pi-0.72.x-A78BFA?style=flat\u0026colorA=111827\" alt=\"pi 0.72.x\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-3178C6?style=flat\u0026colorA=111827\u0026logo=typescript\u0026logoColor=white\" alt=\"TypeScript\"\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg src=\"https://img.shields.io/badge/search-FFF-F97316?style=flat\u0026colorA=111827\" alt=\"FFF search\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Built on \u003ca href=\"https://github.com/badlogic/pi-mono\"\u003epi\u003c/a\u003e. Focused on transparent prompts, verifiable execution, subagents, code review, memory, LSP, and fast search.\n\u003c/p\u003e\n\n---\n\n## Table of Contents\n\n- [What is ROACH PI?](#what-is-roach-pi)\n- [Architecture](#architecture)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Clarify and Plan](#clarify-and-plan)\n- [Subagent Orchestration](#subagent-orchestration)\n- [Review Pipelines](#review-pipelines)\n- [FFF Search](#fff-search)\n- [LSP Code Intelligence](#lsp-code-intelligence)\n- [Workspace Memory](#workspace-memory)\n- [Session Loop](#session-loop)\n- [Autonomous Dev](#autonomous-dev-experimental)\n- [Nested AGENTS.md](#nested-agentsmd)\n- [Commands Reference](#commands-reference)\n- [Tools Reference](#tools-reference)\n- [Configuration](#configuration)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## What is ROACH PI?\n\nROACH PI is an extension suite for the pi coding agent. It turns a normal coding session into a disciplined engineering loop:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/workflow-preview.svg\" alt=\"ROACH PI workflow: clarify → plan → worker → validator\" width=\"88%\"\u003e\n\u003c/p\u003e\n\nIt is intentionally inspectable: commands, tools, hooks, agents, and skills are plain TypeScript and Markdown in this repository.\n\n---\n\n## Architecture\n\nSeven bundled extensions, one disciplined engineering loop:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/architecture-overview.svg\" alt=\"ROACH PI extension architecture showing all seven modules\" width=\"88%\"\u003e\n\u003c/p\u003e\n\n---\n\n## Installation\n\n```bash\npi install git:github.com/tmdgusya/roach-pi\n```\n\nRestart `pi`, then run setup once:\n\n```bash\n/setup\n```\n\n`/setup` writes `quietStartup: true` to `~/.pi/agent/settings.json` so ROACH PI can own the startup banner instead of duplicating pi's default extension listing.\n\n\u003e [!WARNING]\n\u003e If you have the `superpowers` skill installed, remove it before using ROACH PI. It can define skill names that collide with this extension's bundled skills, and pi does not guarantee extension override order for duplicate skills.\n\n---\n\n## Quick Start\n\nTry the disciplined path on a real task — from fuzzy idea to verified implementation in minutes:\n\n```text\n/clarify Add a feature that exports review results as Markdown\n```\n\nAfter the context brief is clear:\n\n```text\n/plan\n```\n\nThen ask the agent to run the plan through the execution loop:\n\n```text\nplan-compliance → plan-worker → plan-validator\n```\n\nBefore merging non-trivial changes, run a review:\n\n```text\n/ultrareview\n```\n\nQuick system checks for visibility:\n\n```text\n/fff-health\n/lsp status\n/memory stats\n```\n\n---\n\n## Clarify and Plan\n\nVague requests should not become vague code.\n\n**`/clarify`** forces ambiguity into the open before implementation starts. It asks one focused question, offers concrete choices when useful, and explores relevant files with an `explorer` subagent in parallel.\n\nThe output is a **Context Brief** — a structured summary of the clarified scope, constraints, and affected files.\n\n**`/plan`** then converts that brief into a task-by-task implementation plan with:\n- explicit files to modify\n- step-by-step instructions\n- verification commands\n- success criteria\n\nPlan execution uses a **compliance → worker → validator** loop, so implementation and verification stay separated. Structured progress tracking records milestones, plan tasks, and todos as durable state — the footer reflects live `running` → `completed`/`failed` transitions and can restore progress from session replay.\n\n| Command | Purpose |\n|---|---|\n| `/clarify [topic]` | Resolve ambiguity with dynamic questions and parallel exploration |\n| `/plan [topic]` | Create an executable implementation plan |\n| `/ultraplan [topic]` | Break complex work into milestones using five planning reviewers |\n| `/reset-phase` | Clear active clarify/plan/ultraplan state |\n\n---\n\n## Subagent Orchestration\n\nThe `subagent` tool delegates work to specialized agents running as separate `pi` processes.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/subagent-modes.svg\" alt=\"ROACH PI subagent modes: single, parallel, chain, async\" width=\"88%\"\u003e\n\u003c/p\u003e\n\nSupported modes:\n\n| Mode | Use it for |\n|---|---|\n| **Single** | One focused investigation or execution task |\n| **Parallel** | Independent reviewers, explorers, or workers |\n| **Chain** | Sequential pipelines where each step consumes the previous output |\n| **Async** | Background tasks that can be waited on, checked, or interrupted by run id |\n\nAsync subagents support `asyncDependency: \"needed-before-final\"` when the lead agent must join results before finalizing its response.\n\n---\n\n## Review Pipelines\n\nTwo levels of review, one unified goal: catch problems before they ship.\n\n**`/review`** — quick integrated review of a PR, branch, or local diff.\n\n**`/ultrareview`** — the deep pass:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/review-search-preview.svg\" alt=\"ROACH PI ultrareview pipeline: 10 reviewers → verifier → synthesis\" width=\"88%\"\u003e\n\u003c/p\u003e\n\n1. resolve the diff once\n2. dispatch 10 reviewers in parallel\n3. run `reviewer-verifier` to dedupe and filter false positives\n4. run `review-synthesis`\n5. save the final report under `docs/engineering-discipline/reviews/`\n\n| Command | Description |\n|---|---|\n| `/review [target]` | Quick single-pass review. Target can be omitted, PR number, PR URL, or branch |\n| `/ultrareview [target]` | Deep 10-reviewer pipeline with verifier and synthesis report |\n\n---\n\n## FFF Search\n\nThe bundled FFF extension upgrades pi's file and content search with git-aware ranking and frecency.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/fff-search-preview.svg\" alt=\"ROACH PI FFF search: find, grep, multi_grep, @ autocomplete\" width=\"88%\"\u003e\n\u003c/p\u003e\n\n- **`find`** — fuzzy file name search with frecency and git-aware ranking\n- **`grep`** — content search with pagination and smart-case behavior\n- **`multi_grep`** — multi-pattern OR search in one pass\n- **`@` autocomplete** — replace pi's default file picker with FFF suggestions (toggle with `/fff-mode both`)\n\nFFF is fallback-safe: if the native engine is unavailable, tools gracefully degrade to pi's default search.\n\n---\n\n## LSP Code Intelligence\n\nThe bundled `pi-lsp-client` extension adds IDE-like operations directly inside pi sessions:\n\n- `lsp_diagnostics` — errors, warnings, and hints\n- `lsp_goto_definition` — jump to symbol definitions\n- `lsp_find_references` — find all usages across the workspace\n- `lsp_symbols` — document and workspace symbol search\n- `lsp_prepare_rename` — check if a rename is safe\n- `lsp_rename` — rename a symbol across the entire workspace\n\nSupports **40+ language server configs** out of the box.\n\n```text\n/lsp              Open the LSP server inspector\n/lsp status       Print installed/available language server summary\n/lsp install \u003cid\u003e Run a whitelisted install recipe\n/lsp warmup \u003cid\u003e  Preload a language server for the workspace\n```\n\n---\n\n## Workspace Memory\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/lsp-memory-preview.svg\" alt=\"ROACH PI LSP tools and workspace memory save/recall flow\" width=\"88%\"\u003e\n\u003c/p\u003e\n\nWorkspace memory stores important findings as structured records under pi's agent directory, scoped by workspace. It recalls relevant records into future sessions automatically.\n\n```text\n/memory list           List all memories\n/memory show \u003cid\u003e      Show a specific memory\n/memory save \u003ctext\u003e    Save a new memory\n/memory delete \u003cid\u003e    Delete a memory\n/memory search \u003cquery\u003e Search memories\n/memory stats          Show memory statistics\n```\n\nThe LLM-callable `memory_save` tool is used after bug fixes, decisions, or useful discoveries — so the agent avoids repeating the same fixes.\n\n---\n\n## Session Loop\n\n**`/loop`** schedules recurring prompts inside the current session — useful for health checks, monitoring, or continuous verification:\n\n```text\n/loop 5m check git status and report changes\n/loop 30s verify the dev server is running on port 3000\n```\n\nJobs are session-scoped, error-isolated, timeout-protected, and cleaned up on shutdown.\n\n```text\n/loop-list           List active loop jobs\n/loop-stop [job-id]  Stop one loop job\n/loop-stop-all       Stop all loop jobs\n```\n\n---\n\n## Autonomous Dev (Experimental)\n\nSet `PI_AUTONOMOUS_DEV=1` to enable the GitHub issue engine:\n\n```bash\nexport PI_AUTONOMOUS_DEV=1\npi\n```\n\n```text\n/autonomous-dev start owner/repo\n/autonomous-dev status\n/autonomous-dev poll\n/autonomous-dev stop\n```\n\nThe engine polls issues labeled `autonomous-dev:ready`, tracks progress in the footer/widget, asks for clarification when needed, and uses existing agents to implement work.\n\n---\n\n## Nested `AGENTS.md`\n\nThe bundled nested-agents extension injects nearby directory-level `AGENTS.md` files whenever the agent reads a file. This lets each subtree carry local conventions without forcing you to paste them into every prompt.\n\n```text\n/nested-agents           Toggle the nested AGENTS.md context widget\npi --no-nested-agents    Disable at startup\n```\n\n---\n\n## Commands Reference\n\n### Workflow\n\n| Command | Description |\n|---|---|\n| `/clarify [topic]` | Resolve ambiguity with dynamic questions and parallel exploration |\n| `/plan [topic]` | Create an executable implementation plan |\n| `/ultraplan [topic]` | Break complex work into milestones using five planning reviewers |\n| `/reset-phase` | Clear active clarify/plan/ultraplan state |\n\n### Review\n\n| Command | Description |\n|---|---|\n| `/review [target]` | Quick single-pass review (omit target, PR number, URL, or branch) |\n| `/ultrareview [target]` | Deep 10-reviewer pipeline with verifier and synthesis report |\n\n### Search, LSP, Memory\n\n| Command | Description |\n|---|---|\n| `/fff-mode both\\|tools-only` | Toggle FFF powering both tools and `@` autocomplete or tools only |\n| `/fff-health` | Show FFF engine, index, git, and frecency status |\n| `/fff-rescan` | Trigger an explicit FFF rescan |\n| `/lsp` | Open the LSP server inspector |\n| `/lsp status` | Print installed/available language server summary |\n| `/lsp install \u003cserverId\u003e` | Run a whitelisted install recipe or show a manual hint |\n| `/lsp warmup \u003cserverId\u003e` | Preload a language server for the workspace |\n| `/memory ...` | Manage workspace memories (list, show, save, delete, search, stats) |\n| `/loop \u003cinterval\u003e \u003cprompt\u003e` | Schedule recurring prompts |\n| `/loop-list` | List active loop jobs |\n| `/loop-stop [job-id]` | Stop one loop job |\n| `/loop-stop-all` | Stop all loop jobs |\n\n### Setup and Experimental\n\n| Command | Description |\n|---|---|\n| `/setup` / `/init` | Configure recommended settings (`quietStartup: true`) |\n| `/team ...` | Optional bounded team runner (requires `PI_ENABLE_TEAM_MODE=1`) |\n| `/autonomous-dev ...` | Experimental GitHub issue engine (requires `PI_AUTONOMOUS_DEV=1`) |\n| `/nested-agents` | Toggle nested `AGENTS.md` context widget |\n| `/ask` | Manual smoke test for `ask_user_question` |\n\n---\n\n## Tools Reference\n\n| Tool | What it does |\n|---|---|\n| `ask_user_question` | Focused multiple-choice or free-text clarification questions |\n| `subagent` | Specialized agents in single, parallel, chain, or async modes |\n| `webfetch` | Fetch web pages and convert to Markdown with caching |\n| `bash` | Sandboxed shell execution with optional approval policy |\n| `find` | FFF-backed fuzzy file search |\n| `grep` | FFF-backed content search with pagination |\n| `multi_grep` | Multi-pattern OR content search |\n| `memory_save` | Save structured workspace memories |\n| `team` | Optional team orchestration (gated by `PI_ENABLE_TEAM_MODE=1`) |\n| `lsp_*` | Diiagnostics, definitions, references, symbols, and rename |\n\n---\n\n## Configuration\n\n### Recommended Startup\n\n```jsonc\n// ~/.pi/agent/settings.json\n{\n  \"quietStartup\": true\n}\n```\n\n`/setup` writes this for you.\n\n### FFF Search Mode\n\n```bash\nPI_FFF_MODE=both pi          # tools + @ autocomplete\nPI_FFF_MODE=tools-only pi    # tools only\n```\n\nOr change it live:\n\n```text\n/fff-mode both\n/fff-mode tools-only\n```\n\n### Team Mode\n\n```bash\nPI_ENABLE_TEAM_MODE=1 pi\n```\n\nDisabled by default. Exposes the `team` tool and makes `/team` functional.\n\n### Autonomous Dev\n\n```bash\nPI_AUTONOMOUS_DEV=1 pi\nPI_AUTONOMOUS_LOG_PATH=~/.pi/autonomous-dev.log pi\n```\n\n### Sandboxed Bash Approval\n\n```bash\nPI_SANDBOX_APPROVAL_MODE=ask pi      # ask before escalation\nPI_SANDBOX_APPROVAL_MODE=always pi   # approve automatically\nPI_SANDBOX_APPROVAL_MODE=deny pi     # block escalation\n```\n\n### LSP Configuration\n\nCreate project-local `.pi/lsp-client.json` or user-global `~/.pi/lsp-client.json`:\n\n```jsonc\n{\n  \"lsp\": {\n    \"my-server\": {\n      \"command\": [\"my-lsp\", \"--stdio\"],\n      \"extensions\": [\".myext\"]\n    }\n  }\n}\n```\n\n---\n\n## Repository Layout\n\n```text\nextensions/\n  agentic-harness/     # workflows, subagents, review, team, webfetch, footer\n  fff-search/          # FFF-backed find/grep/multi_grep and @ autocomplete\n  session-loop/        # recurring session prompts\n  workspace-memory/    # save/recall workspace memory\n  autonomous-dev/      # experimental GitHub issue processor\ndocs/engineering-discipline/\n  context/             # Context Briefs\n  plans/               # implementation plans\n  reviews/             # review outputs\nassets/                # README visuals\n```\n\nBundled package dependencies also include `pi-lsp-client` and `@code-yeongyu/pi-nested-agents-md`.\n\n---\n\n## Development\n\nInstall dependencies in the extension you are changing, then run that extension's tests and type checks:\n\n```bash\nnpm --prefix extensions/agentic-harness install\nnpm --prefix extensions/agentic-harness test\nnpm --prefix extensions/agentic-harness run build\n```\n\nFor a broader local sweep, repeat the same pattern per extension:\n\n```bash\nnpm --prefix extensions/agentic-harness test \u0026\u0026 npm --prefix extensions/agentic-harness run build\nnpm --prefix extensions/fff-search test \u0026\u0026 npm --prefix extensions/fff-search run build\nnpm --prefix extensions/session-loop test \u0026\u0026 npm --prefix extensions/session-loop run build\nnpm --prefix extensions/workspace-memory test \u0026\u0026 npm --prefix extensions/workspace-memory run build\nnpm --prefix extensions/autonomous-dev test \u0026\u0026 npm --prefix extensions/autonomous-dev run build\n```\n\nThere is no root `npm test` script in `package.json`; use the extension-level commands above.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). For larger changes, prefer the same discipline the extension enforces: clarify the goal, write a plan, implement in small steps, and verify with tests or a focused manual check.\n\n---\n\n## License\n\nMIT. The package metadata in [package.json](package.json) declares the license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmdgusya%2Froach-pi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmdgusya%2Froach-pi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmdgusya%2Froach-pi/lists"}