Hook up Claude Code, Codex, or Gemini. One paste.

What you'll have at the end

• The weave CLI installed and signed in — the terminal interface to Powerloom. Backs every other integration on this page.
• Your runtime's plugin or extension installed — gives your agent context-aware slash commands and skills for working against Powerloom inside its native environment.
• A sub-principal for your agent session — a non-human identity nested under your user that carries attribution. Every action your agent takes shows up in the audit log as "you, via Claude Code (session ID)" rather than just "you."
• Your first tracker thread — the durable record of "what this session is working on." Per the §4.10 working agreement, every meaningful unit of agent work gets one.

Quick start — one-click launch

The web UI mints a launch token; you paste one command on any terminal on any machine; weave handles auth bootstrap, repo clone, MCP wiring, skill install, rules sync, and session registration in one step. No weave login ceremony, no manual git config, no plugin install — the whole thing happens in under fifteen seconds.

1. Install loomcli v0.7.20+ on the host you'll work from (one time per machine):

   pip install -U loomcli
   weave --version   # expect 0.7.20 or later

2. Open the Console. Visit /agents → Connect (or /settings/connect-agent). Pick a project from the dropdown and click Open in agent.
3. Confirm runtime, skills, capabilities in the modal. Click Mint launch token.
4. Paste the command the modal shows you into any terminal on the machine you'll work from:

   weave open lt_2026abc123...

5. You're in. Your shell becomes the agent, sitting in a fresh worktree at ~/.powerloom/worktrees/<scope>-<short-id>/ with the right branch, MCP server pre-authed, skills installed, agent-session registered.

The first time you run weave open on a new machine, the launch token doubles as the auth bootstrap — no weave login needed. A 90-day machine credential is written to ~/.config/powerloom/auth.json (Linux/macOS) or %LOCALAPPDATA%\powerloom\auth.json (Windows). Subsequent weave open calls skip auth.

Helpful flags: weave open <token> --dry-run previews the plan without cloning; --resume <session-id> re-attaches to an existing worktree; --reuse <scope> reuses the most recent worktree for that scope.

Operational helpers shipped in v0.7.20: weave reveal opens the worktree in your OS file manager; weave gc cleans up abandoned worktrees and bare clones; weave doctor got a Launch readiness section covering org clone-auth mode, machine-credential expiry, local-cred probe (gh / git credential / SSH-agent), and active-session count.

Manual setup (fallback)

Use the five-step path below when the launch flow isn't available — for example: offline environments, self-hosted Powerloom Home instances that haven't enabled launches yet, or pre-existing checkouts you want to wire up in place.

Step 1 — Install loomcli

loomcli ships the weave command and the runtime plugins. One pip install covers all three runtimes.

pip install -U loomcli

Requires Python 3.11+. If you don't have Python on your PATH, install it first or use pipx install loomcli for an isolated environment.

Verify:

weave --version

Step 2 — Sign in to Powerloom

weave login opens your browser to the access-token mint page, you paste the token back into the terminal, weave stores it locally and uses it for every future call.

weave login

Verify with weave whoami — you should see your email address and organization ID.

For headless / CI environments that can't open a browser: weave login --pat <your-token>. Mint the token at https://app.powerloom.org/settings/access-tokens.

For Powerloom Home / self-hosted: weave --api-url https://your-instance.example.com login. Or set POWERLOOM_API_BASE_URL in your shell rc.

Step 3 — Install the plugin for your runtime

loomcli ships three runtime integrations. Install the one(s) for your agent.

weave setup-claude-code

weave plugin install codex --execute

weave plugin install gemini --execute

Step 4 - Register the coordination session

A sub-principal is a non-human identity nested under your user. Your agent session uses the sub-principal's credentials, so audit logs distinguish "you personally hit pluck" from "your Claude Code session hit pluck on your behalf." Without this, every action looks like it came directly from you.

The normal session-start path creates or reuses the matching sub-principal automatically and caches it for tracker attribution:

weave agent-session register --from-branch --actor-kind codex_cli --if-not-active

Use claude_code, codex_cli, gemini_cli, or antigravity for --actor-kind. --from-branch expects a branch shaped like session/<scope>-<yyyymmdd>. If you are not in a git checkout, pass --scope, --summary, and --branch explicitly.

For long-lived agent identities outside the session-start flow, use weave agent sub-principal mint. The older weave subprincipal create form is no longer the supported command surface.

Step 5 — File your first thread

Tracker threads are Powerloom's "what's being worked on" surface. Per the CLAUDE.md / GEMINI.md / AGENTS.md §4.10 working agreement, every meaningful unit of agent work files a thread, plucks it (claims status=in_progress), updates it as decisions land, and marks it done at PR merge.

From any agent runtime, your first session looks like:

# 1. File the thread
weave thread create \
  --project powerloom \
  --title "Fix the login button color" \
  --priority medium \
  --description "Reported by Sarah on Slack 2026-04-26..."
# → returns id like 8d2c7502-...

# 2. Claim it (status → in_progress)
weave thread pluck 8d2c7502-...

# 3. As decisions / blockers land
weave thread reply 8d2c7502-... "Decided to use the design-system
  primary color instead of a one-off hex."

# 4. At PR merge
weave thread done 8d2c7502-...

From inside Claude Code, the same flow uses /powerloom-home:weave-thread. From Gemini CLI, /weave:thread:create. From Codex, the agent uses the weave-tracker skill loaded when you ask about thread workflow.

Common gotchas

• "Not signed in" after login — the credentials file write may have failed. Check weave whoami. Common cause: POWERLOOM_HOME points at a directory you don't have write access to.
• 426 Upgrade Required — your loomcli is older than the engine's supported schema majors. Run pip install -U loomcli and retry.
• Thread shows as your user, not your session - the session sub-principal cache was not written or is not being read. Re-run weave agent-session register --from-branch --if-not-activefrom the session branch, then retry the tracker action.
• Pluck returns 409 — someone else (often another session of yours!) has the thread. Use weave thread show <id> to see who has it and coordinate.
• weave open says "token expired" or "already redeemed" — launch tokens are single-use by default and expire quickly. Mint a fresh one from the Console; the previous spec is also cached locally at ~/.powerloom/launches/<hash>.json, so a Ctrl-C mid-clone can be resumed by re-running the same command without re-minting.
• Pre-flight fails on missing runtime binary — weave open checks for git and the runtime binary (claude / codex / gemini) on PATH before the slow clone step. Install whichever is missing and re-run.
• "Machine credential expired" — the 90-day credential is past its TTL. Run weave open <token> again from the Console; the redeem will re-bootstrap the credential.

Where to read more

• Docs landing — overview of every Powerloom surface.
• Powerloom Home setup — for self-hosted / single-laptop installs.
• weave-open-launch.md — the architecture for the one-click launch flow: token minting, redeem, machine credentials, clone-auth modes, worktree-per-launch.
• CLAUDE.md — the project's working-agreement file. §4.10 covers the tracker-thread discipline this guide walks you into.
• weave-tracker SKILL.md — the canonical guide for agents on the four-step thread lifecycle (create → pluck → reply → done).