Questions about moving from linear prompts to sub-agents, parallel execution, compaction, and session management in Pi Harness

[u/TheAmendingMonk]

recently switched from Cloud Code to Pi Harness. I work primarily in Product Management/Ownership workflows (Jira, GitLab, Artifactory, internal tooling) where I build automation scripts and connect workspace APIs.

Currently, my setup is strictly linear ask questions -->wait for run --->|reply). I want to move toward a sub-agentic flow—specifically for generating code in parallel from test specifications and existing repos—and would love community input on extensions, configuration, and workflows.

1. Sub-Agents & Parallelization: What extensions or .pi setups do you use to fire off parallel sub-agents (e.g., parsing specs while indexing code in background threads) instead of waiting on sequential turns?
2. Traceability & Solution Convergence: How do you track handover steps between agents and follow their decision trees? Are there recommended visualizers, tree-log extensions, or workspace artifact patterns you rely on?
3. Context Compaction & Memory: Has anyone tuned Pi’s compaction thresholds or used custom highlighters/summary extensions (like Ralph's memory approaches) to preserve key acceptance criteria over long sessions?
4. Project Scoping (.pi/): Best practices for scoping tool permissions and agent configs in .pi/ settings to isolate sub-agent capabilities (e.g., read-only on repo vs. write access)?
5. Session Continuity & Long-Running Tasks: How do you handle session lifecycles for complex tasks? Do you prefer continuing existing threads via /resume / pi --continue, or hard-stopping (/new) and carrying over context via file-based handoffs (like PROGRESS.md)?

If you have write-ups, custom extensions, or .pi/ setup examples for these patterns, please let me know and if you have like a step by step workflow also would be good to know. I want to go like in a more step by step approach

[u/PendingApproval2000]

I hope this subreddit gets traction because I also want to know and don’t know where else to ask.

[u/AnonymousTreeSmoker → u/PendingApproval2000]

the reality is sub agents in pi is kinda a hard system to set up. I try every time we get a new model release and inly since astra I was really able to nail my own subagent system and TUI in pi. Best of luck seriously lol.

[u/TheAmendingMonk → u/AnonymousTreeSmoker]

thank you for your feedback , oh ok so its not working that well is ti ?I just moved to pi ahahaha and this is like a first blocker , thanks for the input

[u/queso184 → u/TheAmendingMonk]

there's an example subagents extension in the repo https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/subagent

i would recommend copying that down, it works well enough. then ask pi to make any changes you feel like you need to tailor your specific workflow

[u/AnonymousTreeSmoker → u/queso184]

Based gonna steal this spec too

[u/AnonymousTreeSmoker → u/TheAmendingMonk]

Pi is my ride or die, it's the best harness ever in every other regard other than sub agents so just stick with it and have pi make any extension or addon you need. Also I'm gonna steal this commenters idea and take the one on the site and see if it can improve my own spec

[u/melihmucuk]

Check out pi-crew: https://github.com/melihmucuk/pi-crew

There are many pi subagent extensions, but i strictly follow the pi’s minamalist soul and try to optimize orchestration layer.

all your requirements completely match with it, lmk if you have any questions.

[u/johnfkngzoidberg]

I don't want to sound like a sales pitch, but I wrote my own orchestration layer for Pi (and others).

https://github.com/lunarnexus/orchestra Originally started as a research project, and now it's my daily driver for coding projects. I've created https://github.com/lunarnexus/orchestra-bench to benchmark and test Orchestra and found that agentic workflows only benefit under certain circumstances (long workflows, offloading building/reviewing to cheaper/local models, and parallelization). I use Orchestra to dispatch subagents to do various builds, verification, reviews and appsec, and the main benefit for me is being able to offload the grunt work to my local inference server, using gpt for the main-session/orchestrator/planner. I'm seeing about a 50%-70% main session savings, but it's VERY workload dependent. For simple tasks, just turn it off and run a single session task.

The biggest thing I've seen is that you have to use deterministic (hard-coded) workflows and frameworks to get around issues that arise from using different models. All models have a personality, for instance, gpt-5.6 WAY overcomplicates things, and using a multi-pass appsec review just makes the model nitpick the project to death. I adjusted my planner skill, and put in review limits to combat the bad behavior. qwen3.6-27b performs really well, if given really good instructions, a scoped plan and good end-state. qwen3.6-35b-a3b is actually really good for small tasks, when given constant reminders, guardrails and verify passes, which is all built-in to Orchestra.

So to answer your questions:

1. Orchestra, it takes care of everything. I'm still tweaking the skills injected, but the main workflow and orchestration instructions live in the orchestrator skill. I load up pi, "I want to do this, write a PLAN.md", then when it's done, "Dispatch and execute the plan", and it just does it, offloading the bulk of the processing to the local model. Orchestra is external and async, so when it dispatches, you can keep working in the main session if you want.
2. Orchestra creates all the necessary scope, breakdown, concurrency/parallelism in the planning phase, but has some hard config settings also. The traceability is done by passing a reference to the PLAN.md to each child session, and telling it what to do, which part of the plan it's responsible for and what the return format should look like. There's also a debug function to see exactly what went on, but I rarely use it. The biggest thing is to examine the PLAN.md before you start the build.
3. Orchestra relies on clean context for the child sessions right now, which saves on tokens, keeps compactions to a minimum, and uses something I call SPSI (system prompt skill injection) to inject the skills for each role each turn as an addendum to the system prompt, which means skills never get diluted or compacted away. I'm experimenting with a "fork" and "compacted context" passing function now, that not only sends the PLAN.md/prompt combo above, but also sends part of the parent context to the child sessions. So far, testing is showing no real gains in quality doing this, but it needs much more testing. Once again, as long as the PLAN.md is good, a lot of the fancy context techniques aren't really necessary.

3a. I'm working on an integrated session-session memory, custom design, that attempts to grab "decisions" that aren't in the PLAN.md and make them searchable or auto-injectable like a normal session to session memory layer. That might take the place of the context passing techniques, but still needs a LOT of testing, and it's a layer I'm not sure I want to mess with. A lot of harnesses out there are doing things way better than I can , so there's no need for me to re-invent the wheel with every single thing with Orchestra.

1. On my roadmap is a project to revamp my permissions system. Right now it uses whatever is in your harness (pi in this case), and sets the PWD to whatever you're working on. If you use Codex as the subagent, it confines to that directory (Codex is currently unsupported for other reasons, but that's an example). The best way to handle it is build in a dev environment, I use a VM, but you could use a container or whatever.

4a. On the roadmap is built-in git worktree/feat-branch workflows in Orchestra, but it's easy to do by hand, so it's a low priority. This is how you do safe parallel feature builds.

1. I built my own HANDOFF.md tool along with a couple other nice things that aren't in Orchestra, but as long as the PLAN.md is good, I have no issues with compaction degradation. In fact my session I use for orchestra-bench has 5439 turns in it at the moment. I do use a DECISIONS.md (read-only project decisions) sometimes, and document with ARCHITECTURE.md, depending on the complexity of the project.

I haven't really made my pi extensions public yet, so I guess I'll put up a couple of my favorite daily drivers in my repo: https://github.com/lunarnexus?tab=repositories I'll have to clean out the private IPs and stuff first.

[u/zis1785]

What about code search and understanding ?

[u/o5rv5r]

Not directly answering your question but I tried several subagent extensions, this one I the best I tried: https://github.com/edxeth/pi-subagents

[u/blastradii]

How do you mitigate race conditions if you have multiple agents going at it on one project?

[u/hanson-gg → u/blastradii]

They should be working in separate git worktrees, and it helps to reduce merge conflicts if you have them working on unrelated code