Hook up Claude Code, Codex, or Gemini. Five steps.

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.

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.

Where to read more

• Docs landing — overview of every Powerloom surface.
• Powerloom Home setup — for self-hosted / single-laptop installs.
• 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).