---
slug: "the-agency-pi-spec-kit"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/JoshMock/the-agency@main/README.md"
repo: "https://github.com/JoshMock/the-agency"
source_file: "README.md"
branch: "main"
---
A collection of extensions, skills, tools and experiments with the [Pi coding agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent).

## Current offerings

- [**@the-agency/pi-tokenshrink**](https://github.com/JoshMock/the-agency/tree/HEAD/packages/tokenshrink/): reduce a prompt's token count deterministically, without using inference ![NPM Downloads](https://img.shields.io/npm/dm/%40the-agency%2Fpi-tokenshrink)
- [**@the-agency/pi-hashline-edit**](https://github.com/JoshMock/the-agency/tree/HEAD/packages/hashline-edit/): alternate to Pi's built in `edit` tool that improves the accuracy and efficiency of file edits, with high potential to reduce token usage ![NPM Downloads](https://img.shields.io/npm/dm/%40the-agency%2Fpi-hashline-edit)
- [**@the-agency/pi-spec-kit**](https://github.com/JoshMock/the-agency/tree/HEAD/packages/spec-kit/): use [Spec Kit](https://github.com/github/spec-kit) for spec-driven development ![NPM Downloads](https://img.shields.io/npm/dm/%40the-agency%2Fpi-spec-kit)
- [**@the-agency/vmpi**](https://github.com/JoshMock/the-agency/tree/HEAD/packages/vmpi/): run `pi` sandboxed in a QEMU microVM via [Gondolin](https://earendil-works.github.io/gondolin/) -- hardware-isolated, no root required ![NPM Downloads](https://img.shields.io/npm/dm/%40the-agency%2Fvmpi)
- [**@the-agency/pi-observability**](https://github.com/JoshMock/the-agency/tree/HEAD/packages/observability/): record OpenTelemetry logs for your Pi sessions ![NPM Downloads](https://img.shields.io/npm/dm/%40the-agency%2Fpi-observability)

## Goals

### Local inference

**Privacy**, **self-sufficiency**, **ethics** and **energy conservation** are personal values of mine, so there will be an emphasis on local and low-energy inference sources (e.g. [vLLM](https://docs.vllm.ai/) using local GPUs or CPUs).

Local inference also enables experimentation with open models that have been trained on more carefully curated sets of data.

### Security

  See [vmpi](https://github.com/JoshMock/the-agency/tree/HEAD/packages/vmpi/). [pi-guardrails](https://www.npmjs.com/package/@aliou/pi-guardrails) is a handy UX improvement, but it's not a security feature. Even running in a Docker container or a process-level sandbox is not bulletproof. If you're installing packages from npm, *especially* if they're developed with agent assistance, all that code should be isolated from the rest of your system. Running your agent—and its extensions, tools and skills—in a virtual machine is the safest way to protect your machine from errant agent choices and supply-chain attacks.

### Do less, better

Avoid maximalism and accelerationism vibes. All code output is authored by a human—assisted by an agent, but with thorough review and revision—who understands, dog-foods and ultimately vouches for all code before publishing it for others. These are tools to help developers craft a coding agent experience to help them, not replace them. It is **not** intended to enable [inactive gods](https://en.wikipedia.org/wiki/Deus_otiosus) wishing to set a course and walk away.

Doing less also means:

- optimizing prompts for token efficiency
- limiting what agents can see and do to avoid context bloat and incorrect choices

Doing better also means:

- navigating code lexically: why grep when you can query a syntax tree?
- optimizing prompts for accuracy, preventing agents from doing the wrong thing
- measure performance where possible to find bottlenecks

## Recommendations

I'm not going to write a plugin or related tool if one already exists that solves a problem well. Here are some tools I'm currently using or experimenting with alongside these plugins:

- [**headroom**](https://github.com/headroomlabs-ai/headroom): deterministic prompt compression, combining multiple tools and strategies, including [RTK](https://github.com/rtk-ai/rtk)
- [**llama.cpp**](https://github.com/ggml-org/llama.cpp): serve open models locally; even if you only have a 4GB VRAM GPU in a laptop, coding inference with a [Qwen coding model](https://huggingface.co/collections/unsloth/qwen3-coder) is slow but effective
- [**ponytail**](https://github.com/DietrichGebert/ponytail): build code that prefers simple, reusable solutions that depend on existing code and dependencies whenever possible
- [**pi-subagents**](https://github.com/nicobailon/pi-subagents): I prefer to "pair program" with an agent iteratively; in the rare case you need to distribute work to multiple agents to keep contexts clean, this is all you need
- **maintaining long-term memory by hand:** I have tried several solutions that help an agent learn and get better on its own over time. They worked, but burn extra tokens on a self-learning loop. Putting reusable instructions in the context files an agent already uses is simple and just as effective. When something goes wrong, edit AGENTS.md by hand, or update Pi's APPEND_SYSTEM.md file for general instruction. If the file gets too long, apply the [progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) pattern: split it up and use AGENTS.md as table of contents.
- [**pi-autoresearch**](https://github.com/davebcn87/pi-autoresearch): one of the other rare use cases where I let an agent loose on its own is looking for performance optimizations; autoresearch is the simplest solution.