pi-sidethread

Persistent, context-isolated child threads for the Pi coding agent.

pi-sidethread adds one tool, sidethread. It runs self-contained work in a fresh child Pi conversation and returns the result without copying the child's intermediate exploration into the parent context. A returned thread_id can resume that same child conversation later.

Install

From npm after publication:

pi install npm:pi-sidethread

From GitHub:

pi install git:github.com/Jawkx/pi-sidethread

Try it for one Pi run without installing:

pi -e git:github.com/Jawkx/pi-sidethread

Pi extensions execute with your user's full system access. Review extension source before installing it.

Tool API

sidethread({
  description: string;
  prompt: string;
  thread_id?: string;
  model?: string;
})

• description: short 3–5 word label shown in the UI
• prompt: self-contained work request for the fresh child context
• thread_id: resumes a thread created by the current parent session
• model: optional Pi model override; the active parent model is inherited by default

Model values use Pi's normal syntax, including optional thinking suffixes such as provider/model:high.

Start a thread

{
  description: "inspect auth flow",
  prompt: "Inspect the auth flow and report the relevant files and data flow. Do not modify files."
}

Resume it

{
  description: "inspect caller",
  prompt: "Now inspect the caller you mentioned and report what it validates.",
  thread_id: "<id from prior result>"
}

When to use it

Use sidethread when work is self-contained, needs several tool calls, or would add substantial intermediate context to the parent conversation. Good examples include codebase reconnaissance, library research, noisy failure investigation, and independent review.

Prefer Pi's direct tools for a simple file read, targeted search, or work that needs only one or two tool calls. The parent should not duplicate work already delegated to a thread.

Behavior

• Fresh child conversation unless thread_id is supplied
• Same working directory and project trust decision
• Pi's normal project instructions, skills, extensions, and active tools
• Parent model and thinking level inherited by default
• Optional per-call model override
• Persisted, parent-owned resumable sessions
• Live thinking, assistant text, tool activity, retries, and compaction in the tool row
• Expanded activity history through Pi's normal tool-details keybinding (Ctrl+O by default)
• Plain child result followed by Thread ID: <id>
• Cancellation and a fixed 30-minute timeout
• Concurrent-resume locking with stale-owner recovery
• Nested sidethread, thread, task, subagent, and subagent_wait tools disabled in children

Child sessions are stored at:

~/.pi/agent/thread-sessions/<parent-session-id>/<thread-id>/

Limitations

• Execution is foreground-only.
• Child processes can load only tools and providers discoverable in their own Pi process. Runtime-only SDK registrations and credentials may not carry over.
• Prompt instructions such as “do not modify files” are guidance, not a security boundary.
• Concurrent threads share the same working directory; callers must avoid conflicting writes.

Development

npm install
npm run check
npm test
npm pack --dry-run

Test the local package in Pi:

pi -e . --tools sidethread

License

MIT