Skip to content
Merged
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
7 changes: 4 additions & 3 deletions .claude/rules/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,17 @@ paths:
- "integrations/**"
- "skills/**"
- ".claude-plugin/**"
- ".cursor-plugin/**"
---

# Integrations and coding-agent plugins

- Edit `integrations/claude-code-plugin/`, then `python -m scripts.codegen.agent_plugin_sync` copies its `hooks/*.mjs`, `bin/`, `lib/`, `skills/` and `assets/` to the Codex plugin; never edit a synced copy. Each plugin's manifest, `hooks/hooks.json` and `.mcp.json`, and the Codex `plugin-defaults.json`, differ on purpose and are edited in their own directory.
- A behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests (`integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json`) to a version no other open PR uses: two PRs with one version ship only the first.
- A behaviour change to any file the Claude Code or Codex plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) bumps both plugin manifests (`integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json`) to a version no other open PR uses: two PRs with one version ship only the first.
- A hook, `lib/` or `bin/` change that calls an op or a field the server does not serve yet says so in its changelog entry ("needs the next server release"), so the release notes list it: that release's pull request raises `MIN_SERVER_VERSION` in `lib/server-version.mjs` to its own version and bumps both plugin versions (clients get it only through a new version); a pull request on `main` before it never raises it (`tests/unit/test_codex_plugin.py` keeps it no newer than the server). Between such a hook's merge and that release, a server of the previous release gets no warning.
- Hooks run inside a user's session: they never throw to the agent, never block past their timeout, never print a token, and degrade to silence when the server is unreachable.
- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case.
- Before pushing, run the `integrations/` row of `loom-pre-push` §3, which lists every check CI runs here, and, for `.cursor-plugin/`, its own row; a change to a plugin skill also runs `claude plugin eval integrations/claude-code-plugin` ([evals](../../integrations/claude-code-plugin/evals/README.md)), and a new skill adds a case.
- Anything a hook sends to the server goes through `redactSecrets` / `redactHead`, redacting before truncating, and a diff through `diffHeaders`, which sends only its paths, hunk ranges and function names (`integrations/claude-code-plugin/lib/loom-client.mjs`); a new capture path that skips them is a finding.
- An integration or its README is held to an open-source bar: the happy path runs end to end as written; an experimental feature says so and names the versions it was tested on; an upstream bug is filed upstream and linked; a cheap CI check keeps the example from rotting.
- The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)).
- The root `skills/loom-code/` and `skills/loom/` skills are not synced: their version is `.claude-plugin/plugin.json` (and `.cursor-plugin/plugin.json`, whose plugin ships them) plus each `metadata.version`, released with the server; `skills/loom/` is also what `mentor.guide` serves, so the image copies it ([release process](../../docs/development/release-process.md#where-the-version-lives)).
- The skills here ship to users. Their text is prompt: every line costs tokens in every session, so keep them short and exact.
1 change: 1 addition & 0 deletions .claude/skills/loom-pre-push/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ Run them in the worktree's `.venv`, on CI's Python (3.12), with `LOOM_ENV_FILE=`
| server behaviour | the integration suite against a private server (`loom-dev-setup` §7) |
| auth, write paths, erasure, migrations, the worker supervisor | the per-module branch-coverage floors CI enforces: `make test-unit-cov` (about 30 minutes on two cores, less with more) |
| `integrations/`, `.claude-plugin/` | `.venv/bin/python -m scripts.codegen.agent_plugin_sync`; `claude plugin validate integrations/claude-code-plugin --profile directory --strict` and `claude plugin validate .` (the plugin and the marketplace listing); `node --test integrations/claude-code-plugin/tests/*.test.mjs`, `node --test integrations/grep-shim/tests/*.test.mjs`, `node --test integrations/cline/tests/*.test.mjs`, `bash integrations/cursor/test.sh`, `PYTHON=.venv/bin/python bash integrations/generic/test.sh`, and CI's loops: `node --check` over every hook, helper, shim and adapter `.mjs`, `sh -n` over `integrations/{claude-code-plugin,codex-plugin}/bin/loom-node` and `integrations/cline/hooks/*`, and `test -x` over `integrations/grep-shim/bin/*` and `integrations/cline/hooks/*` (job `agent-plugins` in `.github/workflows/ci.yml`); with `claude` or `codex` installed, `node integrations/claude-code-plugin/tests/e2e/agent-session.mjs claude --bin <path> --port <free port>` (`codex` needs port 7777 free, the URL its plugin ships; the other platforms run in `.github/workflows/plugin-platforms.yml`); for a behaviour change, both manifests bumped to a version no open PR uses |
| `.cursor-plugin/` | `.venv/bin/python -m pytest tests/unit/test_cursor_plugin.py tests/unit/test_release_prepare.py tests/unit/test_published_links.py`; its version follows the server's and is never bumped on its own |
| `frontend/` | `npm --prefix frontend run test && npm --prefix frontend run build && npm --prefix frontend run budget`; the Playwright run CI adds (`npx --prefix frontend playwright install chromium` once (its system libraries, `playwright install-deps`, only on a machine you own), then `E2E_PORT=<free port> npm --prefix frontend run e2e`); `make lint` covers the accessibility rules |
| `deploy/helm/` | the commands of CI's "lint and validate every overlay" step (`.github/workflows/ci.yml`, job `helm`): a `secrets.jwtSecret` of at least 32 characters (CI uses `openssl rand -hex 32`; `helm lint` passes a shorter one, the kind overlay's `helm template` refuses it), `helm lint --strict` and `helm template … \| kubeconform -strict -kubernetes-version 1.30.0` for each overlay, once more with every optional object on; then the job's `scripts/gates/helm_extractor_isolation.py`, `scripts/gates/helm_metadata_egress.py` and `scripts/gates/helm_assistant_isolation.py` |
| `extractor/`, `compose.yaml` | the extractor tests (`.venv/bin/python -m pytest tests/unit/test_extractor_service.py tests/unit/test_compose_extractor_service.py`), then push and read `docker-smoke.yml`'s Quickstart jobs, which build both images and run the installed stack's extractor probes; `dev/docker-compose.dev.yml` is checked by that compose test and `make dev`, no CI job runs it |
Expand Down
14 changes: 14 additions & 0 deletions .cursor-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"name": "clickhouse-loom",
"owner": { "name": "ClickHouse" },
"metadata": {
"description": "ClickHouse Loom: shared long-term memory and code intelligence for AI coding agents, self-hosted."
},
"plugins": [
{
"name": "clickhouse-loom",
"source": "./",
"description": "Shared long-term memory, document search and a code index for Cursor from a self-hosted Loom server, over MCP, with the loom and loom-code skills."
}
]
}
5 changes: 5 additions & 0 deletions .cursor-plugin/mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"mcpServers": {
"loom": { "url": "${LOOM_MCP_URL}" }
}
}
34 changes: 34 additions & 0 deletions .cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
{
"name": "clickhouse-loom",
"version": "1.2.0",
"displayName": "ClickHouse Loom",
"description": "Shared long-term memory, document search and a code index for Cursor from a self-hosted ClickHouse Loom server, over MCP, with the loom and loom-code skills that say when to recall, save and ask the code index. Not yet tested in Cursor.",
"author": { "name": "ClickHouse" },
"homepage": "https://clickhouse.github.io/loom/features/integrations/cursor/",
"repository": "https://github.com/ClickHouse/loom",
"license": "Apache-2.0",
"keywords": [
"agent-memory",
"long-term-memory",
"code-intelligence",
"code-search",
"mcp",
"clickhouse",
"self-hosted"
],
"logo": "integrations/claude-code-plugin/assets/icon.png",
"skills": "skills/",
"mcpServers": ".cursor-plugin/mcp.json",
"variables": {
"type": "object",
"properties": {
"LOOM_MCP_URL": {
"type": "string",
"title": "Loom MCP URL",
"description": "Your Loom server's MCP endpoint: http://localhost:7777/mcp?toolset=coding when each member runs a single-user server, or https://<your server>/mcp for a team server with browser sign-in",
"default": "http://localhost:7777/mcp?toolset=coding"
}
},
"required": ["LOOM_MCP_URL"]
}
}
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,11 @@ Start a new session; the first one connects to `http://localhost:7777`. In Codex
`codex` interactively once and approve the plugin's hooks; until then only the tools
work. Tell the agent something worth keeping, then ask about it in the next session.

For Cursor on the machine running a personal installation, the button below adds the
[local MCP entry](./docs/features/integrations/cursor.md#mcp-tools), which needs no token:
For Cursor, on a Teams or Enterprise plan, a team admin can import this repository as a
team marketplace; its [Cursor plugin](./docs/features/integrations/cursor.md#plugin),
untested in Cursor, installs the MCP entry and Loom's skills. On the machine running a
personal installation, the button below adds the [local MCP
entry](./docs/features/integrations/cursor.md#mcp-tools), which needs no token:

[![Add Loom to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=loom&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojc3NzcvbWNwP3Rvb2xzZXQ9Y29kaW5nIn0%3D)

Expand Down
Loading
Loading