This page covers connecting Claude Code to Loom: what loom setup does for it, the equivalent manual commands, how to verify the hooks, and how to update or remove it.
Run loom setup and leave claude selected. When ~/.loom/stores.toml already holds your credentials for the server, setup skips the sign-in (it prints Using your existing Loom stores for <server>; run loom login to sign in again.); otherwise it first asks for your email address, consent and a sign-in code. For Claude Code it runs the two commands below, then checks claude plugin list --json for exactly one enabled loom@loom entry. In v0.672 or later it also runs claude mcp list and requires the plugin:loom:loom row to read Connected; the row says installed and verified only then.
A successful run (tested against a private server with loom setup --harness claude --base https://<your-server>) ends with the stores line and one result row per harness:
Loom store(s) coding, loom_demo, kanban configured in ~/.loom/stores.toml.
claude installed and verified
Claude Code: start a new session so the Loom MCP server picks up the new store entry; an already-running session will not see it until restarted.Afterwards claude plugin list --json shows one enabled loom@loom entry.
Setup installs the plugin from the marketplace of the server it signed in to: <server>/loom-plugins.git. The server is --base, or the single origin recorded in ~/.loom/stores.toml, or LOOM_WEB_BASE, or https://loomcloud.ai (see Choosing the server). For a hosted account that is https://loomcloud.ai/loom-plugins.git.
Setup still writes your stores in both cases below, then exits with status 3 and marks the run partial.
A private server reached over http:// does not serve a plugin marketplace, so setup skips the Claude Code install. It prints this line once:
Plugins need an https server: the Loom plugin marketplace is not served over http, so the claude/codex plugin install was skipped. Your store is set up.and this row, with no restart line:
claude skipped (plugins need an https server)With --json the line goes to stderr and the result for claude has "action": "skipped" and "error": "claude: plugins need an https server; skipped". Move the server to https, or install the plugin from a marketplace you can reach as in Manual install.
If a loom marketplace is already installed from a different origin, setup never updates or replaces it. The row reads:
claude FAILED -- claude: the existing Loom marketplace comes from <listed source> but this setup is for <base> (<base>/loom-plugins.git), so nothing was changed. To switch deliberately, run `claude plugin uninstall loom@loom`, then `claude plugin marketplace remove loom`, then re-add it with `loom setup --base <base>`.<listed source> is shown without credentials, query or fragment. For https://loomcloud.ai the last command reads loom setup. To switch on purpose, run the commands in the row:
claude plugin uninstall loom@loom
claude plugin marketplace remove loom
loom setup --base https://<your-server>If Claude Code does not report where the installed marketplace came from and the server is not https://loomcloud.ai, setup updates it anyway and prints under the row: claude: the existing Loom marketplace's origin is not exposed by this harness, so it was updated without checking it came from <base>.
Claude Code 2.1.286 reports the source of each marketplace in claude plugin marketplace list --json ("source": "git", "url": ...).
Use the exact claude executable you use for normal sessions or a fixed-session worker.
Prerequisite: uv must be on the PATH of the shell that launches claude. When the CLI installer finds no uv, it installs a private copy at ~/.loom/bin/uv. From v0.672 the installer also puts ~/.loom/bin on PATH for new terminals (macOS and Linux: through ~/.loom/env, which it adds to your shell profiles; Windows: the user PATH); in an already-open terminal run . "$HOME/.loom/env" or open a new one. With an earlier installer, add ~/.loom/bin to PATH yourself (or install uv system-wide). Without uv the MCP server fails to start (claude mcp list shows Failed to connect - ENOENT: Executable not found in $PATH: "uv") and the Loom MCP tools are missing.
From v0.672, loom setup checks this instead of reporting success: when the plugin is installed but claude mcp list does not show plugin:loom:loom connected, the row is not installed and verified. It reads:
claude FAILED -- claude: the Loom plugin is installed but its MCP server is not running (<reason>), so its tools will not be available. Fix that, then re-run setup. If this terminal predates the Loom installer, run `. "$HOME/.loom/env"` first.The last sentence is printed by v0.674 and later on Linux and macOS (not on Windows). It applies when you started loom setup in the same terminal as the installer: that terminal still has the old PATH, so the private uv is not found until you source ~/.loom/env.
<reason> is the status Claude Code printed for the server (for example ✘ Failed to connect — ENOENT: Executable not found in $PATH: "uv"), `no plugin:loom:loom entry in claude mcp list , or ` claude mcp list exited <code> `. If claude mcp list takes longer than 30 seconds (a cold uv cache can), setup does not fail: the row stays installed and verified with the note could not confirm the Loom MCP server started (timed out); re-run setup or check claude mcp list . Fix the cause (usually uv not on PATH) and re-run loom setup; it is safe to repeat. The restart line is still printed under a FAILED row, and loom setup` exits with status 3.
claude plugin marketplace add https://loomcloud.ai/loom-plugins.git
claude plugin install loom@loomThe supported plugin identity is loom@loom, from the marketplace named loom. The plugin bundles three things: the Loom MCP server, the Loom skills, and lifecycle hooks.
If git does not trust the server's self-signed certificate,
marketplace addfails withFailed to clone marketplace repository ... server certificate verification failed. Add the server's certificate to the operating system trust store (or use a certificate from a public or company CA); see Trust the server's certificate.
These checks need no login:
claude plugin list --jsonExpect exactly one loom@loom entry with "enabled": true.
claude -p hi --output-format stream-json --verbose --include-hook-eventsThe output should show SessionStart and UserPromptSubmit hook events from the plugin finishing with exit code 0, and the loom:loom-install skill in the session's slash commands. Without a login the command still prints the hook events but ends with Not logged in and exit status 1; that is expected here. This confirms the plugin and its hooks are wired up. It does not confirm the connection to your stores; use the steps below for that.
claude mcp listExpect plugin:loom:loom ... Connected once uv is on your PATH; loom setup v0.672 and later runs this same check. The MCP status in the -p init output is not final (it has read pending, connected and failed) even when claude mcp list says Connected; trust claude mcp list.
Run the bundled skill:
/loom:loom-installNot tested in a signed-in Claude Code session: running /loom:loom-install and its checks.
It checks the runtime, your ~/.loom/stores.toml, MCP startup, store connectivity, skills and hooks.
Run /hooks and confirm Loom appears with source Plugin under SessionStart, UserPromptSubmit, PreToolUse, PostToolUse and PreCompact.
Not tested in a signed-in Claude Code session: that the /hooks screen shows source Plugin for these events.
Ask your agent:
List my Loom stores and describe which store is the default.You should see the store names from your stores.toml and the configured default. See Concepts if the terms are new.
claude plugin marketplace update loom
claude plugin update loom@loomRestart Claude Code for the update to apply, start a fresh session, and rerun /loom:loom-install. A marketplace update alone does not verify the runtime or hook wiring. loom setup also performs the update when you re-run it.
claude plugin uninstall loom@loom
claude plugin marketplace remove loomThe second command is optional. Removing the plugin does not delete your account, your stores or ~/.loom/stores.toml.
The Claude package includes kanban_session_runner.py, which can make one fixed Claude session available as a scheduled Kanban worker. This is covered in the Kanban pages, not here.
/hooks shows no Loom entries: the plugin is not enabled, --bare was used, or disableAllHooks is true.uv is on the PATH of the shell that starts claude (claude mcp list shows the failure; from v0.672 loom setup reports it as its MCP server is not running).