Piwi TUI for pi.dev

Piwi = Pi + Wiki. Piwi is a playful, practical extension pack for pi.dev: durable knowledge, planning, background helpers, web research, safe process management, project diagnostics, a small companion, and matching pastel dark/light themes.

Piwi does not replace Pi’s system prompt or install a persona prompt. Its features remain normal Pi tools, commands, local views, and widgets that you can enable individually.

Quick start

pi install npm:piwi-tui

For only the current project:

pi install npm:piwi-tui -l

Then open /settings and choose piwi-theme or piwi-theme-light. Update later with:

pi update npm:piwi-tui

What you can do

Build project knowledge

• Memory keeps a small set of approved project or global facts.
• Wiki stores durable Markdown pages under .pi/wiki/.
• Source ingestion turns documents and images into searchable evidence while preserving visual assets.
• Skills browse everything Pi loaded—including shared Agent Skills—and create approved Pi-managed procedures.

Try: /memory, /wiki, /skills, or ask Pi to ingest a document or image.

Organize work

• Todo is one lightweight checklist for the work happening now.
• Plans handle substantial multi-step work and decisions.
• Tasks are durable backlog items, reminders, and deadlines.
• Boards organize cards by status.
• Doctor gives a fresh, read-only project readiness report.

Try: /todo, /plan, /tasks, /board, or /doctor.

Research without blocking the main conversation

• Web search and fetch collect bounded, explicitly untrusted evidence.
• BTW answers a side question in parallel with the current conversation.
• Subagents run isolated read-only helper sessions for bounded research and codebase exploration.
• /agents config offers a searchable list of the models Pi can actually use, plus helper thinking defaults.

Try: /btw Why is this test flaky?, /agents config, or /research <question>.

Run and diagnose safely

• Guard asks before obvious secret-file or outside-project access.
• Processes manage session-owned background commands, logs, and input.
• Proxy routing applies ordered hostname rules to model APIs and extension fetches.
• /proxy test <url> checks exactly which rule and transport a destination uses.
• Locks diagnoses persistent Piwi locks without deleting anything.

Try: /guard status, /processes, /proxy status, /proxy test https://api.example.com, or /locks.

Add some personality

• Pet is one global companion that grows only from assistant output tokens.
• Counters provide durable global tallies and up to four pinned values.
• Pomodoro adds a live focus/break timer.
• Pastel themes provide matching dark and light presentation.

Try: /pet, /counter, or /pomodoro 25 5.

Everyday command reference

Command	What it opens or does
/memory [project|global]	Browse and filter saved facts
/wiki [page]	Search and open project wiki pages
/skills [project|global|shared|loaded]	Search every skill loaded by Pi, optionally filtered by source
/todo [clear]	Manage the current-work checklist
/plan [slug]	Choose a recently active plan and update its steps
/tasks [overdue|today|upcoming|someday|done]	Browse and manage durable tasks
/board [name]	Choose and manage a kanban board
/doctor	Inspect stacks, dependencies, checks, Git, CI, and environment-file hygiene
/btw <question>	Ask a parallel context-aware side question
/agents [config|stop]	View helpers, configure defaults, or cancel helpers
/guard on|off|status	Control Guard for this session
/proxy on|off|status|reload|rules	Control expert hostname routing
/proxy test <url>	Probe the matching rule, route, transport, timing, and HTTP result
/processes [id]	Browse managed processes, logs, input, and stops
/counter [name] [+/−N|=N|reset]	Open counters or adjust one directly
/pomodoro [work] [break]|stop	Start or stop a focus timer
/pet …	Open the nook; /pet help lists direct actions
/locks	Inspect Piwi state locks without changing them

Interactive views stay inline in chat. Their navigation and action keys remain visible, wrap on narrow terminals, and preserve filters and selection across prompts or confirmations.

Documents and images

ingest_source stores extracted text in .pi/wiki/sources/ and every durable visual asset in .pi/wiki/assets/<source>/. Source Markdown contains real relative image links, so ordinary Markdown viewers can load the saved visuals.

Supported inputs include plain text, Markdown, CSV, JSON, PDF, DOCX, PPTX, XLSX, ODT, ODP, ODS, PNG, JPEG, GIF, WebP, BMP, and safe SVG. BMP and safe SVG are normalized to PNG; TIFF is not advertised because model and decoder support is inconsistent.

For standalone images, document figures, presentation graphics, PDF figures/pages, and spreadsheet charts, Piwi can:

• Preserve a renderable local asset.
• Transcribe meaningful visible text and tables.
• Describe layout, diagrams, charts, and relationships.
• Omit an OCR section when there is no meaningful text.

