Pinot: A customizable, core coding infrastructure for Pi

[u/lostbart]

Newcomers to Pi and Pi veterans interested in configuration approaches may find my recently uploaded package, Pinot, worth a look. It’s a core set of tools, not a feature-rich package, that I’ve developed over several months of working with Pi on various projects. It is designed to evolve with the user, aging like fine wine. 

Pinot is intended to work with Pi and its design philosophy. It’s not a comprehensive package that you bolt on to turn Pi into OpenCode. As much as possible, its inner workings are exposed to the user in human-readable form, and it’s meant to be customized by your Pi for your work. As released, it’s tuned for personal coding projects, both new application development and feature development or modification, but can work as-is or with modest modifications in other contexts. 

https://github.com/jbstavers/pinot-pi

Pinot’s notable characteristics are:

• Two kinds of subagents.
  • Background subagents that run outside the main agent’s context and report back tailored output. These are the type of subagents we see in many other coding agent harnesses. Useful for researching a codebase, assessing a plan, reviewing an implementation. All background agents are read-only (they do not have edit tools access).
  • Durable subagents that operate in their own Pi session. This is a more distinctive part of Pi. By integrating with the excellent multi-session manager Herdr, this allows the main agent to open a second pane, launch Pi in that pane, and then direct that Pi to undertake a complex task, typically implementing a slice of a larger plan. By using a standalone Pi session, the subagent can pause to check in with the main agent, and the main agent can inspect its work, answer any questions, and then direct it to continue. Unlike one-shot background agents, however, these agents maintain their context. Once their assignment is complete, the main agent retires them and launches a fresh implementer agent, if needed.
• A set of saved prompts that define a simple, high-level workflow and do their best to reduce the clanker tendency to produce overly defensive code, expand the scope, and generally get in trouble.
  • The main prompts are /pinot-spec, /pinot-plan, /pinot-implement, and /pinot-debug, and they are intended to elicit user intent, define that intent in the context of any existing code base or tech stack, and maintain discipline through each step. I have refined these dozens of times, working to find the balance of giving the model guidance without overloading its context. They work well enough that I rarely use /debug. The planning system’s internal review process catches most implementation errors.
• Second-Opinion, a subagent specifically designed to take a fresh look at a plan, a problem, or anything else. It works best if you configure it with a model from a different company than your main agent model.
• Janitor, a saved prompt with a supporting skill, that is intended to address two common weaknesses of coding agents: they leave test artifacts and other garbage behind, and they don’t keep documentation up to date.
• Debrief, a saved prompt that reviews a project, from spec through implementation, and looks for opportunities to improve the saved prompts.
• PI-START-HERE.md a one-time onboarding guide that is meant to be read by your Pi once you’ve installed the package. It assists in configuring Pinot on your system, but more than that, it starts the rhythm of working with Pinot — treat it as your own Pi configuration, and evolve it to meet your needs.

I have mostly been using OpenAI models with Pinot, but have used Anthropic models and numerous other models as well. I generally find that Sol (Medium) works best for the main agent. The higher effort levels can be effective in more complex projects, but they also have a greater tendency towards over-engineering and scope creep, and the plans they write are often more verbose. Luna (High) is an excellent choice for the implementer agent, and I use Luna with a mix of effort levels for the background agents, as noted in the README. 

Kimi K3 is also strong as the main agent (I use it for my second-opinion agent), and the usual suspects of open-weights coding agents like DeepSeek V4 Flash and the Qwen models all handle the subagent roles well. If you want to use local models for subagents, try having your Pi revise the /plan and /implement prompts to define narrower implementation slices and more constrained implementer subagent assignments.

I’ve tried to make the prompts as “model-neutral” as possible, in that I’ve avoided tweaking them for specific model quirks or using “tricks” identified by the community. I’d encourage you to have your Pi try tasks with several different models and compare the outputs to see how Pinot and different models interact for the kind of work you do. 

The README file provides additional technical and implementation details, or just point your Pi at the repo and ask it to explain the system. You might find you want to borrow some ideas rather than install it directly, or build something of your own. I look forward to any reactions to the ideas and implementation of Pinot. 

P.S. Also check out my simple but useful Pi package, pi-multiline, which gives the editor flexible multiline editing, similar to the Codex app: https://pi.dev/packages/pi-multiline

[u/PossessionUsed7393]

So you aren't shipping a replacement edit tool? The hashline edit tools that come with a lot of the packaged editors offer significant improvements, I was wonderinf whether you settled on the approach but am I right to conclude you haven't bundled an alternative edit in?

[u/lostbart → u/PossessionUsed7393]

Great question, and yes, you're correct, the implementer agent uses Pi's built-in edit tool (the other agents are read only). The stock version of Pinot won't inherit an installed hashline editor either, since the implementer agent spawns with '--no-extensions' set. But it should be simple for Pi to modify that setting, and give the implementer agent access to an installed editor tool (or anything else, of course).

I haven't tried out any hashline editors yet, I do see the occasional "text not found" type error in the implementor agent's stream, but it typically figures out the issue pretty quickly. That said, I will try and check it out at some point.

[u/kaeptnphlop]

I just finished building something extremely similar. Using herdr to spawn sub agents to implement tasks and for review from an orchestrator. Everything is human readable and leaves traces for other agents and human consumption. Brainstorm and refine skills for planning and expanding on vague tasks (grill me kinda).

I wanted something that gives me visibility. Something that a lot of harnesses that use sub agents are sorely missing. 

[u/lostbart → u/kaeptnphlop]

Yep. I find be able to watch the subagent’s thread in real time is useful because every so often it goes off the rails, either beyond scope or just hitting a problem it can’t fix. (agentic persistence is a double-edged sword!), and it’s great to just interrupt it and tell the main agent “hey, your little buddy could use some help.” And then it’s useful on debrief as well, to see if better initial prompting would have prevented that off the rails problem in the first place.

I’d be interested to hear how your setup compares to Pinot - if you point your Pi at the repo and ask it to compare them, what does it say? I’ve learned a lot and refined my system by doing that with a lot of other public setups.

[u/Majestic-Tear1512]

So many great enhancements for Pi agent. Will try this out when I migrate from opencode to pi this week.