install-popola

name	install-popola
version	1.6.2
description	Install PopolaLoom (popola CLI + popolad daemon + the `popola-loom` Skill) globally for Cursor / Claude Code / Codex / GitHub Copilot. Trigger when the user says install popola / install popola-loom / install popolaloom / set up popola-loom / 装 popola-loom / 装 popolaloom / 安装 popola / /install-popola. Walks pip install + per-IDE registration + daemon boot + post-install verification (popola doctor).
metadata	{"surfaces":["cli","ide"],"requires":{"bins":["pip","popola"],"pythonVersion":">=3.11"},"cliHelp":"popola init --help"}
tier	1
token_estimate	1900
last_updated	2026-05-21
triggers	["install popola","install popola-loom","install popolaloom","set up popola","set up popola-loom","set up popolaloom","装 popola-loom","装 popolaloom","安装 popola-loom","安装 popolaloom","/install-popola","register popola skill","register popola-loom skill","update popola","update popolaloom","uninstall popola","uninstall popolaloom","更新 popolaloom","更新 popola-loom","卸载 popolaloom","卸载 popola-loom","/update-popola","/uninstall-popola"]

install-popola Skill

What this Skill does

A standalone, installer-only Skill that walks the host agent (Cursor / Claude Code / Codex / GitHub Copilot) through registering PopolaLoom on a fresh machine: pip install popolaloom → popola init <ide> --global → popola popolad start → popola doctor smoke. Mirrors the conventional /install-devola-flow workflow that installs DevolaFlow globally to ~/.cursor/skills/devola-flow/ and ~/.claude/skills/devola-flow/. Idempotent and safe to re-run for upgrades — every popola init step prints SKIP <path> (already installed) instead of overwriting.

When to use

Trigger this Skill (NOT the canonical popola-loom Skill) on any of:

• "install popola" / "install popola-loom" / "install popolaloom" / "set up popola" / "set up popola-loom" / "set up popolaloom"
• "装 popola-loom" / "装 popolaloom" / "安装 popola-loom" / "安装 popolaloom" / "把 popola 装到我的电脑" / "全局安装 popola"
• "/install-popola" slash command
• "register popola skill" / "register popola-loom skill" / "把 popola 加到 cursor / claude"

Note: The user-facing Skill identifier was renamed from popolaloom to popola-loom in v0.7.1+; the legacy phrasings (install popolaloom, 装 popolaloom, etc.) remain as triggers above so existing muscle memory keeps working. The Python package name popolaloom is unchanged.

The canonical popola-loom/SKILL.md (loaded after install) assumes popola is already on PATH and the daemon can be started. If that assumption fails on the host machine, run THIS Skill first.

Cloud Agent prerequisite (v0.8.5+)

If you will drive Cursor Background / Cloud Agents through PopolaLoom (--cli=cursor-cloud), provision a CURSOR_API_KEY alongside your shell profile before invoking popola dispatch. This is unrelated to ordinary local cursor-agent binaries — omit the key entirely if you only use --cli=cursor|claude|codex|kimi|copilot subprocess adapters.

Self-hosted setup (one-path, v1.6.0+)

Self-hosted dispatch (popola dispatch ... --cloud-target=self-hosted) has exactly ONE supported path in v1.6.0: Path-B JWT direct. This closes the 6 hard constraints in feedback_for_v1.5.2.md:

