Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
9fd551d
Claude Code uses a complete MCP endpoint
zlareb1 Nov 16, 2026
30a5166
Quote the complete single-user plugin endpoint
zlareb1 Nov 16, 2026
bda34b8
Plugin disclosures include native checkout context
zlareb1 Nov 16, 2026
17d5a6b
The config comment describes endpoint-selected destinations
zlareb1 Nov 17, 2026
26f06b1
Match plugin setup guidance to the complete endpoint
zlareb1 Nov 17, 2026
b55f7af
Describe repository lookup request timeouts accurately
zlareb1 Nov 17, 2026
342ffe3
Keep the configured endpoint as a valid destination
zlareb1 Nov 17, 2026
354cf75
Preserve resolved proxy paths during agent signup
zlareb1 Nov 17, 2026
b7ac426
Preserve base URL options in generic session hooks
zlareb1 Nov 17, 2026
45eb490
Status refuses invalid saved endpoint configuration
zlareb1 Nov 17, 2026
cd68d12
Endpoint defaults and diagnostics preserve literal proxy paths
zlareb1 Nov 17, 2026
647e1ad
Use bounded projected Windows process identity queries
zlareb1 Nov 17, 2026
c7943b8
Read Windows process identity through the native script host
zlareb1 Nov 17, 2026
f38f8a6
Resolve the Windows identity host from the OS system directory
zlareb1 Nov 17, 2026
82b2a36
Compose endpoint configuration with current plugin manifests
zlareb1 Nov 18, 2026
b57023a
Missing client identities skip context polling
zlareb1 Nov 18, 2026
40d9305
Review plugin sender provenance for configured endpoints
zlareb1 Nov 18, 2026
42215d2
Compose plugin endpoints with hook labels
zlareb1 Nov 18, 2026
814c126
Report clocks and child exits for shunt test failures
zlareb1 Nov 18, 2026
84e3f92
Format shunt child-result diagnostics
zlareb1 Nov 18, 2026
464243a
Report scope-pair classes for endpoint test failures
zlareb1 Nov 18, 2026
5576b7b
Merge main and preserve configured plugin endpoints
zlareb1 Nov 20, 2026
96be03c
Replicated erasure fixtures provide isolated write leases
zlareb1 Nov 20, 2026
4aec26f
Hooks use the configured complete MCP endpoint
zlareb1 Nov 20, 2026
f4d5a40
Compose isolated lease fixtures with the endpoint change
zlareb1 Nov 20, 2026
2e6c25c
Use the replicated-erasure fixture supplied by main
zlareb1 Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/plugin-platforms.yml
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,9 @@ jobs:
- name: Claude Code session
if: ${{ !cancelled() }}
run: node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin "$CLAUDE_BIN" --expect-tool Bash
- name: Claude Code endpoint and concurrent checkout scopes
if: ${{ !cancelled() }}
run: node integrations/claude-code-plugin/tests/e2e/claude-endpoint.mjs "$CLAUDE_BIN"
- name: Codex session
if: ${{ !cancelled() }}
run: node integrations/claude-code-plugin/tests/e2e/agent-session.mjs codex --bin "$CODEX_BIN"
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ which needs no token:
[![Add Loom to VS Code](https://img.shields.io/badge/VS_Code-Add_Loom-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522loom%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522http%253A%252F%252Flocalhost%253A7777%252Fmcp%2522%257D)
[![Add Loom to VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Add_Loom-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522loom%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522http%253A%252F%252Flocalhost%253A7777%252Fmcp%2522%257D)

For a team server, pass `--config server_url=… --config token=…` to Claude Code, or
For a team server, pass `--config "server_url=https://<loom>/mcp?toolset=coding" --config token=…` to Claude Code, or
point Codex at it as described in
[connect a coding agent](./docs/getting-started/connect-a-coding-agent.md). Create
tokens in **Settings → Tokens**. Cursor and other MCP clients, and
Expand Down
94 changes: 72 additions & 22 deletions docs/features/integrations/claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,39 @@ day. They can remain longer, especially when no new session starts. The log of w
tool calls the plugin redirected or let through (no prompt or file content) stays until
you remove it (`LOOM_SHUNT_LOG=off` stops it).

Claude Code's SessionStart also writes `loom-mcp-project-<hash>.json` in the system
temp directory (normally `/tmp/loom-mcp-project-<hash>.json` on Linux), mode 0600.
It holds the checkout's absolute working directory, session ID, native client PID,
parent PID, process name and OS process creation marker. It contains no credential
or transcript. The MCP header helper uses it to find this client's checkout and
code namespace. It survives SessionEnd; a later SessionStart tries to prune it after
one day without a write. This is best-effort cleanup, with no deletion deadline.
Codex does not write or read this artifact.

To match that native client identity, Claude Code reads `/proc/<pid>/stat` and
`/proc/sys/kernel/random/boot_id` on Linux. On macOS it runs:

```sh
ps -p <pid> -o ppid= -o lstart= -o ucomm=
```

On Windows it resolves `System32\cscript.exe` under the absolute, drive-qualified
`SystemRoot` from the parent OS environment. It runs that host with
`//nologo //E:JScript //B`, the plugin's `assets/mcp-project-win32.js` file and the
validated PID as separate arguments. Missing or malformed `SystemRoot` supplies
no scope; the executable is never searched for in the checkout.
That static helper queries local WMI for `Name`, `ParentProcessId` and `CreationDate`.
It requires exactly one result and returns the name, parent PID and an exact UTC
FILETIME creation marker. A blocked script host or WMI query supplies no checkout
scope; the plugin does not enable components or change scripting policy.

Each subprocess has a one-second timeout and a 16 KiB output limit. These queries
read the process name, parent PID and creation marker, without collecting process
command lines or environments. The header helper checks at most three ancestors,
through known shells to the nearest client, and waits nominally 1.5 seconds for its
checkout context; one process query can finish after that interval. Codex's fixed
MCP entry skips these process queries.

Two skills reach other services, each only when you ask for it. The `loom-status` skill
can install Node.js from NodeSource through apt, dnf or yum, or from apk or Homebrew, and
runs that installer only after you agree. The `improve-loom-for-my-repo` skill searches
Expand Down Expand Up @@ -143,23 +176,29 @@ In short:
```bash
claude plugin marketplace add ClickHouse/loom # or a path to a local clone
claude plugin install loom@loom \
--config server_url=https://loom.example.com \
--config "server_url=https://loom.example.com/mcp?toolset=coding" \
--config token=<writer JWT>
```

Install either this plugin or `loom-code-skill`, not both; the plugin already ships the
`loom-code` skill. Update with `claude plugin update loom@loom`: hooks ship with the
plugin, not the server.

| Option | Default | Meaning |
| ------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------- |
| `server_url` | `$LOOM_BASE_URL`, else `http://localhost:7777` | Loom base URL, no trailing slash |
| `token` | empty | a writer JWT, stored as a sensitive value |
| `toolset` | `coding` | the MCP listing (`?toolset=`), e.g. `coding+tracker`; every op stays callable by name |
| `local_first` | `false` | `true` stands the code shunt down (same as `LOOM_CODE_LOCAL_FIRST=on`) |
| Option | Default | Meaning |
| ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `server_url` | `$LOOM_BASE_URL/mcp?toolset=coding`, else `http://localhost:7777/mcp?toolset=coding` | Full MCP endpoint; include the proxy prefix and desired toolset |
| `token` | empty | a writer JWT, stored as a sensitive value |
| `local_first` | `false` | `true` stands the code shunt down (same as `LOOM_CODE_LOCAL_FIRST=on`) |

Every option is optional; Claude Code asks once, and an empty answer falls back to the
[lookups below](#configuration).
The endpoint query chooses the listing, for example `?toolset=coding+tracker`. Without
a recognized toolset the server chooses its configured default. The hooks do not infer that default.

An origin-only `server_url` needs reconfiguration with `/mcp?toolset=coding` appended
(after any proxy prefix). Hooks report the required endpoint and refuse network work
until it is valid. Claude Code can still attempt an unauthenticated MCP connection.

Claude Code asks once for optional settings. Keep the default endpoint or supply a
complete URL. An empty token uses the [lookups below](#configuration).

- **Install token.** The MCP header helper cannot see install options, so the first hook
of a session copies the token and URL into `~/.loom/config.json` (0600). It does so only
Expand Down Expand Up @@ -338,28 +377,28 @@ hook matching, request execution, nonempty context and delivery to the agent.

## Configuration

**Where the hooks find the server and the identity.** Environment first, then the install
option, then `~/.loom/config.json`, then the token's claims, then the defaults
(`lib/loom-client.mjs`: `resolveServerUrl`, `resolveToken`, `resolveScope`):
**Where the hooks find the server and the identity.** The MCP endpoint selects the
control-plane base, including its proxy prefix. Credentials and identity follow the
lookups below (`lib/loom-client.mjs`):

| What | Lookup order |
| --------- | -------------------------------------------------------------------------------------------------------- |
| server | `LOOM_BASE_URL` → `server_url` option → `config.json` `url` → `http://localhost:7777` |
| server | the base of `server_url`; its default uses `LOOM_BASE_URL`, else `http://localhost:7777` |
| token | `LOOM_API_KEY` → `token` option → `config.json` `token` → `~/.loom/token` (moved by `LOOM_API_KEY_FILE`) |
| org | `LOOM_ORG` → `config.json` `org` → the token's `org` claim → `default` |
| namespace | `LOOM_NAMESPACE` → `config.json` `namespace` → the token's first non-wildcard namespace → `coding` |
| agent | `LOOM_AGENT` → `config.json` `agent` → `claude-code` |

For a remote server the hooks and the header helper need only one file
Store the remote server's token in one file for the hooks, helper and CLI
(`LOOM_CONFIG_FILE` moves it):

```json
{ "url": "https://loom.example.com", "token": "<writer JWT>", "namespace": "my-team" }
```

The MCP entry does not read it: its URL is the `server_url` install option, whose
default is `LOOM_BASE_URL`, else localhost. Set one of those too, or the entry sends the
file's token to localhost and the primer says so.
default appends `/mcp?toolset=coding` to `LOOM_BASE_URL`, else localhost. Set the
endpoint too; a config file alone does not select the plugin's destination.

**Project scoping.** The project is the basename of the git toplevel
(`LOOM_PROJECT_NAME` overrides it). With the default `LOOM_PROJECT_SCOPE=tag`, every
Expand All @@ -371,11 +410,9 @@ not share memory.

## The MCP entry and its header helper

The plugin's `.mcp.json` points at `<server_url>/mcp?toolset=<toolset>` and gets its
headers from `bin/loom-mcp-headers.mjs`. Claude Code runs the helper in the plugin root,
so the URL ends in `#${CLAUDE_PROJECT_DIR}`: Claude Code hands the helper the URL with the
project directory filled in, and never sends the fragment to the server. The helper
sends:
The plugin's `.mcp.json` uses the complete `server_url` value. The header helper runs
in the plugin root, so it reads checkout context from SessionStart's private state
rather than its working directory. It sends:

- `Authorization: Bearer <token>`, from the same lookup as the hooks except the install
option (see above). With no token, the helper performs the same first-session sign-up
Expand All @@ -385,12 +422,25 @@ sends:
resolves to. The server applies it to every `code.*` call that names no namespace, so
the model does not have to pass one. `LOOM_MCP_CODE_SCOPE=off` disables it.

The MCP header helper uses the latest SessionStart checkout directory, held with
the session identifier, client PID, parent PID, process name and OS process creation
marker in a private temporary file. This file contains no token and survives session
end. It is keyed to the client process's creation identity. The helper checks only
its own live process ancestors and waits for a
bounded interval. An unavailable process identity, missing context, unindexed checkout
or failed repository lookup leaves the connection without an implicit code scope;
pass org and namespace explicitly in that case. A helper error does not prevent
Claude Code from attempting an MCP connection. A later SessionStart attempts to
remove state files untouched for a day.

The checkout's repository is found from its remotes (`origin`, then `upstream`, then the
rest) through `code.repos`. A GitHub fork with no index of its own resolves to its
parent's index when you can read it. `LOOM_CODE_REPO=<owner>/<name>` or a bare name (or
the `code_repo` option, or `code_repo` in `~/.loom/config.json`) is the fallback candidate
after the remotes: it serves a session outside any git checkout, or a checkout with no
index, and gives it that repository's index and scope header. The helper's own lookup is bounded at 2.5 s; a miss costs only the header.
index, and gives it that repository's index and scope header. The repository lookup
uses request timeouts, separately from the local context wait; a miss leaves the
scope header absent.
See [code index overview](../code-index/overview.md) and the
[MCP reference](../../reference/mcp.md) for how the server uses the scope.

Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/connect-a-coding-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ tools to save and search facts.
```bash
claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom \
--config server_url=https://loom.example.com \
--config "server_url=https://loom.example.com/mcp?toolset=coding" \
--config token=<writer JWT>
```

Expand Down
5 changes: 3 additions & 2 deletions docs/operations/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -827,9 +827,10 @@ and what it leaves:
`code.symbol`) lists code tools that refuse. The plugins, `loom install` for Claude Code,
Codex and Cursor, the lines `loom up` and `loom init` print, and the dashboard's Claude Code,
Codex and Cursor snippets ask for `coding`. Point those entries at `core` (with `tasks`
added where agents use the task inbox): the Claude Code plugin's `toolset` option
added where agents use the task inbox): set `?toolset=core` in the Claude Code
plugin's complete `server_url` option, keeping any proxy prefix before `/mcp`
([options](../features/integrations/claude-code.md#install)),
`loom install --toolset core`, or for the Codex plugin a `[mcp_servers.loom]` override in
run `loom install --toolset core`, or for the Codex plugin use a `[mcp_servers.loom]` override in
`~/.codex/config.toml` that keeps the plugin's `http_headers_helper` line, since the
override replaces the entry whole
([the server](../features/integrations/codex.md#the-server)).
Expand Down
2 changes: 1 addition & 1 deletion frontend/src/components/ConnectAgentDialog.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ export function ConnectAgentDialog({ open, onOpenChange }: { open: boolean; onOp

/** A single-user server takes no token: the plugin needs only the address. */
export function AuthOffConnect({ instructionsId }: { instructionsId?: string }) {
const lines = `${pluginInstallLines("claude-code")} --config server_url=${window.location.origin}`;
const lines = `${pluginInstallLines("claude-code")} --config "server_url=${window.location.origin}/mcp?toolset=coding"`;
return (
<div className="mt-2">
<p id={instructionsId} tabIndex={instructionsId ? -1 : undefined} className="text-xs text-text-muted mb-1">
Expand Down
6 changes: 5 additions & 1 deletion frontend/src/components/GettingStarted.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -490,7 +490,11 @@ describe("GettingStarted on Memories", () => {
render(<Recent />);
const panel = await screen.findByRole("region", { name: "Getting started" }, WAIT);
expect(
await within(panel).findByText(/claude plugin install loom@loom --config server_url=/, undefined, WAIT),
await within(panel).findByText(
/claude plugin install loom@loom --config "server_url=\S+\/mcp\?toolset=coding"/,
undefined,
WAIT,
),
).toBeInTheDocument();
expect(within(panel).queryByRole("button", { name: "Create a token" })).toBeNull();
await userEvent.click(await within(panel).findByRole("button", { name: "Open Models & keys" }, WAIT));
Expand Down
3 changes: 3 additions & 0 deletions frontend/src/views/Tokens.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -580,6 +580,9 @@ describe("the token form", () => {
);
expect(screen.getByLabelText(/^Connect/)).toHaveTextContent("Claude Code");
expect(screen.getByTestId("claude-code-recommended")).toBeInTheDocument();
expect(screen.getByTestId("claude-code-recommended")).toHaveTextContent(
"server_url=http://loom.test/mcp?toolset=coding",
);
});

it("the result of a `*` token whose claim names a collection names it, and no other", async () => {
Expand Down
5 changes: 3 additions & 2 deletions frontend/src/views/Tokens.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ import {
formatMcpConfig,
isClientId,
pluginInstallLines,
withToolset,
type ClientId,
} from "../lib/clients";
import {
Expand Down Expand Up @@ -1213,15 +1214,15 @@ function ClientConnect({ client, token, mcpUrl }: { client: ClientId; token: str
(chmod 600):
</div>
<CodeBlock
text={JSON.stringify({ url: mcpUrl.replace(/\/mcp$/, ""), token }, null, 2)}
text={JSON.stringify({ url: mcpUrl.replace(/\/mcp(?:\?.*)?$/, ""), token }, null, 2)}
label="Copy"
ariaLabel="Copy config.json"
/>
<div className="text-xs text-text-muted leading-relaxed">
2. Install the plugin; it mounts the Loom tools itself and reads that file. Leave the token prompt empty.
</div>
<pre className="text-xs font-mono bg-surface-2 rounded-lg p-3 overflow-auto whitespace-pre-wrap">
{pluginInstallLines("claude-code") || ""}
{`${pluginInstallLines("claude-code")} --config "server_url=${withToolset(mcpUrl, "coding")}"`}
</pre>
<div className="text-xs text-text-muted leading-relaxed pt-1 border-t border-border">
<span className="font-medium text-text">Tools only, no hooks:</span> register the server below instead. Pick
Expand Down
9 changes: 5 additions & 4 deletions install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -723,6 +723,7 @@ main() {
server_url=http://localhost:$port
[ "$host" = 127.0.0.1 ] || server_url=http://$host:$port
# The plugins' own server URL, which a plugin installed before keeps.
claude_endpoint="$server_url/mcp?toolset=coding"
default_url=http://localhost:7777
if considered claude-code && command -v claude >/dev/null 2>&1; then
claude_config="${CLAUDE_CONFIG_DIR:-${HOME:-}}/.claude.json"
Expand All @@ -732,10 +733,10 @@ main() {
if ! bounded 60 claude plugin list >"$tmp_dir/claude.plugins"; then
printf 'Claude Code: could not list its plugins (above), so it is left as it is\n'
elif grep -Eq '(^|[[:space:]])loom@loom$' "$tmp_dir/claude.plugins"; then
printf 'Claude Code: the Loom plugin is installed already; `claude mcp list` shows the server it uses, and `claude plugin install loom@loom --config server_url=%s` points it here\n' "$server_url"
printf 'Claude Code: the Loom plugin is installed already; `claude mcp list` shows the server it uses, and `claude plugin install loom@loom --config "server_url=%s"` points it here\n' "$claude_endpoint"
kept=1
elif grep -q '"loom"[[:space:]]*:' "$claude_config" 2>/dev/null; then
printf 'Claude Code: a loom MCP server is set up already, for every project or for one (%s), and is left as it is; to use the plugin instead: claude mcp remove loom, then claude plugin install loom@loom --config server_url=%s\n' "$claude_config" "$server_url"
printf 'Claude Code: a loom MCP server is set up already, for every project or for one (%s), and is left as it is; to use the plugin instead: claude mcp remove loom, then claude plugin install loom@loom --config "server_url=%s"\n' "$claude_config" "$claude_endpoint"
kept=1
elif ! node_ok; then
# Its hooks and MCP header helper run the `node` on PATH, with no search.
Expand All @@ -745,11 +746,11 @@ main() {
# It clones the repository: the slowest call, so it gets 5 minutes.
bounded 300 claude plugin marketplace add ClickHouse/loom >/dev/null || true
# The URL is always given: the plugin's default reads LOOM_BASE_URL.
if bounded 60 claude plugin install loom@loom --config "server_url=$server_url" >/dev/null; then
if bounded 60 claude plugin install loom@loom --config "server_url=$claude_endpoint" >/dev/null; then
printf 'Claude Code: connected to %s (the plugin'"'"'s other settings are optional)\n' "$server_url"
agents="$agents, Claude Code"
else
printf 'Claude Code: could not install the plugin (above); to try again: claude plugin marketplace add ClickHouse/loom; claude plugin install loom@loom --config server_url=%s\n' "$server_url"
printf 'Claude Code: could not install the plugin (above); to try again: claude plugin marketplace add ClickHouse/loom; claude plugin install loom@loom --config "server_url=%s"\n' "$claude_endpoint"
fi
fi
fi
Expand Down
Loading
Loading