pi-huddle

pi install @ssweens/pi-huddle

Huddle mode for pi. Safe exploration with permission gates, plus a powerful gather_input tool for structured multi-question elicitation. Toggle with /huddle, /holup, /plan, or Ctrl+H.

Features

• Huddle mode — read-only by default; writes require your approval
• gather_input tool — rich TUI dialog for structured elicitation (available in all modes)
• session_query tool — targeted lookup into prior .jsonl sessions without loading full history
• Permission gates — approve or deny individual edit/write operations inline
• Bash allowlist — safe commands execute freely, destructive ones prompt first
• Three commands — /huddle (primary), /holup, /plan all toggle the mode
• Ctrl+H shortcut
• CLI flag — pi --plan to start in huddle mode
• Session persistence — huddle state survives session resume

Installation

pi install /path/to/pi-huddle

# Or project-local
pi install -l /path/to/pi-huddle

Usage

Toggle Huddle Mode

/huddle              # primary command
/holup               # alias
/plan                # alias (backward compat)
Ctrl+H               # keyboard shortcut

Start in Huddle Mode

pi --huddle          # start pi directly in huddle mode
pi --plan            # alias (backward compat)

Workflow

1. Enter huddle mode — /huddle or Ctrl+H
2. Use gather_input — gather requirements and clarify before acting
3. Explore safely — read, search, and analyze freely
4. Approve edits on demand — each write operation requires approval
5. Exit when ready — toggle off to restore full access

---

gather_input Tool

The gather_input tool is available in all modes — not just huddle. It presents a rich TUI dialog with one tab per question, numbered options, freeform text input, and a submit/review view.

Dialog UX

← □ Auth method  □ Library  ✓ Submit →

Which auth approach should I use?

  1. JWT tokens
     Stateless, scales well, standard choice.
  2. Session cookies
     Simpler for server-rendered apps.
  3. OAuth2 / OIDC
     Best for third-party login integration.
  4. API keys
     Simplest for machine-to-machine auth.
  5. |ype something.      ← freeform field, type immediately
  ────────────────────────────────────────
  6. Chat about this

Enter to select · Tab/↑↓ to navigate · Esc to cancel

• Tab bar — ←/→ or Tab/Shift+Tab to navigate between questions and Submit
• Options — ↑/↓ to move, Enter to select
• Freeform — navigate to row 5, start typing immediately; Enter to confirm
• Chat about this — tells the agent the user wants to discuss before deciding
• Submit view — recap of all answers before final submission
• multiSelect: true — Space or Enter to toggle, multiple selections allowed

Tool Call Example

{
  "questions": [
    {
      "question": "Which auth approach should I use?",
      "header": "Auth method",
      "options": [
        {
          "label": "JWT tokens (Recommended)",
          "description": "Stateless, scales well, standard choice",
          "markdown": "Authorization: Bearer <token>"
        },
        {
          "label": "Session cookies",
          "description": "Simpler for server-rendered apps"
        },
        {
          "label": "OAuth2 / OIDC",
          "description": "Best for third-party login integration"
        }
      ],
      "multiSelect": false
    },
    {
      "question": "Which features do you want to enable?",
      "header": "Features",
      "options": [
        { "label": "Logging", "description": "Structured JSON logs" },
        { "label": "Metrics", "description": "Prometheus /metrics endpoint" },
        { "label": "Tracing", "description": "OpenTelemetry spans" },
        { "label": "Alerts", "description": "PagerDuty integration" }
      ],
      "multiSelect": true
    }
  ]
}

Return Value

{
  "answers": {
    "Which auth approach should I use?": "JWT tokens (Recommended)",
    "Which features do you want to enable?": "Logging, Tracing"
  },
  "annotations": {},
  "metadata": {}
}

Usage Notes

• 1–4 questions per call
• 2–4 options per question
• markdown field shows a code preview when an option is focused
• multiSelect: true for feature flags, configuration choices, etc.
• Put "(Recommended)" at end of preferred option label
• If user selects "Chat about this", agent should respond conversationally

---

Permission Gates

✅ Always Allowed

Tool	Description
read	Read file contents
bash	Allowlisted safe commands
grep	Search within files
find	Find files
ls	List directories
gather_input	Structured elicitation

⚠️ Requires Permission

• edit — file modifications
• write — file creation/overwriting
• Non-allowlisted bash commands

Permission Dialog

⚠ Huddle Mode — edit: /path/to/file.ts
[Allow]  [Deny]  [Deny with feedback]

Deny with feedback sends the reason to the agent so it can adjust.

Safe Bash Commands (No Prompt)

cat, head, tail, grep, find, rg, fd, fzf, bat, ls, pwd, tree, git status, git log, git diff, git branch, npm list, curl, jq

Prior Session Research Workflow

Use this two-step approach when you need historical context:

1. Find candidate sessions (safe bash):
   • fd session.jsonl ~/.pi/agent/sessions
   • rg -n "<keyword|error|path>" ~/.pi/agent/sessions
   • Optional narrowing with fzf; inspect with bat, head, tail
2. Query surgically with session_query(sessionPath, question)

This keeps context small and avoids dumping huge session files into the prompt.

Benign output redirections like 2>/dev/null and 2>&1 are also allowed.

Blocked Bash Commands (Prompt Required)

rm, mv, cp, mkdir, touch, git add, git commit, git push, npm install, yarn add, pip install, sudo, >, >>

---

Architecture

pi-huddle/
├── package.json          # Package manifest
├── extensions/
│   ├── index.ts          # Commands, shortcuts, gather_input tool, permission gates
│   ├── session-query.ts  # session_query tool for querying prior sessions
│   └── lib/
│       ├── gather-input-dialog.ts  # TUI dialog component
│       └── utils.ts            # Bash command classification
├── skills/
│   ├── huddle/
│   │   └── SKILL.md      # Teaches the agent huddle mode behaviour
│   └── pi-session-query/
│       └── SKILL.md      # Teaches when/how to use session_query
├── LICENSE
└── README.md

Two pi primitives:

• Extension — registers /huddle, /holup, /plan commands, Ctrl+H shortcut, gather_input + session_query tools, permission gates, and context injection
• Skills — document huddle behavior and prior-session querying patterns so the agent uses them correctly

Development

/reload    # Hot-reload after editing
/huddle    # Test huddle mode

License

MIT