1. agent login — populates ~/.config/cursor/auth.json with the session JWT that Path-B reads. No CURSOR_API_KEY needed for self-hosted dispatch (constraint #5 / #3).
2. popola cloud worker start --worker-dir <repo-root> — registers ONE My Machines worker per workspace. --pool / --pool-name flags are REMOVED at the popola layer (constraint #1); Self-Hosted Pool workers go through agent worker start --pool directly outside popola.
3. No GitHub-App probe — the registered worker holds its own clone, so popola skips the GET /v1/repositories preflight for self-hosted (constraint #3).
4. view: https://cursor.com/agents/<bcId> URL — every --cloud-target=self-hosted dispatch prints this line to stdout (after the task_id) for web-side observability (constraint #4).
5. No --allow-fallback — passing --allow-fallback with --cloud-target=self-hosted is a no-op + bilingual stderr WARN (constraint #2). Self-hosted NEVER falls back to a local CLI.
6. No --auth-mode=rest for self-hosted — --auth-mode=session-jwt is the implicit default; explicit --auth-mode=rest with --cloud-target=self-hosted exits 2 (constraint #5).

End-to-end self-hosted bootstrap:

# 0. install popolaloom (Step 0 above)
# 1. Cursor session JWT
agent login                      # opens browser → writes ~/.config/cursor/auth.json

# 2. register the workspace worker (My Machines mode — no API key)
popola cloud worker start --worker-dir "$(pwd)" --management-addr 127.0.0.1:39231

# 3. start the daemon
popola popolad start

# 4. dispatch — auth-mode defaults to session-jwt for self-hosted
popola dispatch "ship the v1.6.0 release notes" \
  --cloud-target=self-hosted --worker-name=popolaloom-myrepo-deadbeef \
  --cwd "$(pwd)" --cli-flag repo_url=https://github.com/acme/myrepo
# → self-hosted-feedf00d
# → view: https://cursor.com/agents/bc-...

Cloud-only project init (v0.9.0 GA)

For teams that operate exclusively through Cursor Cloud Agents (no local cursor-agent / claude / codex subprocess CLIs needed), v0.9.0 GA ships a popola init --target=cloud-only profile that drops a minimal 3-file project scaffold — popolad.toml + .env.example + Makefile — with no IDE skill installs and no .local/ workspace surface. Use this AFTER Step 1 (pip install) instead of Step 2 (popola init):

mkdir my-cloud-project && cd my-cloud-project
popola init --target=cloud-only
#   OK   ./popolad.toml
#   OK   ./.env.example
#   OK   ./Makefile

cp .env.example .env
# Edit .env, set CURSOR_API_KEY=cr_...    (from https://cursor.com/dashboard → API Keys)

set -a && . ./.env && set +a            # export the env to the current shell
popola popolad start
popola dispatch --cli=cursor-cloud --prompt "Plan database migration scaffolding"

The scaffold is disjoint from the IDE skill install paths (~/.cursor/skills/popola-loom/... etc.), so a project that started as --target=cloud-only can later add per-IDE Skill installs by re-running popola init <verb> (Step 2 above) without conflicts. Idempotent on re-run; pass --force to overwrite operator edits. See docs/USER_GUIDE.md#popola-init---targetcloud-only-v090 for the full walkthrough and the cloud-quickstart.sh bash bootstrap that wraps it end-to-end.

Pre-flight checks (run first, in order)

python --version              # must be 3.11+
pip --version                 # needed for install
which popola                  # if present → jump to "Upgrade path"
test -d ~/.cursor && echo "cursor present" || echo "cursor absent"
test -d ~/.claude && echo "claude present" || echo "claude absent"

If which popola returns a path, popolaloom is already installed — skip Steps 1 + 2 below and go straight to Upgrade path (or just to Verification checklist for a sanity smoke).

Install (full path — fresh machine)

Step 0 — one-line install (preferred, v0.8.4+; defaults flipped in v0.9.6)

curl -fsSL https://raw.githubusercontent.com/YoRHa-Agents/PopolaLoom/main/install.sh | bash

The unified install.sh (v0.9.6+) wraps Steps 1–4 below into a single shell command: pip install (defaults to git+https://github.com/YoRHa-Agents/PopolaLoom.git since v0.9.6 — see .local/feedbacks/feedback_for_v0.9.4.md lines 2-5; PyPI publish remains deferred per Q-D-5 偏离默认 / BL-v0.9.x-PyPI) → popola skill install --target=all --global → popola popolad start → popola doctor. It is idempotent — safe to re-run on an already-installed machine. Useful options:

# install only for Cursor at project scope
curl -fsSL .../install.sh | bash -s -- install --scope=project --target=cursor

# install pinned to a specific tag (canonical v0.9.6 install)
curl -fsSL .../install.sh | bash -s -- install --ref=v0.9.6

# install from PyPI (only works once BL-v0.9.x-PyPI lands — currently delivers v0.8.x)
curl -fsSL .../install.sh | bash -s -- install --from=pypi --version=0.9.6

# preview every command without touching disk
curl -fsSL .../install.sh | bash -s -- install --dry-run

The script auto-detects Python 3.11+ (searching python3.12 → python3.11 → python3 → python); pass --python=/path/to/bin to override. Errors are surfaced explicitly per the workspace "No Silent Failures" rule.

If the one-line bootstrap fails (e.g. corporate firewall blocks raw.githubusercontent.com), fall back to the manual Steps 1–4 below.

Step 1 — pip install (one of these)

# v0.9.6 (Q-D-5 偏离默认 carries forward: PyPI deferred to v0.9.x; see BL-v0.9.x-PyPI in TRACKER).
# v0.9.6 also flips ./install.sh default --from=pypi → --from=git so the canonical path no longer
# requires PyPI (closes .local/feedbacks/feedback_for_v0.9.4.md lines 2-5):
./install.sh install                                                # canonical (default --from=git, tracks main)
./install.sh install --ref=v0.9.6                                   # canonical tag-pinned (recommended for v0.9.6)
pip install git+https://github.com/YoRHa-Agents/PopolaLoom@v0.9.6   # manual tag-pinned fallback
pip install git+https://github.com/YoRHa-Agents/PopolaLoom.git      # manual latest main (post-tag = v0.9.6)
pip install -e .                                                    # from a clone (dev workflow)
pip install popolaloom                                              # PyPI (currently v0.8.x; v0.9.x once BL-v0.9.x-PyPI lands)

If the user is on a corporate network or pip mirror that blocks (or simply doesn't carry) PyPI's popolaloom, the git+... forms continue to work (HTTPS to github.com is whitelisted in most environments and is also the new ./install.sh install default in v0.9.6). Note (v0.9.6): pip install popolaloom (no git+) currently resolves to the prior v0.8.x stable line; for v0.9.6 specifically use ./install.sh install --ref=v0.9.6 or the tag-pinned git+...@v0.9.6 form.

Step 2 — register the Skill into every IDE you use

popola init                   # auto-detect (preferred for first-time setup)

# OR explicit per-IDE (idempotent; second run prints SKIP):
popola init cursor --global   # → ~/.cursor/skills/popola-loom/SKILL.md
popola init claude --global   # → ~/.claude/skills/popola-loom/SKILL.md
popola init codex             # → $CODEX_HOME/skills/popola-loom/SKILL.md
popola init copilot           # → <repo>/.github/copilot-instructions.md (project-only)
popola init local             # → scaffold .local/ workspace surface

# OR every IDE at once (preferred when multiple IDEs are present):
popola init all --global      # every IDE except local, with global scope

popola init is the v0.5.0 multi-IDE installer (8 verbs × 8 modifiers; mirrors DevolaFlow per Q5-2 lock). The default scope is project-local; pass --global to install for the whole user.

Step 3 — boot the daemon

popola popolad start
# → "popolad started, PID=12345" + socket at ~/.popola/popolad.sock

The daemon is the persistent process that holds task state, the event bus, and the socket every popola dispatch / list / status / attach / cancel call talks to. Start it once per machine; re-run popola popolad start after a reboot (or wire it into systemd / launchd if you want it pinned).

Step 4 — verify install (5-second smoke)

popola doctor                 # 4-subsystem health table (skill / daemon / lark / arktower)
popola version                # → "popolaloom 0.9.6"
popola list-cli               # registered adapters (cursor / claude / codex / copilot etc.)

popola doctor exits non-zero on any FAIL row, so it's CI-friendly. The expected first-run output is 0 FAIL rows; any FAIL row prints a remediation hint.

Upgrade path (popola already installed)

# Preferred (v0.8.4+) — single-command upgrade
./install.sh update

# Or manually (matches the v0.5.0–v0.8.3 workflow):
pip install --upgrade popolaloom
popola skill upgrade --target=all   # overwrite installed SKILL.md with the wheel-shipped baseline
popola doctor                       # confirm no DRIFT

popola skill upgrade (Stage S4 of v0.5.0+) compares SHA-256 between the wheel-shipped SKILL.md and the on-disk installed copy, takes a .popola-loom-bak.<ts> backup, then writes the new content. Running popola init instead is also safe — it's idempotent — but it WON'T overwrite an existing SKILL.md (it only writes when the file is missing).

Uninstall path (v0.8.4+)

# Preferred (v0.8.4+) — single-command teardown (interactive prompt before pip uninstall)
./install.sh uninstall

# Scripted (CI / non-tty) — skip the prompt and also delete daemon state under ~/.popola/
./install.sh uninstall --yes --purge

# Or surgically remove the Skill from one IDE without touching the package:
popola skill uninstall --target=cursor --global

popola skill uninstall (NEW in v0.8.4) is the inverse of popola skill install: it removes the SKILL.md (and the sibling .popola-loom-version marker for cursor/claude/codex; copilot has no marker since it ships as a single copilot-instructions.md file) and prunes the now-empty popola-loom/ leaf directory. It is idempotent — re-running on a clean home prints ABSENT rather than failing. The unified install.sh uninstall verb composes this with popola popolad stop + pip uninstall popolaloom (+ optional rm -rf $POPOLA_HOME when --purge is set) for full teardown in one command.

Interactive wizard (alternative, v0.5.5+)

popola init --interactive

Walks the operator through per-IDE confirmations: detect IDEs → confirm install per IDE → choose scope → confirm plan → execute. Equivalent to Step 2 above but human-driven; safer for unfamiliar setups or when the operator wants to review every install path before writes.

Verification checklist

Check	Command	Expected
popola CLI on PATH	which popola	/usr/local/bin/popola (or similar)
Python module imports	python -c "import popolaloom; print(popolaloom.__version__)"	0.9.6
Cursor Skill installed	cat ~/.cursor/skills/popola-loom/SKILL.md | head -1	--- (frontmatter)
Claude Skill installed	cat ~/.claude/skills/popola-loom/SKILL.md | head -1	---
daemon running	popola probe	pid=... uptime=...
4-subsystem audit	popola doctor	0 FAIL rows

If every row matches the expected column, the install is complete. Move on to the canonical popola-loom Skill — the host agent will auto-load it the next time the user mentions "dispatch a task" / "派发任务".

Common installation errors and fixes

• popola: command not found — pip install succeeded but ~/.local/bin is not on PATH. Add it: export PATH="$HOME/.local/bin:$PATH" and append the same line to ~/.bashrc / ~/.zshrc so it survives new shells.
• Permission denied installing globally — use pip install --user popolaloom instead of system-wide; or run inside a virtualenv (python -m venv .venv && source .venv/bin/activate && pip install popolaloom).
• popolad failed to bind socket — a stale socket from a previous daemon is at ~/.popola/popolad.sock. Delete it (rm ~/.popola/popolad.sock) then retry popola popolad start. If a previous popolad is still running, popola popolad stop first.
• popola doctor reports DRIFT for the Skill — the installed SKILL.md version differs from the wheel version (usually because the user upgraded the wheel without re-running install). Run popola skill upgrade --target=all to refresh.
• Cursor / Claude doesn't auto-load the Skill after install — restart the IDE (or open a new chat); Skill discovery happens at startup. Confirm the file exists with ls ~/.cursor/skills/popola-loom/SKILL.md.

After install — what next?

Open Cursor or Claude Code in any project and say:

• "派发任务给 cursor 跑 X" / "dispatch a task to cursor: X"
• "list my running agents" / "popola list"
• "check my popola-loom health" / "popola doctor"

The host agent will auto-load the canonical popola-loom Skill (now installed) and route the request to the right popola verb. From here on, this install-popola Skill is dormant unless the user later asks to re-install / upgrade.

Reference

• Repo: github.com/YoRHa-Agents/PopolaLoom
• Canonical Skill (loaded after install): ~/.cursor/skills/popola-loom/SKILL.md (or ~/.claude/skills/popola-loom/SKILL.md)
• 5-minute Quickstart: docs/QUICKSTART.md
• DEMO walkthrough: docs/DEMO.md
• User Guide: docs/USER_GUIDE.md
• Sibling installer (reference): /install-devola-flow slash command — installs DevolaFlow globally with the same shape (curl → bash + per-IDE registration + verify).

Version + drift detection

• This Skill's frontmatter version field reflects the wheel-shipped baseline at install time (currently 0.9.6; bumped in lockstep with each release).
• After upgrading the wheel, run popola skill upgrade --target=all to refresh the on-disk SKILL.md (otherwise popola doctor flags drift once the wheel moves ahead).
• The companion .popola-loom-version marker beside this SKILL.md is the byte-stable input the doctor uses for the drift check; do not hand-edit it (the installer + upgrader own the file).