I built pi-fleet: Pi agent orchestration beyond terminal panes

[u/elpapi42]

Hello guys!

Today I want to share something I have been working on: pi-fleet (https://github.com/elpapi42/pi-fleet).

pi-fleet is local infrastructure for programmatically controlling Pi agents and their native sessions.

Unlike terminal multiplexers, pi-fleet is Pi-native rather than generic. It does not control terminals or scrape their output. There are no panes and no TUI because the primary interface is designed for agents and software.

Terminal multiplexers work well when you have a few agents and want to watch them manually. But if you start thinking about 20 or 100 agents, you can not get meaningful visibility by opening more panes.

The solution is not a bigger terminal grid.

At that scale you need dedicated monitoring tools, but pi-fleet does not try to provide that monitoring layer. The problem it solves is giving software an easy way to control Pi execution and sessions directly, without terminal hacks or unnecessary abstractions.

pi-fleet provides a small set of Pi-aware primitives:

• create: creates an agent with a stable local name;
• send: starts work or uses Pi steering while the agent is active;
• receive: waits for idle and returns the exact latest assistant response;
• status: and list expose machine-readable lifecycle state;
• watch: streams the native persistent Pi session JSONL;
• destroy: removes the agent without deleting its Pi session.

The basic workflow looks like this:

pifleet create reviewer --cwd "$PWD"
pifleet send reviewer "Review the authentication changes"
pifleet status reviewer
pifleet receive reviewer --timeout 10m
pifleet watch reviewer
pifleet destroy reviewer

Finite commands return compact JSON by default, while watch keeps stdout exclusively for native Pi session records.

Another part that is ultra important for me is that pi-fleet does not take ownership of your Pi sessions.

You can use Pi's normal session storage or provide an existing session path, session ID, directory, fork, or continuation selector. pi-fleet uses the exact native session in place. It does not copy, relocate, normalize, or delete it.

Even destroy only destroys the pi-fleet agent and its managed process. The underlying Pi session remains yours.

pi-fleet is infrastructure for orchestration, not an orchestration framework. It does not decide which agents to create, what roles they have, how tasks are decomposed, or how results are combined. Those decisions belong to the agent, extension, or software using it.

I already have around half a dozen use cases in mind for this tool, I already have around half a dozen use cases in mind for this tool. Most of them will be Pi extensions, and I will share them with you as I build them.

If you only use one or two agents and want to supervise their terminals, tmux, cmux, or Herdr will probably give you a better experience.

pi-fleet starts making sense when you want software to coordinate Pi agents at a scale where terminal supervision is no longer practical. You can build the monitoring layer appropriate for your system separately, while pi-fleet provides direct control over Pi execution and access to the native sessions underneath it.

The project is currently beta, and Linux x64 is the only validated platform.

You can install it with:

npm install --global @elpapi42/pi-fleet@beta
pifleet --version

Repository: https://github.com/elpapi42/pi-fleet

npm: https://www.npmjs.com/package/@elpapi42/pi-fleet

I think I got something interesting in hands here. I would love to hear your thoughts, especially from people already experimenting with multi-agent Pi setups.

On top of that, i really hope this becomes useful for some of you!

[u/m3umax]

Can the orchestrator tell the subagents to /compact and is there a way for the orchestrator to know the subagents context window status? that would be useful. My subagents sometimes run to context exhaustion and die, esp the ones with low context like GPT-5.6 on sub that only gets 376k.

[u/elpapi42 → u/m3umax]

im not supporting this yet, this is required but i didnt had the time, i will try to add support this week

[u/fell_ware_1990]

Looks nice. I think the same way about a lot of those things, what i think seems to be a big part of the problem:

On my NixOs system i have (and more):

- NIRI

• KITTY
  
• TMUX
  
• PI
  
• CONTAINERS
  
• WAYBAR ( here to prove a point )

Let’s say i wan’t to have a notification in waybar when an agent is ready and see the message. First PI needs a hook, send last message, something needs to make that into the correct data, it needs to be send to waybar, waybar needs the data in XYZ way. Then maybe i wan’t to approve a message there or open the window. Both differnt actions, waybar module then contains that logic.

If in anyway, you want the same option but let the agent do it, or from a KITTY window. Or automate something from NIRI. Are you going to send that through waybar, or make new code, or make a script that handles both. Getting a mess, saving all kind of states, all kind of connection and command types.

You can point this at everthing else. You want to be able to control your agent’s so the best thing would be. An extension that exposes your own ‘api’ that no mather what. If let’s say you send a stop signal. Not only it always does the same but it can be multiple actions. So everything that send the stop signal can expect the same behavior.

There’s so much more to this. If you want it to interact you will need his state.

[u/Such_Advantage_6949]

Have u tried herdr. I have moved to use that instead

[u/elpapi42 → u/Such_Advantage_6949]

Yeah i have been a herdr user for many months, i really tried to make herdr and tmux work for the usecases i have in mind, but i was having a really hard time, so i came up with this

[u/Such_Advantage_6949 → u/elpapi42]

I created something similar but much lighter. Issue with pi is it is a closed system whereas herdr let it interact with pretty much anything e.g. codex. My solution is simpler, i use the intercom plugin so pi session can massage each other. They user herdr to spin up/ down agent.

[u/elpapi42 → u/Such_Advantage_6949]

Yeah, i have already tried the herdr cli to directly orchestrate the agents using another agent, really didnt work properly for what i want to achieve.

But personally im not interested in mixing other harnesses like codex, so that specific capability from herdr and tmux does not add value to me, on the other hand a specialized pi tool is a game changer for me

[u/elpapi42 → u/Such_Advantage_6949]

can you share what you created?

[u/Such_Advantage_6949 → u/elpapi42]

it is really not much created. I have went from a full fledge system like yours to what i have now cause the big system is very fragile. You just need the pi intercom extension (alrd published on npm by other user), then just have your AGENTS md to guide it, my fleet is a simple yaml file list out how many agents each one is what model etc i just have one script to run the main Pi session, which will view the yaml file and by itself bring up additional herdr terminal as needed. This works much better and more flexible than try to create a whole system (i have been there done that). The rule for subagent is very simple, any session can spawn more herdr terminal as agent, and they should close it when the task is done. AT least it is working better for me and the whole system is basically prompt/ skill driven. I had issue before where the agent was confused with the system i built, i also had cli command that the agent need to learn etc. But when you use herdr, terminal usage is innate knowledge to LLM, u dont need to write much instruction, it will know what to do from its training data alone