Paseo BTW

Ask a side question without interrupting the main task.

@geoqiao/paseo-btw opens a lightweight conversation in the same Paseo workspace. The child appears in the Subagents track, while you continue working with the parent. In Paseo-managed Pi sessions, the native /btw command launches it without a parent LLM turn.

/btw why might this API return 409?

Quick start · Native command or Skill · Defaults · Context and limits

Quick start

Prerequisites

Run inside a Paseo-managed agent. Native Pi commands require the paseo CLI to be available; they use the parent identity supplied by Paseo through PASEO_AGENT_ID.

For the portable Skill, enable orchestration tools under Settings → your host → Agents → Enable Paseo tools, then start a new agent or reload the current one. The Skill prefers injected Paseo tools and falls back to the CLI when unavailable.

Pi

pi install npm:@geoqiao/paseo-btw

Run /reload in an already-open Pi session, then ask your side question:

/btw explain this stack trace

The extension also registers /paseo-btw. If another extension owns /btw, Pi assigns numeric suffixes; use /paseo-btw to avoid that collision.

Claude Code, Codex, and other Agent Skills clients

Install the portable Agent Skill from the repository:

npx skills add geoqiao/pi-tools --skill paseo-btw --agent '*' -g

Invoke the installed paseo-btw Skill using your client's command syntax. Claude Code and Codex may expose /paseo-btw; Pi uses /skill:paseo-btw. These clients still need a Paseo-managed session and orchestration access—the Skill is not a standalone agent service.

The npm package has no install-time script that edits agent configuration. Pi reads its extension and skill manifests; other clients use the skills installer.

Native command or Skill?

Capability	Native Pi extension	Model-mediated Skill fallback
Entry point	/btw or /paseo-btw	Installed Skill command in the host client
Parent model turn	None; the extension calls the launcher directly	One orchestration turn
Defaults	Inherits parent provider/model, thinking setting, and bounded text context	Same defaults; can also copy mode and feature values
Configuration	/btw-config	Skill config requests
One-off model selectors	Not parsed from the side question; use /btw-config	Supports --model, --provider, and --profile
Context	inherit or none	inherit, semantic summary, or none

When the Pi extension is loaded, it also intercepts /skill:paseo-btw before Skill expansion. That path behaves like the native command, not the model-mediated fallback. Text after the command is forwarded as the side question rather than parsed as Skill flags.

For hosts actually using the model-mediated Skill, examples in Pi-style notation are:

/skill:paseo-btw why might this API return 409?
/skill:paseo-btw --provider claude sanity-check this UX decision
/skill:paseo-btw --profile 低成本精修 explain this stack trace

Use your host's equivalent invocation syntax. Continue follow-up discussion in the existing child tab rather than starting a new child for every message.

Defaults and configuration

The native command inherits the parent's model and context unless configured otherwise. View current settings without launching a side agent:

/btw-config

Setting	Default	Example
Model	inherit	/btw-config model claude/claude-haiku-4-5
Context	inherit	/btw-config context none
Timeline tail (paseo logs --tail)	40	/btw-config context-tail 40
Context limit	8000 characters	/btw-config context-max-chars 8000

Explicit model values use Paseo's provider/model format; Pi model IDs can contain another slash, such as pi/openai-codex/<model-id>. Choose a model available in your Paseo setup. Restore inheritance or reset all defaults with:

/btw-config model inherit
/btw-config context inherit
/btw-config reset

Settings normally live in ~/.config/pi-tools/btw.json. PI_TOOLS_CONFIG_HOME, then XDG_CONFIG_HOME, can override the config root. The portable Skill uses the same persisted settings through its config requests; one-off Skill selectors override them for that invocation only.

Context and limits

Mode	What the child receives
inherit	A bounded mechanical snapshot of the parent's Paseo text timeline plus the side question
none	The side question without parent history
summary	A semantic summary prepared by the parent model; available only through the model-mediated Skill

Mechanical capture uses documented paseo logs output, removes the current turn and reasoning blocks, strips terminal escapes, applies best-effort secret redaction, and enforces the configured size limit. Redaction is not a guarantee that all sensitive information is removed. Inherited text is sent to the child agent and its selected provider; use context none when you do not want to forward parent history.

If native capture fails, the side conversation still launches with only the question and reports the fallback. If summary was saved through the Skill, the native command sends no parent context and warns that semantic summarization requires a model turn. The model-mediated Skill may instead fall back from failed capture to a semantic summary.

This is not a provider-native session clone. Paseo's app-level Fork chat from here also curates text for a new agent; native Pi session forking is not implemented by this package.

The side conversation shares the parent's workspace; it does not create a worktree or an isolated sandbox. The portable Skill instructs the child to stay read-only and not take over the main task, but that is guidance, not permission enforcement. The native launcher forwards the question without adding the Skill's read-only response contract. Do not rely on either entry point as a security boundary. Pi's /skill:paseo-btw interception cannot forward image attachments through the CLI.

Pi handles the extension command before starting an LLM turn. A packaged Node CLI reads persistent defaults, inspects the parent agent, captures context when enabled, and calls paseo run --background. It forwards the side question unchanged after trimming; no parent reasoning or tool-call loop is needed.

The child stays in the current Paseo workspace through the inherited parent identity. With model inheritance enabled, the launcher copies the parent's thinking setting and a mode when it can validate that mode against the parent's available modes. It does not promise a complete copy of every provider feature or native session state.

See the portable Skill for model-mediated launch, selector handling, context rules, and CLI fallback behavior.

Development

From the monorepo root:

pnpm --filter @geoqiao/paseo-btw test
pnpm --filter @geoqiao/paseo-btw pack:check

To install the local Skill into supported clients:

npx skills add ./packages/paseo-btw --skill paseo-btw --agent '*' -g

See CONTRIBUTING.md for workspace setup and Changesets. This package is published independently from the other workspace packages.

License

MIT.