{"id":50055979,"url":"https://github.com/code-yeongyu/pi-rules","last_synced_at":"2026-05-21T13:14:20.903Z","repository":{"id":354733170,"uuid":"1224370764","full_name":"code-yeongyu/pi-rules","owner":"code-yeongyu","description":"Rule context loader extension for the pi coding agent","archived":false,"fork":false,"pushed_at":"2026-05-14T03:24:31.000Z","size":204,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T05:24:11.307Z","etag":null,"topics":["agent-rules","agents-md","claude-md","coding-agent","context-injection","extension","oh-my-openagent","omo","pi","pi-coding-agent","pi-extension","pi-mono","pi-package","rules","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/badlogic/pi-mono","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/code-yeongyu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-29T08:05:46.000Z","updated_at":"2026-05-14T03:24:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/code-yeongyu/pi-rules","commit_stats":null,"previous_names":["code-yeongyu/pi-rules"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/code-yeongyu/pi-rules","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-rules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-rules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-rules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-rules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/code-yeongyu","download_url":"https://codeload.github.com/code-yeongyu/pi-rules/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-yeongyu%2Fpi-rules/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33301826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"ssl_error","status_checked_at":"2026-05-21T12:22:11.673Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agent-rules","agents-md","claude-md","coding-agent","context-injection","extension","oh-my-openagent","omo","pi","pi-coding-agent","pi-extension","pi-mono","pi-package","rules","typescript"],"created_at":"2026-05-21T13:14:18.559Z","updated_at":"2026-05-21T13:14:20.895Z","avatar_url":"https://github.com/code-yeongyu.png","language":"TypeScript","funding_links":[],"categories":["Extensions"],"sub_categories":[],"readme":"# pi-rules\n\n[![ci](https://github.com/code-yeongyu/pi-rules/actions/workflows/ci.yml/badge.svg)](https://github.com/code-yeongyu/pi-rules/actions/workflows/ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![npm](https://img.shields.io/badge/npm-%40code--yeongyu%2Fpi--rules-red)](https://www.npmjs.com/package/@code-yeongyu/pi-rules)\n\nRule context loader for the [pi coding agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent). Discovers rule files from `.omo/rules/`, `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, `AGENTS.md`, `CLAUDE.md`, and injects them into the agent context.\n\n## Origin\n\npi-rules is inspired by [oh-my-openagent (omo)](https://github.com/code-yeongyu/oh-my-openagent) `.omo/rules/` and opencode's `AGENTS.md` / `CLAUDE.md` instruction file mechanisms.\n\n- [omo](https://github.com/code-yeongyu/oh-my-openagent) at https://github.com/code-yeongyu/oh-my-openagent is by Yeongyu Kim, originally SUL-1.0.\n- This package is an **independent** pi-coding-agent extension by the same author.\n- Source distributed here is MIT (see [LICENSE](LICENSE) and [NOTICE](NOTICE)).\n- The logic is structurally similar to omo's rules-injector hook, adapted to pi-mono's ExtensionAPI hooks (`before_agent_start`, `tool_result`).\n\n## Quick Demo\n\n```text\n$ pi -e ./src/index.ts\n\n[pi-rules] 5 active rules\n\n\u003e Read src/auth/login.ts\n\n  ✓ src/auth/login.ts (1.2KB)\n\n[pi-rules] +2 instructions injected (security.md, typescript.md)\n```\n\n## Installation\n\nThe package targets the [`pi`](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) coding agent. Pi loads extensions from `~/.pi/agent/extensions/`, project `.pi/extensions/`, or via the `--extension` / `-e` CLI flag.\n\nPick whichever route fits:\n\n```bash\n# 1. From npm (once published)\npi install npm:@code-yeongyu/pi-rules\n\n# 2. From git (once the repository is pushed)\npi install git:github.com/code-yeongyu/pi-rules\n\n# 3. Manual placement (always works)\ngit clone https://github.com/code-yeongyu/pi-rules ~/.pi/agent/extensions/pi-rules\ncd ~/.pi/agent/extensions/pi-rules \u0026\u0026 npm install\n\n# 4. Dev / one-shot test\npi -e /path/to/pi-rules/src/index.ts\n```\n\nAfter installation, restart pi (or run `/reload` inside an interactive session).\n\n## What gets loaded\n\n### Project rule directories (recursive `*.md` / `*.mdc`)\n\n| Directory | Style |\n|-----------|-------|\n| `.omo/rules/` | omo style |\n| `.claude/rules/` | Claude Code style |\n| `.cursor/rules/` | Cursor style |\n| `.github/instructions/` | GitHub Copilot style (only `*.instructions.md`) |\n\nThese use **walk-up stack semantics**: from the target file's directory up to the project root, rules at every level are collected. Closer directories win in precedence.\n\n### Project single-file rules\n\n| File | Style |\n|------|-------|\n| `.github/copilot-instructions.md` | GitHub Copilot |\n| `AGENTS.md` | opencode style |\n| `CLAUDE.md` | Claude Code style |\n| `CONTEXT.md` | deprecated, still supported |\n\nThese use **first-match-wins** at the project root: `AGENTS.md` takes priority over `CLAUDE.md`, which takes priority over `CONTEXT.md`.\n\n### User-home rules (always-on, distance 9999)\n\n| Path | Type |\n|------|------|\n| `~/.omo/rules/` | directory |\n| `~/.opencode/rules/` | directory |\n| `~/.claude/rules/` | directory |\n| `~/.config/opencode/AGENTS.md` | single-file |\n| `~/.claude/CLAUDE.md` | single-file |\n\nUser-home rules are global and apply to every project with the lowest precedence.\n\n## Rule format\n\nRules are Markdown files with an optional YAML frontmatter block:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `description` | `string` | Optional short description |\n| `globs` | `string \\| string[]` | Glob patterns; rule applies if target file matches any |\n| `paths` | `string \\| string[]` | Claude Code alias for globs (merged) |\n| `applyTo` | `string \\| string[]` | GitHub Copilot alias for globs (merged) |\n| `alwaysApply` | `boolean` | If true, rule always applies regardless of target |\n\nExample rule file:\n\n```markdown\n---\ndescription: TypeScript-specific rules\nglobs: [\"**/*.ts\", \"**/*.tsx\"]\n---\n\n# TypeScript\n\nPrefer `unknown` over `any`. Use exhaustive switch checks.\n```\n\n## Precedence and merging\n\nRules are ordered deterministically before injection:\n\n1. **Local before global** — project rules outrank user-home rules.\n2. **Closest distance first** — rules from directories nearer to the target file take priority.\n3. **Source priority** — `.omo/rules` \u003e `.claude/rules` \u003e `.cursor/rules` \u003e `.github/instructions` \u003e `AGENTS.md` \u003e `CLAUDE.md` \u003e `CONTEXT.md` \u003e user-home variants.\n4. **Lexicographic `relativePath`** — final tiebreaker for same-source, same-distance rules.\n\nDeduplication is in-memory per session by `realPath + content hash`. No filesystem persistence.\n\n## Slash commands\n\n| Command | Purpose |\n|---------|---------|\n| `/rules` | Summary of active rules |\n| `/rules list` | List all rule files with paths |\n| `/rules show \u003cid\u003e` | Show body of one rule |\n| `/rules paths` | List absolute paths only |\n| `/rules status` | Counts and warnings |\n| `/reload-rules` | Rescan and clear injection cache |\n\nAll commands work in both UI and plain-text modes.\n\n## TUI widget\n\nOn session start, a banner appears above the editor with a `[pi-rules]` prefix and a list of top rules. Active rules show a `●` indicator; rules with warnings show `⚠`. The banner dismisses on the first `before_agent_start` event.\n\nA persistent status line reads `[pi-rules] N active` and updates as rules are discovered or rescanned.\n\n## Configuration\n\n### CLI flags\n\n| Flag | Type | Default | Purpose |\n|------|------|---------|---------|\n| `pi-rules-disabled` | `boolean` | `false` | Disable all injection |\n| `pi-rules-mode` | `string` | `both` | `static` \\| `dynamic` \\| `both` \\| `off` |\n| `pi-rules-widget` | `boolean` | `true` | Show banner and status line |\n\n### Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `PI_RULES_DISABLED` | unset | If `1`, disables injection |\n| `PI_RULES_MAX_RULE_CHARS` | `12000` | Per-rule body cap |\n| `PI_RULES_MAX_RESULT_CHARS` | `40000` | Total injected per tool result |\n\n## Trust model\n\nRule files are prompt and context input. Do NOT load untrusted repositories. All rule loading is local filesystem reads. There is no network or remote rule fetching.\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| No rules loaded | Verify `.omo/rules/`, `AGENTS.md`, etc. exist in the project root or ancestors. Run `/rules` to inspect. |\n| Rule not matching | Check frontmatter `globs` / `paths` / `applyTo`. Confirm the target file path matches the glob. |\n| Duplicate injection | Automatically deduplicated per session. Try `/reload-rules` to reset. |\n| Extension not loaded | Confirm `pi.extensions` in your `package.json` or use `pi -e ./src/index.ts` for one-shot. |\n| Context too large | Adjust `PI_RULES_MAX_RULE_CHARS` and `PI_RULES_MAX_RESULT_CHARS`. |\n| TUI widget missing | Check `pi-rules-widget` flag is true and your terminal supports the relevant glyphs. |\n\n## Development\n\n```bash\ngit clone https://github.com/code-yeongyu/pi-rules\ncd pi-rules\nnpm install            # install dev + peer deps\nnpm test               # 229 unit tests\nnpm run test:integration  # 43 integration tests\nnpm run typecheck      # tsc --noEmit\nnpm run check          # tsc + biome\npi -e ./src/index.ts   # smoke-test inside a real pi session\n```\n\nThe test suite uses Vitest. Test descriptions follow `#given X #when Y #then Z` style; bodies use `// given / // when / // then` plain comments. No `any` in production code, no enums.\n\n## License\n\n[MIT](LICENSE). See [NOTICE](NOTICE) for re-license disclosure relative to omo.\n\n## Related\n\n- [senpi](https://github.com/code-yeongyu/senpi) — the fork/runtime these extensions are extracted from.\n- [Ultraworkers Discord](https://discord.gg/PUwSMR9XNk) — community link from the senpi README.\n- [Dori](https://sisyphuslabs.ai) — the product powered by senpi under the hood.\n\n## Acknowledgements\n\n- **Yeongyu Kim** ([@code-yeongyu](https://github.com/code-yeongyu)) — author of [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) (origin of the rules-injection idea), and of this pi port.\n- **Mario Zechner** ([@badlogic](https://github.com/badlogic)) — author of [pi-mono](https://github.com/badlogic/pi-mono) and the pi-coding-agent extension API this package targets.\n- **opencode** — for the elegant `Instructions from: \u003cpath\u003e` formatting convention adopted here.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-yeongyu%2Fpi-rules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcode-yeongyu%2Fpi-rules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-yeongyu%2Fpi-rules/lists"}