@willyfrog/agents-warning

A pi extension that shows a startup warning widget when both AGENTS.md and CLAUDE.md are missing in the current working directory.

The warning can be:

• suppressed for specific paths via config
• dismissed for the current pi run/session
• disabled for one run via CLI flag

Behavior

On session_start, the extension:

1. Does nothing if ctx.hasUI is false
2. Does nothing if warning was dismissed in this run/session
3. Does nothing if --no-agents-warning is set
4. Loads config from global + project files
5. Does nothing if cwd is under a configured disabled path
6. Checks only cwd (no parent traversal):
   • if AGENTS.md exists: no warning
   • else if CLAUDE.md exists: no warning
   • else: show warning widget above editor

Install

Add the package to your pi packages configuration (global or project settings):

{
  "packages": [
    "npm:@willyfrog/[email protected]"
  ]
}

Then restart pi or run /reload.

Commands

/dismiss-agents-warning

Dismisses the warning for the current run/session only.

Flags

--no-agents-warning

Suppresses the warning behavior for the current pi run only.

Configuration

Two optional JSON config files are supported:

• Global: <agentDir>/agents-warning.json
  • typically ~/.pi/agent/agents-warning.json
• Project: <cwd>/.pi/agents-warning.json

Schema:

{
  "disabledPaths": [
    "/absolute/path",
    "~/path",
    "../relative-to-config"
  ]
}

Rules:

• disabledPaths entries can be absolute or relative
• ~ expands to the user home directory
• relative paths are resolved relative to the config file directory
• global + project disabledPaths are concatenated and deduped
• matching is based on normalized resolved paths
• if cwd is equal to or under a disabled path, warning is suppressed
• invalid or missing config files are ignored with warning; defaults are used

Widget text

Shown as an editor widget with id agents-warning and placement aboveEditor:

• Missing AGENTS.md/CLAUDE.md in <cwd>
• Create one or disable this check in .pi/agents-warning.json

Development

bun install
bun run lint
bun run typecheck
bun run test
./scripts/run-acceptance.sh