pi-jarvis

A cinematic side-conversation overlay for Pi

Open a second lane of thought without derailing the main session.

pi-jarvis adds /jarvis: a polished overlay where you can ask for status, inspect the repo when you explicitly allow it, and send a quiet note or a confirmed redirect back to the main lane.

The pitch

The main Pi session should stay on the critical path.

/jarvis gives you a second cockpit for the work that should not interrupt that primary flow:

• checking what the main agent is doing right now
• seeing what changed since the last /jarvis turn
• asking for triage, summaries, or a second opinion
• inspecting the repo with local tools when you turn them on
• sending a non-interrupting note back to the main session
• redirecting the main session only after explicit confirmation

Think of it as a side conversation with real context, not a detached scratchpad.

Typical prompts

• "What is the main agent doing right now?"
• "Summarize the last validation failure and tell me what matters."
• "Check this file while the main session keeps moving."
• "Compare what changed since my last /jarvis turn."
• "Redirect the main session, but make me confirm it first."

At a glance

| Capability | What you get | |---|---| | Persistent side lane | /jarvis keeps its own isolated conversation state and restores prior side-session history | | Live awareness | Jarvis sees the current main-session summary plus a delta since the last /jarvis turn | | Permission-gated tools | Local read, bash, edit, write, and optional mcp stay off until you enable them | | Safe main-session handoff | Note main is quiet; Redirect is confirmation-gated | | Independent model control | Follow the main model or pin /jarvis to a separate model | | Cleaner UX | Thinking-step streaming is collapsed into a cleaner animated fallback |

How it fits into Pi

flowchart LR
    U[You] -->|primary work| M[Main Pi session]
    U -->|open /jarvis| J[Jarvis overlay]
    M -->|summary + recent delta| J
    J -->|Repo tools enabled| R[Local tools\nread • bash • edit • write]
    J -->|optional| X[MCP]
    J -. Note main .-> M
    J -. Redirect after confirmation .-> M

Operating model

flowchart TD
    A["Main session keeps moving"] --> B["/jarvis opens in overlay"]
    B --> C["Jarvis sees current main-session context"]
    C --> D{"What do you need?"}
    D -->|Status / summary / analysis| E["Jarvis handles the side task"]
    D -->|Repo inspection| F["Enable Repo tools"]
    D -->|Influence the main lane| G["Enable Note main or Redirect"]
    G --> H{"Redirect?"}
    H -->|Yes| I["Per-send confirmation"]
    H -->|No| J["Quiet follow-up note"]

Why use /jarvis instead of the main lane?

Use /jarvis when you want:

• a second opinion without changing the primary plan yet
• a quick repo inspection while the main agent keeps moving
• a compact explanation of current progress or validation state
• a controlled way to send guidance back to the main session

Stay in the main lane when you want:

• the main plan to change immediately
• the main session itself to execute the next step directly
• no side conversation overhead at all

Quick start

1) Install

npm install pi-jarvis

This package is meant to run inside a Pi installation that already provides the Pi runtime packages. Those host packages are declared as optional peers so npm does not install a second copy of the full Pi/AI provider stack just to add this extension.

MCP support is optional. If you want the /jarvis Repo tools toggle to expose the mcp tool, install pi-mcp-adapter in the same Pi environment; otherwise /jarvis still enables local read, bash, edit, and write tools when you opt in.

2) Register the extension in Pi

Use the package's published extension entrypoint:

./dist/index.js

3) Open Jarvis

/jarvis

Or open it and send the first message immediately:

/jarvis summarize the last validation failure and suggest the fastest next move

4) Turn on more power only when you want it

• leave Repo tools off for pure context / analysis
• turn Repo tools on when you want local read, bash, edit, write, and optional mcp
• turn Note main on when you want Jarvis to quietly message the main session
• turn Redirect on when you want Jarvis to propose a redirect that you still explicitly confirm

Command surface

/jarvis

Opens the side overlay. If text follows the command, that text becomes the first side-session prompt.

/jarvis-model

When Pi has a UI, running /jarvis-model with no argument opens a model picker instead of requiring an exact provider/model string.

/jarvis-model [--project|--global] <provider/model>

Pins /jarvis to a specific model without changing the main session model. A plain /jarvis-model <provider/model> writes a project-local override to .pi/jarvis.json.

/jarvis-model [--project|--global] follow-main

Restores the chosen scope to follow-main. A project-scoped follow-main override still wins over a global pinned setting.

/jarvis-model [--project|--global] clear

Removes the selected scope so /jarvis falls back through the remaining config layers to the built-in default.

/jarvis-thinking [--project|--global] auto|follow-main|off|minimal|low|medium|high|xhigh

Sets the thinking level used by /jarvis without changing the main session thinking level. A plain /jarvis-thinking <level> writes a project-local override to .pi/jarvis.json.