Project-local ingestion itself does not ask for approval. Importing a file from outside the project does. Sending image data to the active remote vision model also asks separately because provider retention policies may apply. Declining vision analysis does not prevent the local visual asset from being preserved.

Helper defaults

Run /agents config to choose from modelRegistry.getAvailable()—the same authenticated, configured models Pi can actually select, not the entire public catalog. The list puts inherit/current/saved choices first, keeps the parent provider nearby, and supports immediate typing to search.

Helpers inherit the parent model and thinking level unless defaults or per-call overrides are set. They have a ten-minute hard limit. After two minutes without emitted activity, Piwi displays a quiet warning but does not kill the helper early; buffered providers and long reasoning can legitimately appear idle.

Doctor behavior

/doctor is deterministic and model-free. It understands common JavaScript/TypeScript, Python, Rust, Go, Ruby, Java/Kotlin, .NET, PHP, Swift, C/C++, and Elixir project conventions. It detects likely quality commands but never runs them.

Each invocation creates one fresh local session report. Doctor does not write a project file, save memory, call a model, access the network, install dependencies, or run project scripts.

Theme color language

Both themes use the same semantic roles:

• Light blue / azure: headings, current or active state, primary values, selected focus.
• Periwinkle / purple: visible keyboard keys and action hints.
• Cyan: technical structure, secondary borders, code, and links.
• Green: healthy, completed, or successful outcomes.
• Yellow / sand: warnings and attention.
• Rose / red: errors and destructive states.
• Gray: descriptions, metadata, separators, and inactive content.

All package-owned renderers, cards, widgets, notifications, and interactive views are checked in both dark and light themes and at narrow terminal widths.

---

Configuration and advanced details

Create ~/.pi/agent/web.json (or %PI_CODING_AGENT_DIR%\web.json):

{
  "search": "brave",
  "keys": { "brave": "...", "exa": "...", "jina": "..." }
}

search may be brave or exa. The Jina key is optional and only raises web_fetch limits. Environment fallbacks are BRAVE_API_KEY, EXA_API_KEY, and JINA_API_KEY.

Queries go to Brave or Exa; fetched URLs go through Jina Reader. Results are bounded and labelled untrusted. URLs containing embedded credentials are rejected.

Proxy settings live only in ~/.pi/agent/proxy.json:

{
  "proxy": "http://127.0.0.1:7890",
  "enabled": true,
  "mode": "direct",
  "useDefaultCredentials": true,
  "rules": [
    { "match": "10.*", "action": "direct", "comment": "Intranet" },
    { "match": "openrouter.ai", "action": "proxy" },
    { "match": "api.openai.com", "action": "direct" },
    { "match": "*", "action": "direct" }
  ]
}

Rules match actual destination hostnames only, top-to-bottom, with first match winning. Do not include schemes, ports, paths, or credentials. A universal * rule must be last. mode handles unmatched destinations.

/proxy test <url> performs an isolated 15-second HEAD probe with no API key or request body. It reports the matching rule, direct/proxy route, selected transport, elapsed time, HTTP result, and sanitized failures. It works even when global routing is off. /proxy status remains concise but retains the latest sanitized network error and its route alongside configuration and counters.

fallback retries only bodyless GET/HEAD network failures. Piwi never replays model POST requests. /proxy off restores the previous dispatcher, fetch function, and proxy environment.

On Windows, useDefaultCredentials:true uses Invoke-WebRequest -ProxyUseDefaultCredentials for matched model HTTP/SSE and extension fetches. Responses are buffered; request bodies and SSE files are preserved byte-for-byte. The implementation is compatible with PowerShell Constrained Language Mode. Proxy credentials are redacted from displays and omitted from the provider environment bridge.

/agents config normally manages ~/.pi/agent/subagents.json:

{
  "model": "openai-codex/gpt-5.4-mini",
  "thinking": "low"
}

Omitting either property means inherit the launching session. Per-call sub_agent.model and sub_agent.thinking take precedence. Thinking may be off, minimal, low, medium, high, xhigh, or max.

Each invocation accepts up to eight tasks. One session-global semaphore allows three helper children concurrently. Helpers receive only their explicit task, use bounded read-only file/search/web/time tools, and do not receive the parent transcript, context files, or skills. Background findings return as a model-waking message; /agents stop cancels all queued and running helpers.

• Todo: the one immediate execution checklist; retained after completion until confirmed /todo clear.
• Plan: substantial sequencing, decisions, and review points in .pi/plans/.
• Task: durable backlog, reminder, or deadline work in .pi/agenda/tasks.json.
• Board card: status-oriented work on a named kanban board.

Task recurrence is descriptive only; it does not create future instances automatically.

remember and forget maintain curated Markdown facts in project or global MEMORY.md. Memory writes, skill creation, and wiki-page writes require interactive approval. Wiki approvals are serialized and scoped to the exact displayed path.

