alex/pi-shared

Watch

Fork 0

Share a global AGENTS.md #9

New issue

Closed

opened 2026-06-30 15:59:32 +00:00 by alex · 2 comments

alex commented

2026-06-30 15:59:32 +00:00

Owner

At the moment I just drop ~/.pi/agents/AGENTS.md locally with some simple instructions:

# General rules for coding agents

- usually running in sandboxes so to avoid issues with (read-only) Git commands, use the following env:
  - GIT_CONFIG_NOSYSTEM=1
  - GIT_CONFIG_GLOBAL=/dev/null

- **DO NOT COMMIT NOR PUSH ANY CHANGE WITHOUT PERMISSION**. This includes interacting with GitHub/Forgejo issues/pull requests.

- when creating Markdown files, do not wrap lines, let the editor/viewer wrap them.

Analyze the Pi extensibility and figure out how we can do this just installing this very repo as we do now (pi install git:forge.l3x.in/alex/pi-shared) and remove the need for the ~/.pi agents file.

At the moment I just drop `~/.pi/agents/AGENTS.md` locally with some simple instructions: ```text # General rules for coding agents - usually running in sandboxes so to avoid issues with (read-only) Git commands, use the following env: - GIT_CONFIG_NOSYSTEM=1 - GIT_CONFIG_GLOBAL=/dev/null - **DO NOT COMMIT NOR PUSH ANY CHANGE WITHOUT PERMISSION**. This includes interacting with GitHub/Forgejo issues/pull requests. - when creating Markdown files, do not wrap lines, let the editor/viewer wrap them. ``` Analyze the Pi extensibility and figure out how we can do this just installing this very repo as we do now (`pi install git:forge.l3x.in/alex/pi-shared`) and remove the need for the `~/.pi` agents file.

alex commented

2026-06-30 16:05:08 +00:00

Author

Owner

/pi work on it in a new PR

forgejo-actions referenced this issue from a commit

2026-06-30 16:14:55 +00:00

feat: ship a global AGENTS.md via the global-agents extension

forgejo-actions referenced this issue from a pull request that will close it,

2026-06-30 16:15:09 +00:00

feat: ship a global AGENTS.md via the global-agents extension #10

forgejo-actions commented

2026-06-30 16:15:21 +00:00

Key finding: Pi packages can only declare extensions, skills, prompts, and themes in their manifest — there is no mechanism for a package to ship a global context file (AGENTS.md). Global AGENTS.md files are loaded only from the global agent dir (~/.pi/agent/AGENTS.md) or project ancestors.

The solution is an extension that injects the rules into the system prompt via the before_agent_start event — exactly the pattern used by pi's own claude-rules.ts example. Since the pi manifest already declares "extensions": ["./extensions"], a new extension file is auto-discovered on pi install.

Let me build it:Now let me typecheck the extension against the installed pi types and validate the runtime resolution logic:Typecheck passes. Now let me verify the path-resolution logic actually points at the file (the extension is at <root>/extensions/global-agents.ts, so two dirname calls should yield the package root):Path resolution works correctly. Now let me confirm the new extension is auto-discovered by the existing pi manifest ("extensions": ["./extensions"] loads all .ts files), and check there are no other references that need updating:The new extension is auto-discovered by the existing manifest. Let me do a final runtime sanity check by loading the extension through jiti (the exact loader pi uses) and invoking its handlers:The extension works end-to-end under pi's actual jiti loader — both events register and the global instructions are correctly appended to the system prompt. Now let me document it in the README:Let me do a final review of all changes and make sure nothing stray is left behind:Everything is clean (node_modules/ is correctly ignored). Let me create the pull request:This is a Forgejo instance (public at https://forge.l3x.in) where the default branch is master, not main. My override of base: "main" caused the 404. Let me retry with the correct base branch:The PR tool isn't compatible with this Forgejo instance's API. Let me create the branch, commit, push, and open the PR via the Forgejo REST API directly. First, let me verify connectivity and git identity:API works with the token. Let me set git identity, create a branch, commit, and push:Branch pushed. Now let me create the pull request via the Forgejo REST API:PR #10 created successfully: #10

Summary

I analyzed Pi's extensibility model and implemented a way to ship global AGENTS.md rules with the package itself, eliminating the manual ~/.pi/agent/AGENTS.md file.

The finding

Pi packages can declare extensions, skills, prompts, and themes — but not a global context file. Global AGENTS.md files are loaded only from the global agent dir (~/.pi/agent/AGENTS.md) or project ancestors (in loadProjectContextFiles), and resources_discover has no return value for context files. So there's no native "ship a global AGENTS.md" manifest key.

The solution

A new global-agents extension (extensions/global-agents.ts) that injects agents/AGENTS.md into every session's system prompt via the before_agent_start hook — the exact pattern pi's own examples/extensions/claude-rules.ts uses. It:

