PenguPool

Build an agent team. Actually manage it.

Claude Code and pi agents as a team you run from VS Code. Talk to the lead: it routes each part to the agent that owns it, and the map shows who is messaging whom.

curl -fsSL https://pengupool.nduwork.com/install.sh | bash
1

    Your first team:

    1. Add the agents. Press n for each one and pick its repo: the folder itself, or a new worktree.
    2. Put a lead over them. Drag each agent onto the lead, then tell the lead what each one owns.
    3. Talk to the lead. It routes each part to the agent that owns it. Watch it happen on the map and in the Log.
    THE PLUGINS

    One backend, three ways in.

    Each harness gets its own wiring. They all read the same local model under ~/.pengupool/, and one tag ships a matching backend and extension.

    ▣

    VS Code extension

    • Sessions and pi Sessions trees; drag a row or a map card to regroup, right-click a session to add a child
    • Live map: lines light green when a parent messages a child and milky blue on the reply; ungrouped sessions stack in their own column
    • Top-down or left-right layout, compact or roomy spacing, and ⟳ Refresh
    • Message log coloured by edge: parent → child, child → parent, @session
    • One tmux-backed terminal per harness that switches sessions in place
    • Shift+R Restart & Resume after a Claude Code or pi update
    ⚓

    Claude Code hooks

    • A <pengupool> block each prompt: tree, parent, children, role
    • SendMessage guard: parent and direct children only
    • ROUTE CHECK when a prompt matches a child's keywords: a hint, never a blocked turn
    • ROLE REQUIRED until the session describes itself
    π

    pi extension

    • The same tree block, appended to pi's system prompt
    • pi-intercom send/ask checked against the routing rule
    • Workflow chain in pi's footer and prompt
    • Its own tmux server; never grouped with Claude Code sessions
    RUNNING A TEAM

    Brief the team, then let it route.

    PenguPool enforces who may message whom, but the agents only know what you tell them. These habits keep work flowing to the agent that owns it.

    1

    Tell the parent about every new child

    After you add and group a session, tell its parent it exists and how you plan to use it. Then give the child its job.

    I added api under you. It owns the REST endpoints in server/. Route API work to it and keep planning and review yourself.
    2

    Check each role, edit when needed

    Roles are automatic: a new session is told ROLE REQUIRED until it describes itself, routing keywords included. Hover a row to review it. Right-click → Describe Role… to edit the summary and brief, or set keywords yourself.

    pengupool ctl describe <id> --keywords "api, endpoint, auth"
    3

    Talk to the top, let triage route

    Prompt the root session and read the Triage: line that starts each reply. To keep one task local, say so.

    Fix the login copy typo. Do it yourself.
    4

    Use @session for a one-off direct line

    Tagging a session lets the one you typed into message it directly until your next prompt, without regrouping anything.

    @payments will token refresh log users out of checkout?
    5

    Pick folder or worktree on purpose

    Use the same folder for reviewers, readers or a second pair of hands, even when a session already runs there. Use a worktree when two sessions edit the same files.

    6

    Keep the tree intact

    Compact with c or /compact. For a fresh context, Shift+C or /clear keeps a Claude Code session's group and role; pi's /new still leaves the group. After a Claude Code or pi update, press Shift+R to restart in place.

    Read the full guide →
    OBSERVABILITY

    See the whole team at work.

    Every agent keeps running in its own session. PenguPool shows who owns what, who is messaging whom, and who is waiting on you.

    ⌘

    Switch without starting over

    Open live tmux sessions from any editor window. Close the editor and come back to the same work.

    ⑂

    Route work, not guesses

    Arrange the team as a tree. Messages go only one edge at a time, and tagging @payments in a prompt opens a direct line until your next one.

    ◎

    Give each agent room

    Start an agent in the same folder as others or in its own git worktree, give it a role and routing keywords, and follow its current phase on the map.