• auto preserves the built-in behavior: follow the main thinking level only when /jarvis follows the main model; pinned /jarvis models use off.
• follow-main follows the main thinking level even when /jarvis is pinned to a separate model.
• Explicit levels pin /jarvis thinking to that level.
• xAI /jarvis models still force thinking off.

/jarvis-thinking [--project|--global] clear

Removes the selected scope so /jarvis thinking falls back through the remaining config layers to the built-in auto default.

Side-session commands inside /jarvis

The /jarvis input handles a small set of built-in commands against the isolated side-session:

• /compact [instructions] compacts the /jarvis conversation context.
• /tree prints the /jarvis session tree with entry IDs.
• /tree <entry-id> navigates the /jarvis session tree to that entry.
• /tree --summarize <entry-id> [instructions] navigates and summarizes the branch being left.
• /new starts a fresh /jarvis side-session without changing the main Pi session.

Model and thinking resolution

flowchart TD
    A[Project config\n.pi/jarvis.json] -->|if present| B{valid?}
    B -->|yes| P[Use project overrides]
    B -->|no or missing| C[Global config\n<agentDir>/extensions/pi-jarvis.json]
    C -->|if present| D{valid?}
    D -->|yes| G[Use global overrides]
    D -->|no or missing| E[Built-in defaults]
    E --> F[Model default: follow-main]
    E --> H[Thinking default: auto]

Resolution order

Model and thinking settings resolve through the same config layers, then fall back to separate built-in defaults:

1. project config: .pi/jarvis.json
2. global config: ~/.pi/agent/extensions/pi-jarvis.json or the equivalent path under a custom Pi agent dir
3. built-in defaults: model follow-main, thinking auto

Overlay controls

The overlay header exposes three controls, all off by default:

| Control | What it does | Safety model | |---|---|---| | Repo tools | Enables local read, bash, edit, write, and optional mcp | Explicit opt-in | | Note main | Sends a concise, non-interrupting note to the main session | Explicit opt-in | | Redirect | Sends a redirecting instruction to the main session | Explicit opt-in + per-send confirmation |

Note main and Redirect can be forcibly disabled when the active /jarvis model is incompatible with bridge tools.

Permission flow

flowchart TD
    A[Overlay opens] --> B[Repo tools off]
    A --> C[Note main off]
    A --> D[Redirect off]

    B -->|enable| E[Jarvis may use local tools]
    E --> F{MCP adapter available?}
    F -->|yes| G[Local tools + MCP]
    F -->|no| H[Local tools only]

    C -->|enable| I[Jarvis may send a quiet note to main]
    D -->|enable| J[Jarvis may request redirect sends]
    J --> K[Every redirect still requires confirmation]

    L[Incompatible /jarvis model] --> M[Note main disabled]
    L --> N[Redirect disabled]

Redirect flow

sequenceDiagram
    participant You
    participant Jarvis
    participant Main as Main session

    You->>Jarvis: Enable Redirect
    You->>Jarvis: "Tell the main session to stop and inspect overlay teardown"
    Jarvis->>You: Confirmation request
    You-->>Jarvis: Approve
    Jarvis-->>Main: Redirect instruction
    Main-->>You: Continues on new priority

Session behavior

• /jarvis keeps its own isolated conversation state
• prior side-session history is restored from a session file under jarvis-sessions/
• Jarvis sees current main-session state plus a compact delta since the last /jarvis turn
• /compact, /tree, and /new entered inside /jarvis operate on the side-session, not the main session
• plain /jarvis-model <provider/model> writes the project model override; use --global to change the global default
• plain /jarvis-thinking <level> writes the project thinking override; use --global to change the global default
• thinking-step streaming is intentionally collapsed to a cleaner animated fallback for readability

Example usage

Ask for live status

/jarvis what is the main agent doing right now?

Ask for triage while the main lane keeps moving

/jarvis summarize the last failing test and tell me the fastest likely fix

Use Jarvis as a repo-side helper

/jarvis inspect overlay.ts for teardown or redraw risks

Send a non-interrupting note back to the main session

1. Open /jarvis
2. Enable Note main
3. Ask Jarvis to send the note

Send a redirect safely

1. Open /jarvis
2. Enable Redirect
3. Ask Jarvis to redirect the main session
4. Confirm the send

Compatibility note

This repository's current validation baseline is Pi 0.69.0.

The package relies on Pi-provided peer dependencies, so treat other host versions as not the validated baseline for this repo unless you have tested them yourself.

Development

Install dependencies:

npm install

Type-check:

npm run check

Run tests:

npm test

Build the published package contents:

npm run build

Preview and verify the npm payload contract:

npm run verify:release

License

pi-jarvis is released under the MIT License. See LICENSE.