resolves agents/AGENTS.md relative to itself via import.meta.url,
re-reads it on each session_start so /new and /reload pick up edits,
appends it in a <global_context> block that mirrors pi's <project_context> context-file format.

It auto-loads because the existing manifest already declares "extensions": ["./extensions"] — no package.json change needed.

Verified

tsc --strict against the installed pi types passes.
Loaded it through pi's actual loader (jiti) and exercised both handlers — before_agent_start correctly appends the rules block.

Note: the built-in PR tool returned 404 (this repo runs on Forgejo with default branch master), so I created the branch, pushed, and opened the PR via the Forgejo REST API.

Now I understand the Pi extensibility model. Let me verify the global context-file loading path to confirm my approach:I have a clear understanding now. Let me summarize my findings before implementing: **Key finding:** Pi packages can only declare `extensions`, `skills`, `prompts`, and `themes` in their manifest — there is **no** mechanism for a package to ship a global context file (`AGENTS.md`). Global `AGENTS.md` files are loaded *only* from the global agent dir (`~/.pi/agent/AGENTS.md`) or project ancestors. The solution is an **extension** that injects the rules into the system prompt via the `before_agent_start` event — exactly the pattern used by pi's own `claude-rules.ts` example. Since the `pi` manifest already declares `"extensions": ["./extensions"]`, a new extension file is auto-discovered on `pi install`. Let me build it:Now let me typecheck the extension against the installed pi types and validate the runtime resolution logic:Typecheck passes. Now let me verify the path-resolution logic actually points at the file (the extension is at `<root>/extensions/global-agents.ts`, so two `dirname` calls should yield the package root):Path resolution works correctly. Now let me confirm the new extension is auto-discovered by the existing `pi` manifest (`"extensions": ["./extensions"]` loads all `.ts` files), and check there are no other references that need updating:The new extension is auto-discovered by the existing manifest. Let me do a final runtime sanity check by loading the extension through jiti (the exact loader pi uses) and invoking its handlers:The extension works end-to-end under pi's actual jiti loader — both events register and the global instructions are correctly appended to the system prompt. Now let me document it in the README:Let me do a final review of all changes and make sure nothing stray is left behind:Everything is clean (`node_modules/` is correctly ignored). Let me create the pull request:This is a **Forgejo** instance (public at `https://forge.l3x.in`) where the default branch is `master`, not `main`. My override of `base: "main"` caused the 404. Let me retry with the correct base branch:The PR tool isn't compatible with this Forgejo instance's API. Let me create the branch, commit, push, and open the PR via the Forgejo REST API directly. First, let me verify connectivity and git identity:API works with the token. Let me set git identity, create a branch, commit, and push:Branch pushed. Now let me create the pull request via the Forgejo REST API:PR #10 created successfully: https://forge.l3x.in/alex/pi-shared/pulls/10 ## Summary I analyzed Pi's extensibility model and implemented a way to ship global `AGENTS.md` rules **with the package itself**, eliminating the manual `~/.pi/agent/AGENTS.md` file. ### The finding Pi packages can declare `extensions`, `skills`, `prompts`, and `themes` — but **not** a global context file. Global `AGENTS.md` files are loaded only from the global agent dir (`~/.pi/agent/AGENTS.md`) or project ancestors (in `loadProjectContextFiles`), and `resources_discover` has no return value for context files. So there's no native "ship a global AGENTS.md" manifest key. ### The solution A new **`global-agents` extension** (`extensions/global-agents.ts`) that injects `agents/AGENTS.md` into every session's system prompt via the `before_agent_start` hook — the exact pattern pi's own `examples/extensions/claude-rules.ts` uses. It: - resolves `agents/AGENTS.md` relative to itself via `import.meta.url`, - re-reads it on each `session_start` so `/new` and `/reload` pick up edits, - appends it in a `<global_context>` block that mirrors pi's `<project_context>` context-file format. It auto-loads because the existing manifest already declares `"extensions": ["./extensions"]` — no `package.json` change needed. ### Verified - `tsc --strict` against the installed pi types passes. - Loaded it through pi's actual loader (jiti) and exercised both handlers — `before_agent_start` correctly appends the rules block. Note: the built-in PR tool returned 404 (this repo runs on Forgejo with default branch `master`), so I created the branch, pushed, and opened the PR via the Forgejo REST API. --- [View action run](https://forge.l3x.in/alex/pi-shared/actions/runs/15) | Model: zai/glm-5.2 (thinking: xhigh) | Time: 10m 13s | Tokens: 1.9M | Pi SDK v0.80.2 | Action v2.24.0-develop (develop @ 268c2eb)

alex closed this issue

2026-06-30 16:31:34 +00:00

No labels

dependencies

No milestone

No assignees

2 participants

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

alex/pi-shared#9

No description provided.

Rows
Columns