π pi-project-profile
Project-aware π (pi) coding agent with a verification gate. Detects any repository's stack, commands, conventions and instruction files (AGENTS.md, CLAUDE.md, .cursorrules, …), injects them as a stable <project_profile> system-prompt section, then runs the project's own typecheck, lint, tests and build after every agent turn — with a bounded self-repair loop and a review of the agent's diff. It never writes into the repository.
pi install npm:@lenard9191/pi-project-profile
What it does
- Profile — detects the stack, commands (including how to run one test), conventions, CI checks, test layout, generated code and instruction files (
AGENTS.md,CLAUDE.md,.cursorrules, Copilot, Windsurf, Cline, Gemini, Codex, …), and injects them as a stable<project_profile>section that keeps prompt caching intact. - Verify — after every turn that changed files, runs the project's own checks by tier (syntax → typecheck → lint automatically; tests and build once you allow them per repository) and sends only new failures back to the agent for at most three repair rounds.
- Review — flags what a reviewer would want to know about the agent's diff: added suppressions, skipped or focused tests, stubs, loosened configs, deleted tests, secrets, unignored
.envfiles, stale lockfiles. - Rules on demand — delivers nested
AGENTS.mdfiles and glob-scoped rules (Cursor, Copilot, Windsurf) when the agent first touches a file they apply to, and warns before hand-editing generated files.
Installs, migrations, deploys and anything network-bound are never run. Cache and settings live under ~/.pi/agent/project-profile/. Requires π ≥ 0.87 and Node ≥ 22.18; no runtime dependencies; MIT.
What the agent sees
<project_profile>
- Project: zod — ~/projects/zod · remote github.com/colinhacks/zod · ~741 tracked files
- Stack: monorepo: pnpm workspaces (8 packages) · pnpm · Vite · Vitest
- Commands: install `pnpm install` · typecheck `pnpm exec tsc --noEmit -p tsconfig.json` · lint `pnpm run lint` · test `pnpm run test` · test one `pnpm exec vitest run <file> -t "<name>"`
- Conventions: ESM · Prettier · Biome · Husky git hooks · License: MIT
- Tests: `*.test.ts` in tests/ (202)
- Instruction files: AGENTS.md (loaded) · .cursorrules (22 KB — read it when relevant)
- Verification: after each turn that changed files, the harness runs `pnpm exec tsc --noEmit -p tsconfig.json`, `pnpm run lint:check` automatically; asks once before running tests
</project_profile>Verification tiers
| Tier | Examples | Policy |
|---|---|---|
| syntax | node --check, python -c ast.parse, ruby -c, bash -n, JSON parse | automatic, changed files only |
| fast | tsc --noEmit, cargo check, go build/go vet, mypy/pyright, mix compile, dart analyze | automatic |
| lint | eslint, biome, prettier --check, ruff, cargo fmt --check/clippy, gofmt, rubocop, swiftlint | automatic |
| test | npm test, cargo test, pytest, go test, rspec, mix test, phpunit, swift test, ./gradlew test | confirmed once per repo |
| build | pnpm build, ./gradlew compile*, swift build, zig build, cmake --build | confirmed once per repo |
Pre-existing failures (a repository that was already red) are hidden from the agent and reported to you once. Tests are narrowed to the changed files when that is safe (vitest related, jest --findRelatedTests, go test ./<pkg>/..., cargo test -p, pytest <files>); monorepo packages are checked in their own directory. Format and lint failures come with the exact auto-fix command.
Coverage
Node/TypeScript (npm, pnpm, yarn, bun; workspaces, Turborepo, Nx), Deno, Rust, Go, Python (uv, poetry, pdm, pipenv, hatch), Ruby, JVM (Gradle, Maven, Kotlin, Android), .NET, Swift, PHP, Elixir, Dart/Flutter, C/C++ (CMake, Meson), Zig, Haskell, Scala, OCaml, Gleam, Erlang, Terraform, shell, Lua, Perl, plus Makefile/justfile/Taskfile targets, Bazel, CI files (GitHub Actions, GitLab, CircleCI, Azure, Travis, Jenkins, Buildkite, Bitbucket), docker-compose services and umbrella repositories. Tested on macOS, Linux and Windows.
Commands and tool
/profile | show the profile, checks, availability and cache path |
/profile doctor | required vs installed runtimes, tool and dependency availability, fix commands (never run) |
/profile set <key> <cmd> | override typecheck, lint, test, build, … (- disables) |
/profile tests allow|deny|ask | test-tier permission (same for build) |
/verify [fast|lint|test|build|all] [file…] | run checks now, showing every failure |
run_checks | the same, as a tool the model can call mid-task |
The package also ships an Agent Skill (/skill:project-profile) that the model loads on demand to interpret verification messages and explain configuration. Full reference: README.
FAQ
Does it work with Claude Code, Cursor, Codex or GitHub Copilot?
It is an extension for the π coding agent only. It does read the instruction files those tools use (CLAUDE.md, .cursorrules, .cursor/rules, copilot-instructions.md, .github/instructions, Windsurf and Cline rules, GEMINI.md, codex.md), so a repository already set up for them is understood by π with no extra configuration.
Does it change anything in my repository?
No. Detection is read-only; the cache and per-repo settings live under ~/.pi/agent/project-profile/ and logs under $TMPDIR/pi-project-profile/. The automatic checks are the project's own read-only commands; auto-fix commands are suggested, never run.
Will it run my tests or builds automatically?
Only after you allow it once per repository. Typecheck and lint run automatically because they are read-only. Installs, migrations, deploys and anything that needs the network are never run.
What happens when a check fails?
The failing diagnostics go back to the agent, which must fix the cause — not disable the check — and end its turn; the checks re-run. After three rounds, or when a round changes nothing or repeats the same failure, the loop stops and the agent summarizes what is still failing instead of claiming success.
Does it break prompt caching?
No. The <project_profile> section contains no timestamps, branch names or iteration-order-dependent content, so it is byte-identical for every turn of a session.
The detected command is wrong. How do I fix it?
/profile set <key> <command> overrides one key for the repository (use - to disable it); /profile doctor explains missing tools; /profile refresh re-detects; /profile note persists guidance for the agent.