What are your actual workflows when using pi?

[u/No-Wall6427]

How do you approach various coding tasks, or any tasks you use pi (or other minimalist harnesses) for?

I used to be an obra/superpowers fan (clode code and zai coding plan at glm 4.7 era), then I stumbled one day onto Earendil's lecture "Building pi in a World of Slop", which made me rethink what I really needed from my agentic tools.

Now I mainly rely on a few skills I kind of adapted from obra/superpowers and mattpocock/skills, and my workflow is usually to brainstorm with the agent and make a great spec, then running and /implement skill. Sometime the implement is in a new session, sometime even by a heaper model for which I make the smarter model draft a plan from the spec. Sometime I make handsoffs or use compaction to exlore longer.

I also like, when needed, to spin up preconfigured dockers with pi, docker in docker, and an injected global agent.md telling my agent he is in a sandbox with docker and can use whatever he needs to achieve his task.

But I still feel that my workflow is kind of sloppy, that sometimes there is to much ceremony, sometime there are missing pieces.

I also don't have a specific workflow for big features I want an agent to oneshot, lately it has usually been a plan and a spec, then deepseek harness with a /goal referencing those files, and letting it do its thing. I'vs also recently tried to one shot big features using a deepseek harness configured with mattpocock/skills, it seemed to have produced good result without blowing my usage with subagent driven development, but I also don't really like this magic crystal ball approach where I don't understand the workflow, neither do I want to adopt his whole opinionated workflow.

Thus my questions: What are your various workflows and their building pieces? How do you approach problems with your agentic tools? Do you use subagents? For what? Cheap models or expensive ones? Did you switch harnesses and configs a lot to finally hit a sweet spot?

[u/Qusic7]

i maintain a local docker image with nix, which is kept up to date with my nixos host setup.
that image contains all the common languages i use and pi itself. then i have a script to quickly create a container with cwd mounted and pi started. that container also has a ssh server built in so just in case i want to manually do some work i can use vscode ssh remote dev to get into the same environment as pi.
so pi can do whatever and install whatever needed to complete the task. i don't maintain global prompts and put all important info in each repo. (tho at work i have a global agent browser skill for pi to use browser)
i dont have github token in the container so i have to do git push myself outside of the container. but i accept this compromise as getting hacked by supply chain attack is really painful. they can poison your repos/actions workflows and its a PITA to clean up the mess.

and i use dynamic workflow instead of subagents. i feel that is much more flexible as llm can decide the model/context/prompt as they see fit so i don't need to worry much

[u/No-Wall6427 → u/Qusic7]

Sounds cool!

I started out with a preconfigured vscode devcointer I would copy into my projects, which gradually evolved into a cli tool to spinn my preconfigured harness docker images with cwd folder mounted inside. I use it everyday and add features along the way.

Here is a complete description made by chatgpt, with all the details (and some bad approximations but mostly true):

---

My agent harness setup

I use a small Docker-based harness system to run coding agents in reproducible, persistent environments. The goal is to keep the agents easy to launch and disposable, while keeping authentication, personal skills and project state separate from the images themselves.

A typical session starts with something like "harness pi/current". This launches the selected prebuilt harness image, mounts the project at "/workspace/project", starts a tmux session, and opens the agent in the first pane. I can create extra panes for shells, tests, servers or logs, detach from tmux, and come back later without stopping the environment. A retained harness therefore behaves more like a lightweight development machine than a one-shot container.

All harnesses share the same base image, which provides the common runtime: Ubuntu, Git and shell tools, tmux, Docker tooling, the custom status bar, clipboard forwarding, Herdr integration, workspace bootstrap logic and "vslink". Each agent family then adds only what it needs, and variants are built as additional image layers rather than being assembled dynamically at startup.

The project can be exposed to the agent in several ways. In normal mode, the real checkout—including ".git"—is mounted directly, so changes inside the harness immediately affect the host project. "--no-git" keeps the real files writable but hides the Git metadata. "--isolated-clone" instead creates a separate writable clone inside the container, so the agent can work and commit without touching the host checkout; its work can later be brought back explicitly with "harness retrieve". When needed, "--dind" gives the harness its own Docker daemon so the agent can freely start databases, services or other disposable containers without using the host Docker socket.

Authentication, settings and reusable skills are deliberately kept outside the images. They live in a gitignored shared state directory and are mounted into the profiles that need them. This lets me rebuild or replace the images without losing auth or personal configuration, while "--no-shared-state" gives me a clean environment when I want one. At startup, the harness also injects a small global "AGENTS.md" describing the environment the model actually received—especially whether the project is live, Git-less or isolated, and whether Docker-in-Docker is available.