Memory is sent to the active provider before model calls and therefore consumes context. /memory, /wiki, and /skills browse locally without injecting those views into model context.

/skills reads Pi’s actual loaded-skill registry. It includes ~/.pi/agent/skills/, project .pi/skills/, shared ~/.agents/skills/, trusted project/ancestor .agents/skills/, package skills, settings entries, and explicit CLI skills. Shared/package/configured skills are read-only in Piwi; create_skill writes only Pi-managed project or global locations.

Guard is separate. /guard off disables Guard’s session file/URL confirmations but does not bypass wiki, memory, skill, external-ingestion, cloud-vision, or destructive-clear approvals.

Imported sources remain explicitly untrusted and are excluded from normal wiki search unless include_sources:true is requested.

Guard is a confirmation heuristic, not an operating-system sandbox. It realpath-checks structured read/write/edit paths, confirms obvious secret and outside-project access, and heuristically scans shell strings. Dynamic shell behavior cannot be perfectly understood.

Managed processes are session-owned, bounded, non-detached programs with sanitized temporary logs. They are never shared or persisted and are terminated when Pi exits. process start receives the same Guard shell-path check as built-in bash.

The pet is global across projects in ~/.pi/agent/pet.json. A new companion asks for its name on the first /pet visit. It earns exactly 1 Spark per 500 assistant output tokens and 1 XP per 1,000 assistant output tokens; input, cache, tools, helpers, and BTW output do not count.

The pet never dies, leaves, loses purchases, or requires streaks. /pet help lists profile, care, shop, collection, journal, evolution, adventure, encounter, naming, display, and settings actions.

Counters live in ~/.pi/agent/counters.json, support 100 named integer values and four pins, and add no model prompt overhead. In the dashboard, only ← and → adjust values; Enter, Space, +, and − remain unbound.

Extension	Main capability
datetime.ts	now with local/UTC/timezone data
web.ts	web_search, web_fetch
proxy.ts	Unified hostname routing and route probes
memory.ts	Approved project/global memory
wiki.ts	Wiki pages, search, and source ingestion
tasks.ts	Tasks and kanban boards
plan.ts	Plans plus ask_user
todo.ts	One current-work checklist
doctor.ts	Read-only project readiness
locks.ts	Read-only lock diagnostics
btw.ts	Parallel side questions
subagent.ts	Parallel read-only helper agents
skills.ts	Browsing every loaded skill plus approved Pi-managed creation
guard.ts	Risky-access confirmations
autoname.ts	Automatic session names
pomodoro.ts	Focus/break widget
counters.ts	Global counters and pinned widget
processes.ts	Session-owned background processes
pet.ts	Global companion and progression

Prompt templates:

Prompt	Purpose
/briefing	Adaptive project overview and current work
/changes [path]	Summarize uncommitted Git changes
/research <question>	Parallel web research and sourced synthesis

All package-owned tools use compact call/result/error cards. Large web, process, and imported-document evidence is bounded and labelled untrusted.

Use pi config to enable or disable individual Piwi extensions, prompts, and themes globally or per project. Project-local installs live in .pi/settings.json; if the same package exists globally and locally, the project entry wins.

Normal Pi project instructions belong in <project>/AGENTS.md or CLAUDE.md. Pi also walks ancestor directories and reads ~/.pi/agent/AGENTS.md globally.

System-prompt files are different:

• <project>/.pi/SYSTEM.md replaces Pi’s default system prompt.
• <project>/.pi/APPEND_SYSTEM.md appends without replacing it.
• Global equivalents live in ~/.pi/agent/.

Piwi ships neither file. Run /reload after changing context or system-prompt files.

Git install:

pi install git:github.com/JoulesDotDev/piwi-tui@v1.5.4

Contributor local-path install:

bun install
pi install /absolute/path/to/TUI
bun run check

Pi loads the TypeScript directly; no build step is required for use. Local paths remain references to the checkout, while npm/Git installs are managed independently under Pi’s agent directory.

Some corporate Windows policies block dependency postinstall scripts. Piwi does not require them:

npm config set ignore-scripts true
pi install npm:piwi-tui
npm config delete ignore-scripts

Project and global data

Project data stays under <project>/.pi/: memory, Todo, agenda, plans, wiki pages/sources/assets, and project skills. Global state and configuration live under Pi’s agent directory: global memory, pet, counters, web, proxy, helper defaults, and global skills.

Review project wiki sources before committing because they may contain complete confidential documents. Protect web.json and any proxy URL containing credentials as secrets.

Optional MCP companion

MCP remains intentionally separate:

pi install npm:pi-mcp-adapter

Piwi does not bundle or configure MCP servers.

License

MIT