[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81343":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":13,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":14,"starSnapshotCount":14,"syncStatus":12,"lastSyncTime":25,"discoverSource":26},81343,"pi-solo","HazAT\u002Fpi-solo","HazAT","Pi extension for Solo (soloterm.com) — registers every Solo MCP tool as a first-class Pi tool, auto-binds to SOLO_PROCESS_ID, idle-closes the helper, and renders Solo keyboard shortcuts in tool results.",null,"TypeScript",43,2,1,0,3,42.23,"MIT License",false,"main",true,[],"2026-06-12 04:01:33","# pi-solo\n\nNative [Pi](https:\u002F\u002Fpi.dev) extension for [Solo](https:\u002F\u002Fsoloterm.com), Aaron Francis's local agent + dev-stack workspace for macOS.\n\n\u003Cimg width=\"1822\" height=\"1185\" alt=\"SCR-20260516-irqz\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fe537bf3c-2007-4915-a1a1-c85d86b9fdca\" \u002F>\n\n## What it does\n\n- **PI SOLO header banner** with a live status line beneath it: connection state (starting \u002F warming \u002F connected \u002F disabled \u002F error), catalog size split into direct vs. gateway tools, the active surface profile, and the current model. Replaces pi's built-in header on `session_start` and re-renders on model changes and on every Solo MCP client transition — so the very first thing you see on startup already advertises what the extension is contributing.\n- **Bundled `solo` theme** — a GitHub-dark-derived palette shipped with the extension via `pi.themes`. Installing the package makes the theme available in `\u002Fsettings`; select it with `\"theme\": \"solo\"` in your pi `settings.json`.\n- Auto-detects Solo's bundled MCP helper at `\u002FApplications\u002FSolo.app\u002FContents\u002FMacOS\u002Fmcp`.\n- Spawns it lazily and speaks JSON-RPC over stdio — no separate MCP server to configure.\n- Queries Solo for its full tool catalog and exposes a curated tool surface. By default, only the handoff\u002Fworkflow essentials (`scratchpad_write`, `scratchpad_read`, `scratchpad_list`, `todo_create`, `todo_list`, `todo_update`, `todo_complete`) are **first-class Pi tools**; lower-frequency cleanup\u002Fadmin tools stay discoverable and callable through `solo_tool`.\n- **Solo-native, resumable subagents.** Spawn `scout`, `worker`, `planner`, `reviewer` (or any `~\u002F.pi\u002Fagent\u002Fagents\u002F\u003Cname>.md` definition) as real Solo agent processes via Solo's native `spawn_agent` MCP tool — visible in the sidebar with Solo's agent state, fire-and-forget, and woken via Solo's idle timer. Agent frontmatter `model` and `thinking` are forwarded as per-launch Pi `extra_args`, and every child gets a dedicated Pi `--session` JSONL file, so pi-solo can re-attach or respawn it after the parent restarts. Artifacts (plans, specs, context documents) flow through Solo scratchpads instead of local files.\n- **Optional Solo notifications** when a Solo subagent finishes and the parent Pi is ready for input. Enable with `\u002Fsolo-notify subagent`, `PI_SOLO_NOTIFY=subagent`, or `\"piSolo\": { \"notifications\": \"subagent\" }` in Pi settings. Notifications are sent through a dedicated Solo terminal so they use Solo's in-app notification path, not macOS system notifications.\n- **Auto-binds to `SOLO_PROCESS_ID`** via Solo's canonical `identify_session` tool when Pi runs as a Solo agent, so timers, locks, and todos owned by this Pi process behave correctly.\n- **Idle-closes the helper** after 5 s of inactivity so it doesn't show up as a persistent subprocess under your Pi row in Solo's sidebar. Bursts of MCP calls reuse one warm helper; quiet periods cost zero subprocesses.\n- **Renders keyboard shortcuts** on spawn\u002Fstart\u002Frestart\u002Fstatus results so you can press `⌥3 · ⌘5` (or whatever the position resolves to) to jump straight to the relevant agent in Solo's sidebar.\n- Polished `renderCall`\u002F`renderResult` for direct Solo tools — no raw JSON dumps in your tool log.\n- Gracefully no-ops when Solo isn't installed or MCP is disabled in Solo settings.\n\n## Install\n\n```bash\npi install git:github.com\u002FHazAT\u002Fpi-solo\n```\n\nOr pin a tag:\n\n```bash\npi install git:github.com\u002FHazAT\u002Fpi-solo@v0.1.0\n```\n\nFor local development, symlink the extension subdir into your global extensions directory:\n\n```bash\nln -s ~\u002FProjects\u002Fpi-solo\u002Fpi-extension\u002Fsolo ~\u002F.pi\u002Fagent\u002Fextensions\u002Fsolo\n```\n\nThe extension is auto-discovered. Run `\u002Freload` if Pi is already running.\n\n## Theme\n\nThe package ships a `solo` theme (a GitHub-dark-derived palette tuned for the banner gradient) under `themes\u002Fsolo.json` and registers it via `pi.themes` in `package.json`. After installing the extension:\n\n- Pick it interactively with `\u002Fsettings` → Theme → `solo`, **or**\n- Set it globally in `~\u002F.pi\u002Fagent\u002Fsettings.json`:\n\n  ```json\n  { \"theme\": \"solo\" }\n  ```\n\nThe currently active custom theme hot-reloads on edit, so tweaking `themes\u002Fsolo.json` in a clone gives immediate visual feedback.\n\n## Header\n\nWhen the extension loads it replaces pi's built-in header with a gradient `PI SOLO` block-letter banner plus a live status line:\n\n```\n● solo connected · 76 tools (7 direct · 69 gateway · core) · model claude-sonnet-4-6\n```\n\nThe status dot reflects the SoloMcpClient state — green when connected, yellow while warming or when MCP is toggled off in Solo settings, red on error — and the line re-renders on every model change and every MCP client transition. The previously transient `Solo connected — …` notification is gone; the same information now lives permanently in the header.\n\n## Setup\n\n1. Install Solo from \u003Chttps:\u002F\u002Fsoloterm.com>.\n2. In Solo: `Settings → MCP` → toggle MCP on.\n3. _(Optional)_ Enable Todos, Scratchpads, Timers, Key-value in the same panel to expose those tool groups.\n4. **Required for subagents:** In Solo: `Settings → Agents` → **Add tool**. Configure Pi as a Generic agent tool with command `pi`. `subagent` resolves this tool and launches it through Solo's native `spawn_agent`.\n\n## Commands\n\n| Command                                                               | Purpose                                                                        |\n| --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |\n| `\u002Fsolo`                                                               | Show connection status, catalog\u002Fdirect\u002Fgateway counts, bound project & process |\n| `\u002Fsolo-tools`                                                         | List Solo MCP catalog tools and whether they are direct or gateway-only        |\n| `\u002Fsolo-refresh`                                                       | Re-query Solo for its current tool catalog (cheap)                             |\n| `\u002Fsolo-reconnect`                                                     | Force-restart the helper                                                       |\n| `\u002Fsolo-bind \u003Cprocess-id>`                                             | Manually bind this Pi to a Solo process                                        |\n| `\u002Fsolo-subagent \u003Cname> [task]`                                        | Spawn a Solo subagent by agent name (scout, worker, …)                         |\n| `\u002Fsolo-subagent-resume \u003Cid\\|process-id\\|session> [prompt]`            | Resume\u002Fre-attach a subagent or respawn Pi with an existing `--session` file    |\n| `\u002Fsolo-notify [status\\|test [method]\\|off\\|subagent\\|agent-end\\|all]` | Configure\u002Ftest Solo notifications for completed Solo work                      |\n\n## Solo subagents\n\nSolo subagents lean into Solo's own primitives. Subagents are spawned with Solo's native `spawn_agent` MCP tool. Agent definition `model:` and `thinking:` frontmatter are passed to Pi as per-launch `extra_args`; Solo's saved agent tool defaults are not mutated. You can see, attach to (`⌘N`), and re-focus children from the sidebar. Solo provides the agent icon and `agent_state` tracking; `timer_fire_when_idle_any` wakes the parent when the child goes idle or hits the max wait.\n\n### Tools\n\n| Tool                 | Purpose                                                                                |\n| -------------------- | -------------------------------------------------------------------------------------- |\n| `solo_tool`          | List, inspect, or call Solo MCP catalog tools that are hidden from the direct surface. |\n| `subagent`           | Spawn a sub-agent in a Solo agent pane. Fire-and-forget; parent wakes on idle.         |\n| `subagent_resume`    | Re-attach to a live subagent or respawn Pi with a saved child `--session` file.        |\n| `subagent_interrupt` | Send Escape to interrupt the active turn (pane stays alive).                           |\n| `subagents_list`     | List available agent definitions from `~\u002F.pi\u002Fagent\u002Fagents\u002F` and `.pi\u002Fagents\u002F`.         |\n\n### Agent definitions\n\nDrop a `.md` file in `~\u002F.pi\u002Fagent\u002Fagents\u002F\u003Cname>.md` (or `.pi\u002Fagents\u002F\u003Cname>.md` for project-local overrides). The frontmatter carries `name`, `description`, `interactive`, `output`, `model`, and `thinking`, and the markdown body is inlined into the first prompt as the agent's identity. `model` (with an optional `:\u003Cthinking>` suffix) and a standalone `thinking:` field are translated into Pi CLI flags (`--model \u003Cspec>`, `--thinking \u003Clevel>`) and handed to Solo's `spawn_agent` as `extra_args`, so the child starts on the right model\u002Fthinking from launch — no child-side override step. Per-spawn `tools`, `skills`, `cwd`, and session-mode fields are tolerated for existing files but are not honored because Solo runs the configured agent tool command (`pi`) directly.\n\n```markdown\n---\nname: scout\ndescription: Fast codebase reconnaissance.\noutput: context.md # anything other than false keeps the scratchpad artifact pattern enabled\ninteractive: false\n---\n\nYou are a codebase reconnaissance specialist. …\n```\n\n### Scratchpad artifacts\n\nWhenever a subagent produces an artifact (plan, spec, scout report, review notes), it lands in a **Solo scratchpad** rather than a local file:\n\n1. The orchestrator pre-creates an empty scratchpad named `\u003Cagent>\u002F\u003Ctimestamp>-\u003Ctask-slug>`.\n2. The child is launched with a dedicated Pi `--session \u003Cjsonl>` file and the first prompt tells it the scratchpad name, id, and placeholder revision so it can overwrite the artifact via `scratchpad_write`.\n3. The Solo idle timer injects a wake-up body into the parent with the process id and scratchpad id so the parent can read it directly with `scratchpad_read`.\n4. The parent persists the child session path, process id, timer id, and artifact references in the parent Pi session. On restart, pi-solo validates the old Solo process; if it is still alive, it re-arms the idle watcher, and if it is gone, it respawns Pi with the same child `--session` file and sends a resume prompt.\n\nThis happens by default for every subagent. Set `output: false` in the agent definition or pass `scratchpad: false` to opt out of the scratchpad artifact; the child Pi session still exists for resumption.\n\n### Solo MCP tool surface\n\n`PI_SOLO_TOOL_SURFACE` controls how much of Solo's MCP catalog is registered directly in Pi:\n\n| Profile   | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `core`    | Default. Direct-register only the curated handoff\u002Fworkflow essentials — `scratchpad_write`, `scratchpad_read`, `scratchpad_list`, `todo_create`, `todo_list`, `todo_update`, and `todo_complete` — and route every other MCP catalog tool through `solo_tool`. New Solo 0.7.1 tools (`spawn_agent`, `identify_session`, `scratchpad_find`, `scratchpad_tail`, `scratchpad_edit`, `scratchpad_append_section`, project admin) stay available via the gateway and are intentionally not promoted to direct. |\n| `full`    | Direct-register every Solo MCP catalog tool.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| `minimal` | Direct-register no Solo MCP catalog tools; use `solo_tool` for all catalog access.                                                                                                                                                                                                                                                                                                                                                                                                                        |\n\nHand-written tools remain direct in every profile: `solo_tool`, `subagent`, `subagent_interrupt`, and `subagents_list`.\n\nUse the gateway to discover and call hidden tools:\n\n```typescript\nsolo_tool({ action: \"list\", query: \"process\" });\nsolo_tool({ action: \"schema\", name: \"get_project_stats\" });\nsolo_tool({ action: \"call\", name: \"get_project_stats\", arguments: {} });\n```\n\nState-changing gateway calls require a short reason:\n\n```typescript\nsolo_tool({\n\taction: \"call\",\n\tname: \"close_process\",\n\targuments: { process_id: 42 },\n\treason: \"close completed worker pane\",\n});\n```\n\n## Configuration\n\n| Env var                 | Default                                     | Purpose                                                      |\n| ----------------------- | ------------------------------------------- | ------------------------------------------------------------ |\n| `SOLO_MCP_HELPER`       | `\u002FApplications\u002FSolo.app\u002FContents\u002FMacOS\u002Fmcp` | Path to the bundled helper                                   |\n| `SOLOTERM_APP_DATA_DIR` | `~\u002F.config\u002Fsoloterm`                        | Solo's app data dir (passed through)                         |\n| `SOLO_PROCESS_ID`       | —                                           | If set, Pi auto-binds to that Solo process                   |\n| `PI_SOLO_DISABLED`      | —                                           | Set to `1` to disable the extension entirely                 |\n| `PI_SOLO_TOOL_SURFACE`  | `core`                                      | Tool surface profile: `core`, `full`, or `minimal`           |\n| `PI_SOLO_NOTIFY`        | `off`                                       | Solo notifications: `off`, `subagent`, `agent-end`, or `all` |\n\nNotification modes can also be set in `~\u002F.pi\u002Fagent\u002Fsettings.json` or `.pi\u002Fsettings.json`:\n\n```json\n{\n\t\"piSolo\": {\n\t\t\"notifications\": \"subagent\"\n\t}\n}\n```\n\nUse `\u002Fsolo-notify test` to verify Solo shows the notification before leaving it on. The default test creates\u002Freuses a `Pi Solo Notifications` terminal and sends OSC 777 from there; `\u002Fsolo-notify test macos` is available only as a diagnostic fallback.\n\n## How it works under the hood\n\nSolo ships a bundled stdio MCP helper at `\u002FApplications\u002FSolo.app\u002FContents\u002FMacOS\u002Fmcp`. The helper reads the shared MCP secret from `~\u002F.config\u002Fsoloterm\u002Fsolo.db`, connects to Solo's local Unix socket at `~\u002F.config\u002Fsoloterm\u002Fsolo-mcp.sock`, and bridges JSON-RPC over stdio. This extension spawns that helper, speaks the standard MCP protocol over its pipes, direct-registers the selected profile's tools, and keeps the rest reachable through `solo_tool`.\n\nThere is **no separate MCP server** in this extension. We talk to Solo directly using the helper Solo already provides.\n\n### Idle-close\n\nSolo's sidebar shows every Pi process's subprocess tree. A long-running helper would show up there as a persistent child. To keep things clean, the extension keeps the helper warm only during burst activity and closes it 5 seconds after the last MCP call. The tool catalog stays cached, so subsequent calls re-warm the helper in ~30 ms — transparent to the LLM.\n\n### Auto-binding\n\nWhen Pi is launched as a Solo agent (Solo sets `SOLO_PROCESS_ID` in the environment), the extension calls Solo's canonical `identify_session` on initialization, passing `solo_process_id` when available. The response populates the bound process\u002Fproject so timers it sets, locks it acquires, and todos it owns all belong to the right Solo identity. No fallback to the older `whoami` \u002F `bind_session_process` flow is kept — Solo 0.7.1+ is the supported baseline.\n\n### Subagent wake-up\n\n`subagent` launches the configured Pi agent tool through Solo's native `spawn_agent`, forwarding any `model` \u002F `thinking` from the agent definition plus a child Pi session file as `extra_args` (`--model …`, `--thinking …`, `--session …`). It then waits until Solo reports `agent_state.idle`, schedules `timer_fire_when_idle_any`, and sends the wrapped task as one user turn. When the child later goes idle (or reaches the 30 minute max wait), Solo injects a plain wake-up body into the parent Pi process with the child `process_id` and scratchpad id. The parent records the subagent complete in its session state, reads the scratchpad, and closes the child pane when finished.\n\n### Keyboard hints\n\nAfter successful `spawn_agent` \u002F `spawn_process` \u002F `start_process` \u002F `restart_process` \u002F `get_process_status` calls, the extension does two cheap follow-up MCP calls (`list_projects` + `list_processes`) to figure out where the target sits in Solo's sidebar, then renders the matching keyboard shortcut:\n\n- Same project, position ≤ 9 → `⌘5 to jump`\n- Different project, both ≤ 9 → `⌥3 · ⌘5 to jump`\n- Position > 9 → `⌘E to jump` (Solo's universal cross-project picker)\n\n## Repo layout\n\n```\npi-solo\u002F\n├── pi-extension\u002Fsolo\u002F\n│   ├── index.ts                 ← main extension (MCP client + tool registration)\n│   ├── header.ts                ← PI SOLO banner + live status subtitle\n│   └── subagents\u002F\n│       ├── index.ts             ← subagent tools, commands, task\u002Fwake text\n│       └── solo-surface.ts      ← thin Solo backend (agent spawn\u002Fsend\u002Ftimer\u002Fclose)\n├── themes\u002F\n│   └── solo.json                ← bundled `solo` theme (GitHub-dark palette)\n├── test\u002Ftest.ts                 ← unit tests (node:test)\n├── vite.config.ts               ← Vite+ config (fmt \u002F lint \u002F staged)\n├── .editorconfig                ← shared indent \u002F line-ending rules\n├── .vite-hooks\u002Fpre-commit       ← runs `vp staged` on every commit\n├── .pi\u002F\n│   ├── settings.json            ← dev pointer: load the extension when pi runs in this repo\n│   └── skills\u002Frelease\u002FSKILL.md  ← release workflow\n├── LICENSE                      MIT\n├── package.json                 scripts + peerDeps + `pi.extensions`\n└── README.md\n```\n\nMirrors the layout of [pi-interactive-subagents](https:\u002F\u002Fgithub.com\u002FHazAT\u002Fpi-interactive-subagents).\n\n## Development\n\nThe project uses [**Vite+**](https:\u002F\u002Fviteplus.dev) (`vp`) as the unified entry point for formatting, linting, and commit-hook orchestration. There is **no bundling** — the Pi extension is loaded directly as TypeScript at runtime — so `vp` only runs Oxfmt + Oxlint here, not Vite’s build pipeline.\n\n```bash\nvp install      # install dev dependencies (npm under the hood)\nvp config       # install the .vite-hooks\u002F_ pre-commit shim (once per clone)\nvp check        # format + lint the source tree\nvp check --fix  # auto-fix formatting and lint issues\nvp fmt          # run only Oxfmt\nvp lint         # run only Oxlint\nnpm test        # run unit tests (node:test)\n```\n\nOn every commit, the installed pre-commit hook runs `vp staged`, which executes `vp check --fix` against just the files in the index — trivial formatting drift is auto-fixed and re-staged before the commit lands.\n\nTo cut a release, ask Pi: “release 0.2.0” (the `.pi\u002Fskills\u002Frelease\u002FSKILL.md` skill drives the rest).\n\n## Status\n\nBuilt and tested on macOS 14+, Pi 0.74+, **Solo 0.7.1+** (the supported and tested baseline; older Solo versions are not supported). Linux\u002FWindows: untested (Solo is macOS-only anyway).\n\n## License\n\nMIT\n","pi-solo 是一个为 Solo（soloterm.com）设计的 Pi 扩展，旨在将 Solo 的每个 MCP 工具注册为 Pi 的原生工具，并自动绑定到 SOLO_PROCESS_ID。该项目使用 TypeScript 编写，具有自动检测 Solo 的 MCP 辅助程序、通过 JSON-RPC 进行通信、以及在空闲时关闭辅助进程等功能，从而优化了资源管理。此外，它还提供了实时状态栏显示连接状态、集成的主题选项和可恢复的子代理支持等特性。适用于需要在 macOS 上使用 Solo 作为开发环境并与 Pi 集成的工作场景中，以提高工作效率和用户体验。","2026-06-11 04:04:41","CREATED_QUERY"]