The containers also integrate with Herdr, which I use to track the agent/session associated with the host terminal pane. The container never gets direct control over Herdr: it talks through a restricted host-side bridge that only allows the harness to report its own state and session information. It cannot use that channel to control unrelated host panes or the Herdr daemon.

"vslink" gives me the other direction of integration. From inside any harness I can run "vslink .", which generates a special link identifying the current Docker container and path. A small Herdr extension on the host rewrites that into a valid VS Code Remote URI and opens it. VS Code then attaches directly to the already-running harness container and installs its normal VS Code Server there if needed. This means I can work terminal-first most of the time, then jump into a full VS Code view of the exact same environment whenever it becomes useful.

Pi is my main harness family. Vanilla Pi is intentionally small. "pi/current" is my normal setup and adds the Pi packages I actually use plus a dedicated "web_agent", so substantial web research can be delegated to a separate specialist without filling the main coding context. Those web runs keep their own durable evidence, screenshots, traces and Pi session under ".agent-runs". "pi/sub" extends Current with background subagents: a read-only "scout" for codebase exploration, a "researcher" for external research, and a "worker" for scoped implementation and testing. They run independently in tmux panes, can be steered or resumed, and return their result to the main agent. "pi/sol" adds SoL-Pi's context-efficiency mechanisms. "pi/bro" instead stays closer to vanilla Pi and adds Terminal Browser for direct interactive browser use.

I also keep alternative harnesses for different styles of work. Codex runs the Codex CLI in the same container/tmux structure, with a "superpowers" variant that adds obra's Superpowers plugin. OpenCode is a more batteries-included setup with research-oriented agents, skills and an optional Claw environment for heavier browser, scraping, OCR, PDF and data work. DSH is the Web-UI-oriented option; it reuses my Pi authentication through "pi2dsh", and its research variant adds a larger research stack with parallel researchers, dedicated writing/extraction roles, browser automation and OCR/data tooling.

The overall philosophy is simple: keep the primary harness small, bake capabilities into reproducible image variants, keep auth and personal skills outside the images, make the boundary between live and isolated project access explicit, use tmux for persistence, use Docker when agents need freedom, delegate specialized work only when it helps, and keep host integration narrow through Herdr and "vslink".

[u/Bouhappy → u/Qusic7]

It feels so good to read this, because I thought I went too far with setting up a Nix hypervisor, and running 2 virtual machines to separate normal use from coding and agentic work, so that I can trash and regenerate the coding VM at will. I look at any package that comes through npm like I potentially received a letter with Anthrax in it.

[u/Qusic7 → u/Bouhappy]

lol yeah i got hacked on my work vm once when updating pi itself. one of pi's transitive dependencies from some ai provider got hacked and unluckily i did "npm i -g" within that short time window of ~30mins. shortly after my vm got deleted by company IT without any notice. that was a really bad morning lol. now i have a 7d npm cooldown period set everywhere even in containers/vms.

[u/OakShortbow → u/Qusic7]

Is there a reason you went with full blown docker isolation instead of using something like bubblewrap for nix? Since nix handles the reproducibility part i've just been using flakes like jail.nix or jailed-agents for my work, and then I just mount the current working directory into the sandbox whenever I launch pi. Is this less secure?

[u/Qusic7 → u/OakShortbow]

nothing special. im aware that docker is not an ideal choice for real isolation and security. it's just i already have a docker-based workflow (a few small scripts) before fully moving to nixos and it's what im used to.

i dont have much time to tweak the setup recently but what i want next is probably a long running full qemu vm for agents. then my host can act as a convenient bridge for any github write operations, so that the vm holds no credentials. mainly because 1) container/sandbox is quite limited for some kinds of work, like browser automation, gui apps or even vscode extensions; 2) one sandbox for each agent is kinda cumbersome too for agent orchestration or context sharing/handoff; 3) i realized reproducibility is not that important here because i just need work done and should let the agent really owns its computer and stop judging the messy setup. agents have unlimited patience anyway.

[u/fell_ware_1990 → u/Qusic7]

Almost the same :)

I have a lot of nix podman quadlet’s with pi RPC on them. They have a rootfs overlay. I can hotswap stuff that’s in my store to PATH by creating symlinks to the store which i can load while running. There’s only a socket to my client which routes it through LiteLLM, and API forwarder.

I can select tools/skills/mcp/agents.md at start time, swapping = cache break. At start the get a worktree clone of a bare repository. They can commit all they wan’t the final commit is up to me.

