Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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 @@ -80,6 +80,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 @@ -229,7 +229,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 All @@ -174,28 +213,28 @@ Every option is optional; Claude Code asks once, and an empty answer falls back

## 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 @@ -207,11 +246,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 @@ -221,12 +258,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 @@ -788,9 +788,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 @@ -708,6 +708,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 @@ -717,10 +718,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 @@ -730,11 +731,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