Pi Interactive Shell plugin
An extension for Pi that runs vim, psql, ssh and other interactive CLIs in an overlay you can watch and take over.
- 608 ★ on the repository
- Last commit
Broad access
Why this level
- The agent runs arbitrary interactive programs and types commands into them: SSH, database shells, git rebase.
- Dispatch and monitor modes run processes in the background without your direct supervision.
Install
Manual install
pi install npm:pi-interactive-shellThe README command. Node.js is required.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent runs arbitrary interactive programs and types commands into them: SSH, database shells, git rebase.
- Dispatch and monitor modes run processes in the background without your direct supervision.
This is third-party code. Review the repository files before installing.
What it does
The extension adds an `interactive_shell` tool to Pi. The agent launches an interactive program in it, such as an editor, a REPL, a database shell, SSH or `docker logs -f`, while you watch in an overlaid terminal window with full PTY emulation and can start typing yourself at any moment. The user does not call the tool directly: you ask Pi to do a task or use the `/spawn` command. There are four modes. In interactive mode the agent gets a `sessionId` and sends input and reads status afterwards. Hands-free polls the session and receives quiet output updates. Dispatch is for delegation: the session starts and reports completion in a new turn while the agent does other work. Monitor wakes the agent only when a configured trigger fires: a stream line, a poll diff or a file change. Structured `spawn` launches Pi, Codex, Claude and Cursor with ready parameters, including in a separate git worktree, and keys under `spawn.commands` add any other agent. The package ships an `interactive-shell` skill that tells the agent when to choose which mode. In dispatch mode, selected output can be enabled so that only failure lines and totals come back from the log.
Who it is for. Users of the Pi coding agent who want the agent to drive editors, REPLs, SSH sessions and long-running processes under their supervision.
Good fit when
- The agent must edit a file in vim or walk an interactive git rebase and you want to see every keystroke.
- A psql or SSH session has to stay open and receive commands as the task goes on.
- A build or dev server runs long and the agent must react to output as it appears.
- A refactor should go to another agent such as Codex, with a message on completion.
- Tests or logs need watching in the background, waking the agent only on a word like "blocked" or "ready".
Not a fit when
- The agent does not run in Pi: the extension is written for the Pi coding agent.
- One non-interactive command is enough: a plain shell call is simpler.
- You need a guaranteed process stop: `kill` cancels only local supervision, and subprocess exit is not confirmed.
Example request
Open psql to the mydb database in hands-free mode, check the row count of the orders table and leave the session open for my input.Limitations
Node.js is required; the PTY uses prebuilt `zigpty` binaries, so no node-gyp toolchain is needed on supported platforms.
Cancelling with `kill` drops local supervision, and the author does not confirm subprocess exit.
Dispatch closes a quiet session automatically after a 15-second startup grace and 8 seconds without output, so long silent processes are better started in another mode.
Selected-output mode relies on an external service; with it off nothing is sent anywhere.
How to disable. Remove the package from Pi with its extension-removal command, or delete the `skills/interactive-shell` link from `~/.pi/agent/skills/`.
FAQ
How do I install Pi Interactive Shell?
Run `pi install npm:pi-interactive-shell`. The package brings the `interactive-shell` skill too. When loading from a local folder, link `skills/interactive-shell` into `~/.pi/agent/skills/` yourself.
How do I take control from the agent?
Start typing in the overlay and control moves to you. In a monitored hands-free or dispatch session, Ctrl+G hands it back to the agent.
How do dispatch and monitor differ?
Dispatch reports when a session finishes; monitor wakes the agent when a trigger fires: a stream line, a poll diff or a file change.
Which agents can spawn launch?
Pi, Codex, Claude and Cursor with ready parameters. Any other is added with a key under `spawn.commands` and becomes available as `spawn: { agent: "aider" }`.
Can I read the output of long sessions afterward?
Yes. For headless dispatch and monitor sessions the log is saved to disk, and a `sessionId` query returns the output tail. Logs older than a day are deleted when the next one is written.
Discussion
No questions or reviews yet.
Related
PluginsA Pi agent package: code search, LSP, web search, desktop control and confirmations for risky commands.
An extension for the Pi coding agent that folds tool calls into compact lines and renders file edits as readable diffs
More than thirty separately installed extensions for the Pi Coding Agent: goals, plan mode, LSP and subscription limits
Armin's personal toolkit for the Pi Coding Agent: 18 skills, extensions, commands and themes, with some skills portable to other agents
pi-kanban runs pi agent sessions in a browser terminal and shows tasks as a kanban board, subagents and the session log alongside.
Native interface for the pi agent in Rust and GPUI: project sessions, a conversation tree, a changes panel and plugins.
README in short
The README explains the motivation: agents need interactive programs while users want to watch. Then install, a table of the four modes, call examples for each, structured spawn, background work, selected output and a pattern for waiting on a terminal line from an external gate.