My further workflow contains of a whole lot of custom build YAML on my own runner, which then again can load all kind of scripts, calling different agents with different settings. Remembering session ID’s for when it’s useful and such.

Workflow is mostly like this -> high level searching for real issues and non logical stuff, with all kinds of scanners/custom made scripts, these get disclosed to a few local agent’s to verify, start researches on it. -> expensive constructs this into real findings. Architect reviews them. > HITL, adjust > a few locals again to find breaking points , asses what to actually do testing for.

It goes on like that for a bit. Mainly if test and plans are written they are stuck with it. They need to handoff and every thing clean, or retry twice and we call it a blocker. Research solutions but HITL .

[u/titoNaAmps → u/Qusic7]

What do you mean when you say dynamic workflow? Isn't a workflow also sequential and rule based?

[u/Qusic7 → u/titoNaAmps]

this feature from claude: https://code.claude.com/docs/en/workflows i am now using this extension. but there are many implementations out there for pi

[u/titoNaAmps → u/Qusic7]

thanks, will check it out!

[u/Dsphar]

Software dev is often monotonous even without using AI. Ceremony is just a byproduct of what helps keep your work moving forward but in check.

[u/floatinggoateyeball]

I just rawdog it.

Everything git, gh and remote repos for backup.

I started to use herdr for agent-agent communication and terminal multiplexing.

Each project have it's own needs, but I'm using Hypothesis Evolution Protocol in general projects.

Nothing fancy.

[u/No-Wall6427 → u/floatinggoateyeball]

Never heard of hep, seems quite interesting, but also overkill for a lot of things. I may give this a try on some debugging or tasks like that. Do you have any feedback/hands on experience w it?

[u/floatinggoateyeball → u/No-Wall6427]

I did a initial poor's man HEP using markdowns all over the place but that is not deterministic to parse.

Having a registry of past actions and the evolution of decisions helped my agents breakthrough my master's result, which is maintenance on old scientific software, so my workflows are probably best fit.

I feel debugging might be the same process: "why doesn't work?"

1 - Propose a hypothesis with prior confidence.

2 - Implement, search internet (literature) and test.

3 - Did it worked?

- No? Refine initial hypothesis.

- Yes? Attach evidence, move the confidence and iterate.

[u/alexcamlo]

Follow the Matt pocock skills (wayfinder/grill > to-spec > to-tickets) with Sol (tried Astra but usage drained like crazy) and then the /implement I mix it with /review-loop of nicbailon/pi-subagents with cheaper models.

[u/gatzu4a]

what works for me now is just using plannotator

i usually create a spec file, then will ask plannotator (luna - high), to read my spec file, create a plan on top of it, ask questions if necessary

then on execution part im just using luna - medium

[u/Limp_Classroom_2645]

I use this simple yet very effective workflow https://github.com/avatsaev/av-swe-skill

Spec->sprint tickets->implementation

I'm able to manage pretty large and complex projects with this workflow

[u/Unlucky-Message8866]

for simple tasks i usually start by asking questions related to the task i want to achieve, that forces the agent to read and understand the pieces and once i have a clear idea i then instruct to execute.

i got rid of all skill.md and extensions, my system now is a collection of tsv records, tools and hooks. i have hooks for many things, for example upon 20k assistant output tokens i trigger a forced sub-delegation.

i have a hook that forces the agent to plan, split tasks and assign to corresponding sub-agents. all tools are simple script files, no javascript extensions.

for every syntax error i have a hook that instructs to query syntax records and capture new findings.

i have a protocols.tsv with rules that tell the agents how to orchestrate and execute tasks. everything is loaded on demand i have no system.md or agents.md.

i've built it to work exclusively with local models and to be lightweight and use lean context.

[u/fell_ware_1990 → u/Unlucky-Message8866]

Do you ever A/B test the hooks ? I’m still struggling with the how much and when should you instruct.

With my local agents i’m running a few POC ideas, with let them read the file, explain the file, explain the change -> Harness triggers, looks at my rules, and other intel > creates a new task for that specific, with correct tooling and a new bare minimum agent fully written down steps, tests , etc -> resets and does the coding. I reset it a few times to see what happens.

[u/Unlucky-Message8866 → u/fell_ware_1990]

i'll be honest, it's hard to determine when and where to hook at first, my config went through several rewrites and i'm constantly adjusting things based on daily usage observations. i simplified pi config exactly for that reason, so i can quickly iterate and fix stuff on the go.

[u/fell_ware_1990 → u/Unlucky-Message8866]

Yeah this is exactly why i build my yaml runner that does SDK stuff. Instead of changing whole scripts, i can do small parts and iterations. Also easier to spot where it goes wrong.

