Start in 10 seconds

pi install npm:@groeponline/pi-wishcraft

Reload Pi, then press alt+p to open the Deck.

Try the two flows that make Wishcraft click fastest:

# remember to benchmark the new provider path
/ideas

The # line is captured as an idea instead of being sent as a prompt. Your active run keeps going.

Then open the skill picker:

/skills

Search, inspect and insert a skill without leaving the session.

Why Wishcraft

Pi stays the engine. Wishcraft adds the operator layer around it: live status, overlays, idea capture, skill search, sticky Bash, hooks, policy controls and session UX.

Kongming lanterns started as battlefield signals and later carried wishes. Wishcraft keeps both ideas in one place: telemetry while the work is moving, and thoughts you can park until you are ready for them.

Portfolio boundary: Wishcraft owns the operator cockpit and lightweight idea capture. Promote durable work to pi-missions, then use pi-agent-orchestrator when parallel or isolated execution adds value: idea -> mission -> orchestration run.

Guides live in docs/.

What you get

| Surface | What it does | | --- | --- | | Signal | Motion-aware three-lane operator status: model/Git, live activity/tool state, and context/queue. Default placement is the editor top border; /signal placement below moves it. | | alt+p | Wishcraft Deck: session, Signal, skills, ideas, guardrails, appearance. g + jump. /wishcraft settings is the flat list. /signal menu is Navigate / Configure / Status. | | # <idea> | File-backed inbox. Does not send the prompt. /ideas reviews status, tags, and skill insert. /ideas next feeds the oldest active idea into the session. | | alt+s | Stash the draft, ask something else, get it back when the run finishes. | | /skills | Overlay search on name, description, and path. Enter inserts. /skills doctor is the health table. /skills new writes a SKILL.md from a template. | | !cmd / bash mode | Managed shell with ghost suggestions from project history. No shell-native completion probes. | | Hooks + repairs | Command hooks on pi events. Custom-tool input repairs before execution. Kill-switch: wishcraft.hooksEnabled. | | Read hints | Appends a one-line continuation hint after a partial read, so the model knows the next offset. Opt-out: wishcraft.readHints: false. | | Policy | In-process deny/inject rules in global settings. No spawn. Kill-switch: wishcraft.policyEnabled. | | Working indicator | Four deterministic styles (dots, pulse, bar, ascii) with accessibility-aware static fallbacks. | | Welcome art | lantern, balloon, and normal opening artwork, each with a different silhouette and narrow-terminal fallback. |

Pi owns the footer chrome, feed scrolling, and input. Wishcraft supplies widgets, overlays, and the bash/stash/editor integrations. The bar is not clickable; actions are commands and overlays.

Daily commands

Activates on load. /signal toggles it. /signal <preset> switches the information layout. /signal menu opens Navigate / Configure / Status. /wishcraft opens the Deck. Tab completes presets and placement above|below|toggle. /powerline remains a compatibility alias.

/signal doctor        settings, queue, git, bash, fonts
/signal export        current preset + layout as JSON
/tps                  live in/out overlay (same ring as the segment)
/tps 40               override POWERLINE_TPS
/usage                session / today / week from ~/.pi/agent/wishcraft-usage.json
/repairs              tool-input repair counters
/skills               skill manager
/skills doctor        health table (broken frontmatter, dupes, unused, budget)
/skills new [name]    write a SKILL.md from a template
/ideas                idea review overlay (status, tags, skill insert)
/wishcraft            Deck overlay (operator surface)
/wishcraft settings   flat settings TUI
/open-ports           listening sockets
/cd <path>            continue this conversation in another directory
/bash-mode            sticky shell  (also ctrl+shift+b)
/vibe star trek       themed working messages

Keybinds (powerlineShortcuts, applied after /reload; null disables):

{
  "powerlineShortcuts": {
    "menu": "alt+p",
    "info": "alt+i"
  }
}

Minimal config

~/.pi/agent/settings.json (or PI_CODING_AGENT_DIR):

{
  "powerline": {
    "preset": "chef",
    "placement": "above",
    "welcome": true,
    "appearance": { "base": "lanternwake" }
  }
}

chef is muted colors, slash separators, live TPS in/out, and TCP port count. Built-in presets: default, minimal, compact, full, nerd, ascii, chef. Custom segments, labels, layout, and presets are documented in docs/configuration.md. For every setting at its default, see examples/settings.example.json.

