diff --git a/.claude/rules/plugins.md b/.claude/rules/plugins.md index ae47b1882a..69c11d531b 100644 --- a/.claude/rules/plugins.md +++ b/.claude/rules/plugins.md @@ -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. diff --git a/.claude/skills/loom-pre-push/SKILL.md b/.claude/skills/loom-pre-push/SKILL.md index fc001d9891..4ca1c8da67 100644 --- a/.claude/skills/loom-pre-push/SKILL.md +++ b/.claude/skills/loom-pre-push/SKILL.md @@ -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 --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= 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 | diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json new file mode 100644 index 0000000000..67f4d551dd --- /dev/null +++ b/.cursor-plugin/marketplace.json @@ -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." + } + ] +} diff --git a/.cursor-plugin/mcp.json b/.cursor-plugin/mcp.json new file mode 100644 index 0000000000..bc984f141a --- /dev/null +++ b/.cursor-plugin/mcp.json @@ -0,0 +1,5 @@ +{ + "mcpServers": { + "loom": { "url": "${LOOM_MCP_URL}" } + } +} diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json new file mode 100644 index 0000000000..781d520dca --- /dev/null +++ b/.cursor-plugin/plugin.json @@ -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:///mcp for a team server with browser sign-in", + "default": "http://localhost:7777/mcp?toolset=coding" + } + }, + "required": ["LOOM_MCP_URL"] + } +} diff --git a/README.md b/README.md index f9d38477cf..3b3509b270 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/development/release-process.md b/docs/development/release-process.md index a4b8cff85f..4f6fef661f 100644 --- a/docs/development/release-process.md +++ b/docs/development/release-process.md @@ -1,21 +1,21 @@ # Release process -Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`) and the Gemini CLI extension share one version `X.Y.Z`. The two coding-agent plugins share their own version, bumped on a behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`): installed clients pick up a hook change only through a new plugin version. `MIN_SERVER_VERSION` in the plugins' `lib/server-version.mjs` names the oldest server their hooks support: when the server's `GET /v1/health` reports an older `version`, SessionStart prints one `loom:` line asking for a server upgrade, and says nothing when the version cannot be read. It rises with a release ([cutting the release](#cutting-the-release), step 2). +Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin that ships them and the Gemini CLI extension share one version `X.Y.Z`. The Claude Code and Codex plugins share their own version, bumped on a behaviour change to any file the plugin ships (`hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`): installed clients pick up a hook change only through a new plugin version. `MIN_SERVER_VERSION` in the plugins' `lib/server-version.mjs` names the oldest server their hooks support: when the server's `GET /v1/health` reports an older `version`, SessionStart prints one `loom:` line asking for a server upgrade, and says nothing when the version cannot be read. It rises with a release ([cutting the release](#cutting-the-release), step 2). ## Where the version lives -`.venv/bin/python scripts/release/prepare.py bump X.Y.Z` bumps each of these in the release commit, except the plugins, and writes the [release notes](#release-notes): +`.venv/bin/python scripts/release/prepare.py bump X.Y.Z` bumps each of these in the release commit, except the Claude Code and Codex plugins, and writes the [release notes](#release-notes): -| Component | Files | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Server | `server/__init__.py` (`__version__`), `pyproject.toml`, `uv.lock` and `server.json` | -| Python SDK | `sdk/python/pyproject.toml` and `sdk/python/loom/_version.py` | -| TypeScript SDK | `sdk/typescript/package.json`, `sdk/typescript/package-lock.json`, `sdk/typescript/src/version.ts` | -| Web app | `frontend/package.json` and `frontend/package-lock.json` | -| Root skills | `.claude-plugin/plugin.json` and the `metadata.version` of `skills/loom-code/SKILL.md` and `skills/loom/SKILL.md` | -| Gemini CLI extension | `gemini-extension.json` | -| Helm chart | `deploy/helm/loom/Chart.yaml`: `appVersion` (the default tag of the server and extractor images, and the chart's `app.kubernetes.io/version` label) and the chart's own `version`: a minor for a major or minor release, a patch for a patch release | -| Coding-agent plugins | `integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json` (their own version; bump it on a behaviour change to any file the plugin ships: `hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) | +| Component | Files | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Server | `server/__init__.py` (`__version__`), `pyproject.toml`, `uv.lock` and `server.json` | +| Python SDK | `sdk/python/pyproject.toml` and `sdk/python/loom/_version.py` | +| TypeScript SDK | `sdk/typescript/package.json`, `sdk/typescript/package-lock.json`, `sdk/typescript/src/version.ts` | +| Web app | `frontend/package.json` and `frontend/package-lock.json` | +| Root skills | `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json` and the `metadata.version` of `skills/loom-code/SKILL.md` and `skills/loom/SKILL.md` | +| Gemini CLI extension | `gemini-extension.json` | +| Helm chart | `deploy/helm/loom/Chart.yaml`: `appVersion` (the default tag of the server and extractor images, and the chart's `app.kubernetes.io/version` label) and the chart's own `version`: a minor for a major or minor release, a patch for a patch release | +| Claude Code and Codex plugins | `integrations/claude-code-plugin/.claude-plugin/plugin.json`, `integrations/codex-plugin/.codex-plugin/plugin.json` (their own version; bump it on a behaviour change to any file the plugin ships: `hooks/`, `lib/`, `bin/`, `skills/`, `.mcp.json`, the Codex `plugin-defaults.json`) | The server reads its version from `server/__init__.py` only; the OpenAPI document, MCP `serverInfo`, `loom report` and `GET /v1/health` (checked by `tests/unit/test_health_problems.py`) report it. These checks keep the numbers consistent: @@ -390,6 +390,7 @@ Agents and people find Loom through these listings. Each reads files in this rep | npm page of `@clickhouse/loom` | the metadata of `sdk/typescript/package.json`, and `sdk/typescript/README.md` as the page body | the `npm` job on each dispatched release; the page shows the version tagged `latest`, which the job sets only for the highest final | | Claude plugin directory | `integrations/claude-code-plugin/.claude-plugin/plugin.json` (`displayName`, `description`, `keywords`, `icon`, `documentationUrl`, `supportUrl`, `privacyPolicyUrl`) and the README | submitted once in the developer portal; later versions are picked up from the tracked branch. The icon is read only on the first submission | | Claude Code plugin suggestions | the `relevance` block of the `loom` entry in `.claude-plugin/marketplace.json`: the `loom` command, Loom's config files, an SDK dependency in a manifest | read from the marketplace on the default branch; shown only where an administrator allowlists the marketplace (`pluginSuggestionMarketplaces`) | +| Cursor Marketplace | `.cursor-plugin/plugin.json` (`displayName`, `description`, `keywords`, `logo`, `variables`), `.cursor-plugin/marketplace.json` | not submitted; a submission at cursor.com/marketplace/publish is reviewed by hand, and so is each update | | Codex plugin directory | `integrations/codex-plugin/.codex-plugin/plugin.json` (`interface`) | submitted in the plugin portal; a plugin with lifecycle hooks is not eligible there, so the public listing needs a build without them | | Docs index for coding agents | `context7.json` | refreshed from the default branch after the repository is added once | | Agent Skills index | `skills/loom-code`, `skills/loom` and the Claude Code plugin's skills; the contributor skills are marked internal in their frontmatter and are not offered | ranked by `npx skills add ClickHouse/loom` installs; nothing to submit | diff --git a/docs/development/repository-guide.md b/docs/development/repository-guide.md index 018b5a8a46..5fb5570c85 100644 --- a/docs/development/repository-guide.md +++ b/docs/development/repository-guide.md @@ -4,31 +4,31 @@ What every top-level directory holds, where a concern lives inside `server/`, th ## Top-level layout -| Path | Holds | -| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `server/` | the FastAPI server: domain packages (memory, code, tracker, …), the operation registry, workers, transports, CLI, settings | -| `extractor/` | the reference extractor service (`loom_extractor/`): format detection and the document parsers, run outside the server; its image (`Dockerfile`, released as `ghcr.io/clickhouse/loom-extractor`) and lock (`uv.lock`); see [document extraction](../architecture/document-extraction.md) | -| `sdk/python/` | the Python SDK, published as `clickhouse-loom` (`sdk/python/loom/`) | -| `sdk/typescript/` | the TypeScript SDK, published as `@clickhouse/loom` (`sdk/typescript/src/`) | -| `frontend/` | the React dashboard served at `/` (Vite + Tailwind); `src/`, Playwright specs in `e2e/`, `scripts/bundle_budget.mjs` | -| `schemas/` | `migrations/` (numbered SQL), `schema.sql` (generated current shape), `otel/` (ClickStack OTel tables), `ops/` (hand-run SQL); see [`schemas/README.md`](../../schemas/README.md) | -| `dev/` | compose stacks, operator scripts (`loom_ingest.py`, `loom_init.py`, `onboard_tenant.py`, backup and restore, `verify_audit_chain.py`), `ci_start_clickhouse.sh`, `redeploy_preflight.sh` | -| `deploy/` | ClickHouse server config (`clickhouse-config/`), the Lemmagen3 model (`lemmagen3/`), the blue/green proxy (`proxy/`), the Helm chart (`helm/`), the repository-job sandbox AppArmor profile (`apparmor/`), the standalone env template (`standalone/`), the scheduled namespace copy CronJob (`okf-sync/`), dashboards (`dashboards/`, `hyperdx_dashboards.md`, `clickstack_sources.sh`) | -| `bench/` | benchmark harnesses and gates, their fixtures (`fixtures/`), datasets, rubrics, acceptance and skill evals; see [benchmarks](../benchmarks/overview.md) | -| `integrations/` | client integrations: the Claude Code and Codex plugins, the Cline hooks, the grep shim, Cursor and generic transcript hooks, the OKF CI gate | -| `skills/` | the standalone Agent Skills: `loom-code`, and `loom` (the agent guide the server image ships and `mentor.guide` serves) | -| `scripts/` | `codegen/` (generators), `gates/` (CI ratchets and guards), `ops/` (operator tools), `scip_harness/` (compiler-tier producers), `docs_site/` (the documentation site's hook, theme override, pinned builder and IndexNow submission), `i18n/` (the translation generator and its freshness check) | -| `tests/` | `unit/`, `integration/`, `analyzer/`, `code_lanes/`, `fixtures/` (below) | -| `examples/` | runnable integration examples (`claude_agent_loop.py`, `ledger_run.py`, `log_conversation.py`, `onboarding_walkthrough.py`), and the course starter a teacher copies into a repository of their own (`course-starter/`, [teaching](../guides/teaching.md#hand-out-the-labs-as-an-assignment)) | -| `i18n/` | machine translations of the README, the quickstart and the use-case pages into six languages, one folder per language; generated by `scripts/i18n/translate.py` (`.github/workflows/i18n.yml`), never edited by hand | -| `docs/` | this documentation; `mkdocs.yml` and `scripts/docs_site/` build it as the documentation site (`.github/workflows/docs-site.yml`) | -| `.github/` | CI, release and scan workflows (`workflows/`), issue and pull-request templates, and `social-preview.png`, the image uploaded in Settings → General → Social preview (GitHub reads only the uploaded copy) | -| `.devcontainer/` | the GitHub Codespaces try-out: a dev container that installs the latest release with the installer and connects Claude Code; not a development environment ([quickstart](../getting-started/quickstart.md#try-it-in-github-codespaces)) | -| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock` | the server's image, the task runner, the blue/green deploy script, the server package and its lock file | -| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.agents/plugins/` | the MCP Registry listing, the docs-index config, the citation GitHub shows as "Cite this repository", the Gemini CLI extension manifest, the Claude Code marketplace with the `loom-code` skill manifest, the Codex marketplace | -| `llms-install.md` | the steps a coding agent follows to install Loom and add it as an MCP server | -| `AGENTS.md`, `CLAUDE.md` | the instructions every coding agent reads; `CLAUDE.md` imports `AGENTS.md` | -| `.claude/`, `.agents/skills/` | the agents' skills, path-scoped rules, the read-only reviewer subagent and its hook, and project permission settings; `.agents/skills/` links each skill for Codex | +| Path | Holds | +| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `server/` | the FastAPI server: domain packages (memory, code, tracker, …), the operation registry, workers, transports, CLI, settings | +| `extractor/` | the reference extractor service (`loom_extractor/`): format detection and the document parsers, run outside the server; its image (`Dockerfile`, released as `ghcr.io/clickhouse/loom-extractor`) and lock (`uv.lock`); see [document extraction](../architecture/document-extraction.md) | +| `sdk/python/` | the Python SDK, published as `clickhouse-loom` (`sdk/python/loom/`) | +| `sdk/typescript/` | the TypeScript SDK, published as `@clickhouse/loom` (`sdk/typescript/src/`) | +| `frontend/` | the React dashboard served at `/` (Vite + Tailwind); `src/`, Playwright specs in `e2e/`, `scripts/bundle_budget.mjs` | +| `schemas/` | `migrations/` (numbered SQL), `schema.sql` (generated current shape), `otel/` (ClickStack OTel tables), `ops/` (hand-run SQL); see [`schemas/README.md`](../../schemas/README.md) | +| `dev/` | compose stacks, operator scripts (`loom_ingest.py`, `loom_init.py`, `onboard_tenant.py`, backup and restore, `verify_audit_chain.py`), `ci_start_clickhouse.sh`, `redeploy_preflight.sh` | +| `deploy/` | ClickHouse server config (`clickhouse-config/`), the Lemmagen3 model (`lemmagen3/`), the blue/green proxy (`proxy/`), the Helm chart (`helm/`), the repository-job sandbox AppArmor profile (`apparmor/`), the standalone env template (`standalone/`), the scheduled namespace copy CronJob (`okf-sync/`), dashboards (`dashboards/`, `hyperdx_dashboards.md`, `clickstack_sources.sh`) | +| `bench/` | benchmark harnesses and gates, their fixtures (`fixtures/`), datasets, rubrics, acceptance and skill evals; see [benchmarks](../benchmarks/overview.md) | +| `integrations/` | client integrations: the Claude Code and Codex plugins, the Cline hooks, the grep shim, Cursor and generic transcript hooks, the OKF CI gate | +| `skills/` | the standalone Agent Skills: `loom-code`, and `loom` (the agent guide the server image ships and `mentor.guide` serves) | +| `scripts/` | `codegen/` (generators), `gates/` (CI ratchets and guards), `ops/` (operator tools), `scip_harness/` (compiler-tier producers), `docs_site/` (the documentation site's hook, theme override, pinned builder and IndexNow submission), `i18n/` (the translation generator and its freshness check) | +| `tests/` | `unit/`, `integration/`, `analyzer/`, `code_lanes/`, `fixtures/` (below) | +| `examples/` | runnable integration examples (`claude_agent_loop.py`, `ledger_run.py`, `log_conversation.py`, `onboarding_walkthrough.py`), and the course starter a teacher copies into a repository of their own (`course-starter/`, [teaching](../guides/teaching.md#hand-out-the-labs-as-an-assignment)) | +| `i18n/` | machine translations of the README, the quickstart and the use-case pages into six languages, one folder per language; generated by `scripts/i18n/translate.py` (`.github/workflows/i18n.yml`), never edited by hand | +| `docs/` | this documentation; `mkdocs.yml` and `scripts/docs_site/` build it as the documentation site (`.github/workflows/docs-site.yml`) | +| `.github/` | CI, release and scan workflows (`workflows/`), issue and pull-request templates, and `social-preview.png`, the image uploaded in Settings → General → Social preview (GitHub reads only the uploaded copy) | +| `.devcontainer/` | the GitHub Codespaces try-out: a dev container that installs the latest release with the installer and connects Claude Code; not a development environment ([quickstart](../getting-started/quickstart.md#try-it-in-github-codespaces)) | +| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock` | the server's image, the task runner, the blue/green deploy script, the server package and its lock file | +| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.cursor-plugin/`, `.agents/plugins/` | the MCP Registry listing, the docs-index config, the citation GitHub shows as "Cite this repository", the Gemini CLI extension manifest, the Claude Code marketplace with the `loom-code` skill manifest, the Cursor marketplace and plugin, the Codex marketplace | +| `llms-install.md` | the steps a coding agent follows to install Loom and add it as an MCP server | +| `AGENTS.md`, `CLAUDE.md` | the instructions every coding agent reads; `CLAUDE.md` imports `AGENTS.md` | +| `.claude/`, `.agents/skills/` | the agents' skills, path-scoped rules, the read-only reviewer subagent and its hook, and project permission settings; `.agents/skills/` links each skill for Codex | ## Inside server/ diff --git a/docs/features/integrations/cursor.md b/docs/features/integrations/cursor.md index 43a939fa4c..60156746f8 100644 --- a/docs/features/integrations/cursor.md +++ b/docs/features/integrations/cursor.md @@ -1,14 +1,40 @@ # Cursor -Cursor gets Loom in two independent pieces: - -| Piece | What it gives | How | -| ------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| MCP tools | the `loom_*` tools in Cursor's agent | the [install link](#mcp-tools) for a local single-user server, else `loom install --client cursor` ([MCP clients](mcp-clients.md)) | -| Transcript capture | each conversation's turns in `conversation.append` | the `sessionEnd` hook `integrations/cursor/cursor-session-hook.sh` | - -There is no Cursor plugin, so no code shunt and no capture of tool calls, runs or -working memory; the [Claude Code](claude-code.md) and [Codex](codex.md) plugins have those. +Cursor gets Loom in three pieces: + +| Piece | What it gives | How | +| ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| MCP tools | the `loom_*` tools in Cursor's agent | the [plugin](#plugin), the [install link](#mcp-tools) for a local single-user server, or `loom install --client cursor` ([MCP clients](mcp-clients.md)) | +| Skills | the `loom` and `loom-code` skills | the [plugin](#plugin), or `npx skills add ClickHouse/loom --skill loom loom-code` | +| Transcript capture | each conversation's turns in `conversation.append` | the `sessionEnd` hook `integrations/cursor/cursor-session-hook.sh` | + +The Cursor plugin carries the MCP entry and the `loom` and `loom-code` skills, and has no +hooks: no code shunt and no capture of tool calls, runs or working memory; the +[Claude Code](claude-code.md) and [Codex](codex.md) plugins have those. + +## Plugin + +`.cursor-plugin/` at the repository root makes the repository a Cursor plugin marketplace +with one plugin, `clickhouse-loom`: the `loom` MCP server and the root `skills/`. The +plugin is not listed in Cursor's marketplace and has not been tested in Cursor. On a +Teams or Enterprise plan, a team admin adds it under **Dashboard → Plugins & MCPs → Add +Marketplace → Import from Repo** with `https://github.com/ClickHouse/loom`. + +The plugin has one variable, **Loom MCP URL**. A team admin sets it in Cursor's +dashboard under **Plugins & MCPs**, for every member. + +| Server | Loom MCP URL | Sign-in | +| ------------------------------------------ | -------------------------------------------------------- | ------------------- | +| single-user, on each member's machine | `http://localhost:7777/mcp?toolset=coding` (the default) | none | +| team server with `LOOM_OAUTH_ENABLED=true` | `https:///mcp` | browser, per person | + +A server with OAuth on takes the bare URL, the resource its protected-resource metadata +names; tools outside its default toolset run through `loom_op`. The entry sends no +`Authorization` header, so a team server without OAuth answers 401. Such a team skips the +plugin: `loom install --client cursor` [below](#mcp-tools) writes the entry with a token, +and `npx skills add` adds the skills. +[Clients that sign in by browser](mcp-clients.md#clients-that-sign-in-by-browser) has the +OAuth details. ## MCP tools diff --git a/docs/features/integrations/index.md b/docs/features/integrations/index.md index eba817368a..644f72ed12 100644 --- a/docs/features/integrations/index.md +++ b/docs/features/integrations/index.md @@ -22,7 +22,7 @@ opt-in; one you leave unconfigured does nothing. They fall into three groups: | Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | | JetBrains, Visual Studio, Neovim, Emacs and other agents | MCP client config | [other editors and agents](mcp-clients.md#other-editors-and-agents) | | Cline CLI (experimental) | hooks: session primer, prompt recall, a file's memories on a read | `integrations/cline/`: [README](../../../integrations/cline/README.md) | -| Cursor | MCP tools + `sessionEnd` transcript hook | `integrations/cursor/`: [cursor.md](cursor.md) | +| Cursor | MCP tools, skills (untested plugin) + `sessionEnd` capture hook | `.cursor-plugin/`, `integrations/cursor/`: [cursor.md](cursor.md) | | Any Agent-Skills client | the `loom` and `loom-code` skills, no hooks | `skills/loom/`, `skills/loom-code/`: [below](#coding-agents) | | Aider, Continue, OpenCode, JetBrains AI | transcript capture template | `integrations/generic/`: [below](#transcript-capture-hooks) | | Agents that only use shell grep | the grep shim | `integrations/grep-shim/`: [grep-shim.md](grep-shim.md) | diff --git a/docs/features/integrations/mcp-clients.md b/docs/features/integrations/mcp-clients.md index 1ceebe3de1..45ff9c397d 100644 --- a/docs/features/integrations/mcp-clients.md +++ b/docs/features/integrations/mcp-clients.md @@ -9,12 +9,13 @@ path as `POST /v1/`. The protocol is in the [MCP reference](../../reference/ ## Plugin or plain MCP -| You run | Use | You get | -| ----------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| Claude Code | the [Claude Code plugin](claude-code.md) | tools, capture hooks, code shunt, skills, the code-scope header | -| Codex | the [Codex plugin](codex.md) | the same, with Codex wiring | -| Claude Desktop, Cursor, VS Code, Cline, Windsurf, Zed | `loom install --client ` ([below](#wire-a-client-with-loom-install)) | the tools; capture only through a [transcript template](index.md#transcript-capture-hooks) ([Cursor](cursor.md)) | -| an orchestrator running several agents | one MCP mount per agent ([frameworks.md](frameworks.md)) | shared memory across the agents | +| You run | Use | You get | +| --------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Claude Code | the [Claude Code plugin](claude-code.md) | tools, capture hooks, code shunt, skills, the code-scope header | +| Codex | the [Codex plugin](codex.md) | the same, with Codex wiring | +| Cursor | the [Cursor plugin](cursor.md#plugin) (untested in Cursor) or `loom install --client cursor` | the tools; the `loom` and `loom-code` skills from the plugin; capture through the [`sessionEnd` hook](cursor.md#transcript-capture) you register | +| Claude Desktop, VS Code, Cline, Windsurf, Zed | `loom install --client ` ([below](#wire-a-client-with-loom-install)) | the tools; capture only through a [transcript template](index.md#transcript-capture-hooks) | +| an orchestrator running several agents | one MCP mount per agent ([frameworks.md](frameworks.md)) | shared memory across the agents | A plain MCP entry gives the tools only: no session capture, primer or code shunt. Loom still records an implicit run per MCP session and names the agent after the client's diff --git a/docs/getting-started/connect-a-coding-agent.md b/docs/getting-started/connect-a-coding-agent.md index ca10eef216..62ebd9125f 100644 --- a/docs/getting-started/connect-a-coding-agent.md +++ b/docs/getting-started/connect-a-coding-agent.md @@ -69,6 +69,10 @@ the plugin installed: an entry with the same name replaces the plugin's. ## Cursor and other MCP clients +On a Cursor Teams or Enterprise plan, a team admin can import the [Cursor +plugin](../features/integrations/cursor.md#plugin) (untested in Cursor), which carries the +MCP entry and Loom's skills. + For Cursor or VS Code against a single-user server on the same machine, no token is needed: use the [Cursor](../features/integrations/cursor.md#mcp-tools) or [VS Code](../features/integrations/vscode.md#local-single-user-server) install link. Otherwise, in the dashboard, diff --git a/integrations/cursor/README.md b/integrations/cursor/README.md index 8b9ae9df9e..dcf69df1f6 100644 --- a/integrations/cursor/README.md +++ b/integrations/cursor/README.md @@ -2,9 +2,11 @@ `cursor-session-hook.sh` is a Cursor agent hook that hands a finished conversation's transcript to `loom ingest-transcript`, which posts each turn -to `conversation.append`. For Loom's tools inside Cursor, use the MCP config -instead (`loom install --client cursor`, see [docs/features/integrations/mcp-clients.md](../../docs/features/integrations/mcp-clients.md)); -the two are independent. +to `conversation.append`. For Loom's tools inside Cursor, use the +[Cursor plugin](../../docs/features/integrations/cursor.md#plugin) +(untested in Cursor) or the MCP config (`loom install --client cursor`, see +[docs/features/integrations/mcp-clients.md](../../docs/features/integrations/mcp-clients.md)); +the hook is independent of both. ## Install diff --git a/llms.txt b/llms.txt index 7778c409bc..7754a04869 100644 --- a/llms.txt +++ b/llms.txt @@ -62,7 +62,7 @@ Start with docs/index.md (the map). To install Loom, a coding agent reads docs/g - [Claude Code plugin](docs/features/integrations/claude-code.md): The `loom` plugin for Claude Code does three things in one install: - [ClickStack and HyperDX](docs/features/integrations/clickstack.md): Loom always emits OpenTelemetry; the HyperDX sources, dashboards and the erasure step need configuring. - [Codex plugin](docs/features/integrations/codex.md): The Codex plugin gives Codex the same Loom integration as Claude Code: MCP tools, hooks that capture the session and load a primer, and the code shunt. -- [Cursor](docs/features/integrations/cursor.md): Cursor gets Loom in two independent pieces: +- [Cursor](docs/features/integrations/cursor.md): Cursor gets Loom in three pieces: - [Agent frameworks and orchestrators](docs/features/integrations/frameworks.md): The SDKs ship adapters that present Loom through a framework's own memory or retrieval interface. - [The grep shim](docs/features/integrations/grep-shim.md): Needs Node 18 or later, a viewer token, and a repository in the code index. - [Integrations](docs/features/integrations/index.md): Loom on a bare ClickHouse service is a complete deployment. @@ -174,7 +174,7 @@ Start with docs/index.md (the map). To install Loom, a coding agent reads docs/g - [Extend Loom](docs/development/extending-loom.md): Loom has one registry per kind of thing: operations, workers, settings, providers, language lanes, extraction steps and tracker sources. - [Local development](docs/development/local-development.md): This page sets up a checkout for working on Loom's code. - [Migrations](docs/development/migrations.md): This page holds the rules for writing a migration. -- [Release process](docs/development/release-process.md): Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`) and the Gemini CLI extension share one version `X.Y.Z`. +- [Release process](docs/development/release-process.md): Loom follows SemVer: the server, both SDKs, the web app, the root skills (`loom-code`, `loom`), the Cursor plugin that ships them and the Gemini CLI extension share one version `X.Y.Z`. - [Repository guide](docs/development/repository-guide.md): What every top-level directory holds, where a concern lives inside `server/`, the order to read the code in, and the conventions a pull request fails without. - [Testing](docs/development/testing.md): Which suite a test belongs in, what each suite needs to run, how tests skip when their environment is missing, which gates CI enforces, and how to regenerate what they pin. diff --git a/scripts/release/prepare.py b/scripts/release/prepare.py index 91e1d67d65..4d01b607af 100755 --- a/scripts/release/prepare.py +++ b/scripts/release/prepare.py @@ -67,6 +67,7 @@ class Pin(NamedTuple): Pin("frontend/package-lock.json", _TOP_JSON), Pin("frontend/package-lock.json", _LOCK_ROOT), Pin(".claude-plugin/plugin.json", _TOP_JSON), + Pin(".cursor-plugin/plugin.json", _TOP_JSON), Pin("gemini-extension.json", _TOP_JSON), Pin("skills/loom-code/SKILL.md", r'^ version: "(?P[^"]+)"$'), Pin("skills/loom/SKILL.md", r'^ version: "(?P[^"]+)"$'), diff --git a/skills/loom-code/SKILL.md b/skills/loom-code/SKILL.md index 50b61186ba..2f2b4d1591 100644 --- a/skills/loom-code/SKILL.md +++ b/skills/loom-code/SKILL.md @@ -83,8 +83,8 @@ router still works through the shell. ## Install -Install either this skill (`loom-code-skill`) or the `loom` plugin, not -both: the plugin ships its own skill named `loom-code`. +In Claude Code, install either this skill (`loom-code-skill`) or the `loom` +plugin, not both: the plugin ships its own skill named `loom-code`. ## Identity diff --git a/tests/unit/test_cursor_plugin.py b/tests/unit/test_cursor_plugin.py new file mode 100644 index 0000000000..877dc2c5b2 --- /dev/null +++ b/tests/unit/test_cursor_plugin.py @@ -0,0 +1,65 @@ +"""The Cursor plugin at the repository root: `.cursor-plugin/` holds the marketplace, the +manifest and its MCP entry, and the plugin's skills are the root `skills/`.""" + +from __future__ import annotations + +import json +import posixpath +import re +from pathlib import Path + +import pytest + +import server.cli.install as cli +from server.cli._client import DEFAULT_BASE_URL +from tests.unit.test_loom_code_skill import ROOT_SKILLS + +ROOT = Path(__file__).resolve().parents[2] +PLUGIN_DIR = ROOT / ".cursor-plugin" +MANIFEST = json.loads((PLUGIN_DIR / "plugin.json").read_text()) +MARKETPLACE = json.loads((PLUGIN_DIR / "marketplace.json").read_text()) + + +def test_the_marketplace_lists_the_root_plugin_by_its_name() -> None: + (entry,) = MARKETPLACE["plugins"] + assert entry["source"] == "./" + assert entry["name"] == MANIFEST["name"] + + +def test_manifest_paths_are_relative_and_exist() -> None: + # Cursor's template validator refuses an absolute path or one that leaves the plugin. + for field in ("logo", "skills", "mcpServers"): + path = MANIFEST[field] + assert not path.startswith("/") and not posixpath.normpath(path).startswith(".."), path + assert (ROOT / path).exists(), path + + +def test_every_variable_the_mcp_entry_uses_is_declared_and_required() -> None: + entry = (ROOT / MANIFEST["mcpServers"]).read_text() + used = set(re.findall(r"\$\{(\w+)\}", entry)) + variables = MANIFEST["variables"] + assert used and used == set(variables["properties"]) == set(variables["required"]) + + +def test_the_entry_sends_no_authorization_header() -> None: + # A local server takes the call without one; an OAuth server answers 401 for sign-in. + entry = json.loads((ROOT / MANIFEST["mcpServers"]).read_text())["mcpServers"]["loom"] + assert entry == {"url": "${LOOM_MCP_URL}"} + + +def test_the_default_url_is_the_one_loom_install_writes_for_cursor( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + config = tmp_path / "mcp.json" + monkeypatch.setattr(cli, "_resolve_install_path", lambda client: config) + assert cli._install_one( + "cursor", token="", server_url=DEFAULT_BASE_URL, name="loom", dry_run=False + ) + written = json.loads(config.read_text())["mcpServers"]["loom"]["url"] + default = MANIFEST["variables"]["properties"]["LOOM_MCP_URL"]["default"] + assert default == written + + +def test_the_plugin_ships_the_root_skills() -> None: + names = {p.parent.name for p in (ROOT / MANIFEST["skills"]).glob("*/SKILL.md")} + assert names == set(ROOT_SKILLS) diff --git a/tests/unit/test_published_links.py b/tests/unit/test_published_links.py index a50e7356d1..3c9dc6eb8a 100644 --- a/tests/unit/test_published_links.py +++ b/tests/unit/test_published_links.py @@ -44,6 +44,7 @@ def test_published_links_resolve() -> None: for f in ( "server.json", ".claude-plugin/plugin.json", + ".cursor-plugin/plugin.json", "integrations/claude-code-plugin/.claude-plugin/plugin.json", "integrations/codex-plugin/.codex-plugin/plugin.json", "pyproject.toml",