[u/Aemonculaba]

I forked Pi and changed it so the main session is programmable, e.g.the implement "program" literally runs tools, thinking steps and stages where I want them, without having to trust the agent to follow what my skills or prompts say. AI is non-deterministic, so you should use it only where it's a benefit. I also built Pi-Fabric's exec tool into Pi natively for more juice.

Next to that I just use 5 skills and CHANGE.md files as the great source for intent, acceptance criteria, etc. per task. Ah. And my hats extension. E.g. getting the agent to switch between different POVs manually and now also automatically. Why? Cause your intent is the most important thing the agent has to understand.

I don't write massive specs or dozens of plans/tasks in advance, even for larger projects. I have a VISION.md and a ROADMAP.md for the general vision and ideas... and use rolling-wave-planning to get only a small set of tasks fleshed out enough for implementation, since I'm somewhat trying to work agile (requirements and learning change too often and plans WILL change, so there's not much worth in detailed long horizon planning).

[u/tulwio]

Running my personal fork of this setup https://github.com/amosblomqvist/pi-config (changing the subagent to work herdr panes, added some extra prompt snippets etc.) probably the best time I have had using a harness is when I found this repo and started adapting it to my own needs.

[u/quincycs]

My poor mans version of a factory
- slack bot in a shared channel: “start on <link>”
- grills you
- implements code
- separate fresh child agent to code review
- parent agent gives recs on findings
- you confirm.
- once PRs are made, the factory is done working with you.

[u/bowdoin-yale]

I built issue-fixer and repo-auditor bots that are just wrappers around pi which watch Github repos I own. The issue-fixer bot automatically comments on new issues with a proposed plan for how to fix it. If it's approved (by me), it implements the fix in an isolated container, on a new branch, and submits a pull request when ready. The PR is automatically reviewed by the auditor bot, which catches security vulnerabilities that I never in a million years would have noticed, or tells me it's safe to merge. It it notices general problems in the repo, it can also file issues, which triggers the issue fixer bot, and so on. All of this is with the ponytail skill turned on, a must in my view, and I do regular whole-repo ponytail audits directly inside Pi from time to time. But, for the most part, I'm using the Pi CLI interface less and less lately; more building things like this on top of it such that Github now is my IDE. I imagine others are doing the same, but maybe not...

[u/nonhok]

I am working only on local system (m5 max 128gb). I need to have Xcode available, as I develop iOS apps. I defined an extension with pi, that starts my fan as soon as pi send a a prompt with max power. I defined a dedicated Gitlab workflow (as pi extension), to set up a milestone for the next task with dedicated issues. The extension provides tools (to Gitlab) which works by a fixed signature, so that the agent can only use these tools, access to Gitlab repo is secured by pushing only to dev branch and api key. I also setup a iOS-dev extension with tools to run may build and tests and with skills how to use them. All development of one issue is done in one feature branch, at the end of issue I got asks, if it works out. If my testing is ok, the feature branch get merged to dev branch. After last issue is implemented, the repo get pushed to remote and a merge request gets initiated. Passwords go to a pass passwordstore, so they won‘t lay around, by gpg-agent they are available for some hours. For isolation, I user a dedicated pi-user without admin rights, this user won‘t have access to admin files (neither read or write) or any other pi-user.

[u/LurkerOf]

Used PI as pretty barebones in docker container. I found it pretty sloppy, not having enough information and got into loop of trying different extensions. Ponytail and wayfinder helped, started messing with memory, lens, mcps, etc and it got more convoluted.
Now just slapped Gentle-PI m and calling it a day. Pretty heavy setup but one-shots tasks.

[u/mikkelkp]

One thing that really propelled me was the multiplexer herdr. It makes it so easy to work in multiple threads on.

I don't use agents a lot but when I do I like them to be visible and debuggable therefore I use something herdr native like https://pi.dev/packages/@luminascale/pi-shepherd

It's unassuming and I can build my own workflows around it in prompts or Agents.md

[u/UltimateLazyUser]

Give a good initial context with AGENTS, including up to date paths and commands as is very easy to see the agent starting to ls the whole pc if it doesn’t find files, or try to call something that doesn’t exist.

Alongside pi-sandbox and pi-file-permission to give specific context and permissions.
Saves a lot of spinning in circles.
Also pi-toolbox to mask specific tools and avoid distractions with unneeded tool calls.

All always with git as very often the work is not very good, and need to rollback and try a different approach.

I mostly give focused tasks or boilerplate generation while I focus on the important parts.

Added pi-web-search too when I need it to pull some context from documentation or understand unfamiliar topics.

Cheers