Daily token budget (never blocks a turn):

{
  "wishcraft": {
    "tokenBudget": { "daily": 500000 }
  }
}

At 80% the cost segment warns; at 100% it goes red and welcome notifies. /usage shows the ledger.

Hooks

Hooks are commands that read JSON on stdin. See docs/configuration.md for examples.

Definitions come from the global agent settings file only. Project .pi/settings.json cannot install new hook commands. wishcraft.hooksEnabled: false disables every hook without deleting the config.

{
  "wishcraft": {
    "hooksEnabled": true,
    "hooks": {
      "preToolUse": [
        { "matcher": "bash", "hooks": [{ "command": "~/.pi/agent/hooks/bash-guard.sh", "timeout": 5 }] }
      ],
      "postToolUse": [
        { "matcher": "write", "hooks": [{ "command": "~/.pi/agent/hooks/write-audit.sh", "timeout": 5 }] }
      ],
      "sessionStart": [
        { "hooks": [{ "command": "~/.pi/agent/hooks/session-git-status.sh", "timeout": 10 }] }
      ]
    }
  }
}

Example hook (exit 2 = deny):

#!/usr/bin/env bash
payload=$(cat)
cmd=$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input",{}).get("command",""))')
if printf '%s' "$cmd" | grep -Eq '(^|[[:space:]])rm[[:space:]]+(-[a-zA-Z]*[[:space:]]+)*-r[a-zA-Z]*f|-fr[a-zA-Z]*|[[:space:]]/[[:space:]]*$'; then
  printf '%s\n' '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"blocked destructive rm"}}'
  echo "blocked destructive rm" >&2
  exit 2
fi
exit 0

Another example (append-only, never blocks):

#!/usr/bin/env bash
mkdir -p "$HOME/.pi/agent/logs"
cat >> "$HOME/.pi/agent/logs/write-audit.jsonl"

SessionStart example (extra context, never blocks):

#!/usr/bin/env bash
status=$(git status --short 2>/dev/null | head -n 40)
CTX="$status" python3 - <<'PY'
import json, os
print(json.dumps({
  "hookSpecificOutput": {
    "additionalContext": "git status:\n" + os.environ.get("CTX", "")
  }
}))
PY

Repairs run on custom/extension tools only, before hooks: drop null optionals, parse JSON-string arrays before wrapping, turn {} into [] on array keys, wrap bare strings, alias filePath / absolutePath / target_file to path, unwrap degenerate markdown auto-links. Core tools (bash, read, edit, write, grep, find, ls) are never rewritten. /repairs prints the counters.

Policy

Declarative deny/inject rules live in the global settings file; see docs/configuration.md. No shell commands — pure in-process regex. Evaluated before command hooks. wishcraft.policyEnabled: false disables policy without deleting rules.

{
  "wishcraft": {
    "policy": [
      {
        "action": "deny",
        "tool": "bash",
        "match": "sudo\\s+rm",
        "reason": "destructive sudo rm"
      },
      {
        "action": "inject",
        "tool": "read",
        "pathMatch": "\\.env",
        "context": "Do not leak secrets from .env files into the conversation."
      }
    ]
  }
}

Privacy/network boundary: ideas, settings, usage ledgers, and normal cockpit state stay local; there is no package-owned telemetry backend. Optional exchange-rate/DeepWiki features and operator-defined hooks cross the network/process boundary only when used.

Limits

• No mouse on the live footer. Pi core owns that surface.
• No second alt+i product. Ports stay on alt+i; other detail is → in the navigator.
• Compatibility status keys (powerline.preset, powerline.tps, powerline.ports) are available to peer extensions; normal Wishcraft use does not require them.
• The legacy @groeponline/pi-powerline-footer package is deprecated in favor of @groeponline/pi-wishcraft.
• Tags are not rewritten. 0.19.x through current stay on the timeline.

vNext Direction

Wishcraft is Pi's animated operator layer. See the release plan and design corpus.

Docs

• Commands
• Configuration
• Bash mode
• Stash and shortcuts
• Skill manager
• Working vibes
• Segments and theming
• ROADMAP

MIT. Issues: GroepOnline/pi-wishcraft.