Skip to content
Back to search

catalyst-q

MarketplaceWorks with Claude CodeGitHub

Catalyst-Q tools for agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/crewriz--catalyst-q/badge.svg)](/listings/crewriz--catalyst-q)

HTML

<a href="/listings/crewriz--catalyst-q"><img src="/api/listings/crewriz--catalyst-q/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines
  1. {
  2. "name": "catalyst-q",
  3. "owner": {
  4. "name": "Travis Crew",
  5. "url": "https://github.com/t-crew"
  6. },
  7. "description": "Catalyst-Q tools for agents.",
  8. "plugins": [
  9. {
  10. "name": "catalyst-q",
  11. "source": "./",
  12. "description": "Run quantum circuits through a hosted API and get exact answers, or a refusal with the numbers. Includes an advisor that says when not to use it. Not a quantum computer.",
  13. "author": {
  14. "name": "Travis Crew"
  15. },
  16. "homepage": "https://catalyst-q.strategic-innovations.ai",
  17. "license": "MIT",
  18. "keywords": ["quantum", "openqasm", "qec", "mcp"]
  19. }
  20. ]
  21. }
README.md · README · 158 lines
  1. # Catalyst-Q
  2. **Send a quantum circuit. Get the exact answer back, or a refusal that shows you the numbers.**
  3. Catalyst-Q is a hosted API that runs quantum circuits on classical hardware. It is not a quantum computer. This repo holds the client tools: an SDK, a command line, an MCP server for agents, a GitHub Action and a desktop app. All of them work without an account.
  4. ![The first screen of the desktop app, with the advisor reacting to a goal](docs/screenshots/02-advisor-reacts.png)
  5. ## Try it now, with no account
  6. Run a Bell pair:
  7. ```sh
  8. curl -s https://catalyst-q.strategic-innovations.ai/api/v1/try \
  9. -H 'content-type: application/json' \
  10. -d '{"mode":"execute","qasm":"OPENQASM 3.0; qubit[2] q; h q[0]; cx q[0], q[1];","measure":[0,1]}'
  11. ```
  12. Or from a file:
  13. ```sh
  14. npx catalyst-q run examples/bell.qasm --measure 0,1
  15. ```
  16. Or in TypeScript:
  17. ```sh
  18. npm install catalyst-q
  19. ```
  20. ```ts
  21. import { CatalystQ, settle } from "catalyst-q";
  22. const q = new CatalystQ();
  23. const out = await settle(q.run({ qasm: "OPENQASM 3.0; qubit[2] q; h q[0]; cx q[0], q[1];", measure: [0, 1] }));
  24. if (out.kind === "answer") console.log(out.reply.result.probabilities);
  25. if (out.kind === "refusal") console.log(out.code, out.detail, out.numbers);
  26. ```
  27. The no-account route takes up to 64 qubits and 4,000 gates, 6 calls a minute and 60 a day per address. With a key in `CATALYST_Q_KEY`, the same calls take up to 256 qubits.
  28. ## What you get back
  29. | You ask for | You send | You get |
  30. |---|---|---|
  31. | Every probability | `{mode:"execute", qasm, measure?}` | The full table of exact probabilities, up to 20 measured qubits |
  32. | Shots | `{mode:"execute", qasm, sampling:"random", shots, seed?}` | Real draws from the exact distribution, at any number of measured qubits |
  33. | Named outcomes | `{mode:"execute", qasm, outcomes:["0101"]}` | The probability of each bit string, at any number of measured qubits. Classical bit 0 is on the right |
  34. | A score for device counts | `{mode:"score", qasm, counts:{"0101":12}}` | Cross-entropy with its standard error, shots on impossible outcomes and, at small widths, total variation and Hellinger fidelity |
  35. | Expectation values | `{mode:"circuit", qasm, observables:[{pauli:"ZZ",qubits:[0,1]}]}` | Each value with `exact` and an error `certificate` |
  36. | A surface code | `{mode:"qec", distance:3, epsilon:0.05}` | The logical channel under a coherent rotation error |
  37. Most replies carry a `permalink` to a public record of the job. That record includes your circuit, so do not send a circuit that must stay private.
  38. ## What it refuses, and why
  39. Catalyst-Q gives an exact answer or none. When a job is out of reach, you get a refusal in place of a guess. It is an ordinary JSON reply with a non-2xx status:
  40. ```json
  41. { "ok": false, "error": "a_code", "detail": "A sentence saying why.", "...": "the numbers behind it" }
  42. ```
  43. A refusal is a result. It tells you this exact computation will not happen here, and how far off it was. Every tool in this repo shows it that way: the SDK's `settle()` returns it as a value, the CLI prints it and exits 10, the MCP server returns it as a normal tool result, the Action writes it to the job summary and passes, and the desktop app explains it in plain words with the numbers beside it.
  44. You will also be refused for circuits it cannot read, for going over a route's limits, and for going past the rate limit.
  45. ## When not to use it
  46. - **Your circuit is small.** Qiskit on a laptop runs ordinary small circuits fine. You do not need a hosted API for them.
  47. - **You want to know how a specific device behaves.** This is classical and noiseless. It says nothing about a device beyond the counts you give it.
  48. - **The circuit is private.** Replies usually link to a public record of it.
  49. - **You need thousands of parameter settings.** Each call is one circuit, and the no-account route allows 6 a minute.
  50. - **You study other codes or circuit-level noise.** The QEC routes cover rotated surface codes under the noise they name. Stim is the usual tool for the rest.
  51. ## Not sure it applies? Ask the advisor
  52. The advisor reads a goal, a folder or some code and says where Catalyst-Q could help, why, and when not to use it. It runs on your computer, makes no network call and uses no model. If nothing applies, it says so and stops.
  53. ```sh
  54. npx catalyst-q suggest .
  55. npx catalyst-q suggest --goal "plan a QAOA run before I buy hardware time"
  56. ```
  57. It recognises circuits and Qiskit, Cirq or PennyLane code; counts from a hardware run; circuits that keep the number of excitations; QAOA and VQE; reversible arithmetic and oracles; surface codes; papers to reproduce; and shots spent estimating an expectation value.
  58. ## For AI agents
  59. **MCP server.** Six tools, each saying when to reach for it and when not to.
  60. ```sh
  61. claude mcp add catalyst-q -- npx -y catalyst-q-mcp
  62. ```
  63. **Agent skill.** [skills/catalyst-q/SKILL.md](skills/catalyst-q/SKILL.md) tells an agent to run the advisor before anything else. The repo is also a plugin for Claude Code and Codex:
  64. ```sh
  65. claude plugin marketplace add CrewRiz/catalyst-q
  66. claude plugin install catalyst-q@catalyst-q
  67. codex plugin marketplace add CrewRiz/catalyst-q
  68. codex plugin add catalyst-q@catalyst-q
  69. ```
  70. ## In a pull request
  71. The Action runs the `.qasm` files a pull request changes and writes the results to the job summary. It needs no secret. See [action/README.md](action/README.md).
  72. ```yaml
  73. - uses: actions/checkout@v7
  74. - uses: CrewRiz/catalyst-q/action@v1
  75. ```
  76. ## On your desktop
  77. `npx catalyst-q ui` opens a local page. Tell it what you are trying to do, drop in a file, run a circuit, see the outcomes as a bar chart, and score counts from a device. [apps/desktop](apps/desktop) wraps the same page in a window and keeps a key encrypted by your operating system.
  78. ## Hold it to a yardstick
  79. [yardstick/](yardstick/) is a provider for [Quantum Yardstick](https://github.com/t-crew/quantum-yardstick), an open benchmark harness, so you can check Catalyst-Q against analytic ground truth yourself.
  80. ## What is in this repo
  81. | Path | What it is | npm |
  82. |---|---|---|
  83. | `packages/sdk` | TypeScript client with no dependencies | `catalyst-q` |
  84. | `packages/advisor` | The local advisor | `catalyst-q-advisor` |
  85. | `packages/cli` | The commands behind `npx catalyst-q` | `catalyst-q-cli` |
  86. | `packages/mcp` | The MCP stdio server | `catalyst-q-mcp` |
  87. | `packages/ui` | The page the CLI and desktop app share | `catalyst-q-ui` |
  88. | `apps/desktop` | The Electron shell | |
  89. | `action/` | The GitHub Action | |
  90. | `skills/` | The agent skill | |
  91. | `yardstick/` | The benchmark provider | |
  92. Client code and docs live here. The service is hosted at [catalyst-q.strategic-innovations.ai](https://catalyst-q.strategic-innovations.ai).
  93. ## Develop
  94. ```sh
  95. npm install
  96. npm test # offline; every test mocks the network
  97. npm run desktop # needs the Electron binary, which npm install fetches
  98. ```
  99. Node 22.18 or newer. Set `ELECTRON_SKIP_BINARY_DOWNLOAD=1` if you do not need the desktop app.
  100. ## Jobs larger than one request
  101. With a key, `q.distributed({ qasm, outcomes })` carries a hard job across as many requests as it needs. All of the job's state travels in its own payload, so nothing is stored on the service between requests, a failed request can be sent again, and the answer is the same to the last bit at any concurrency. Fan-out divides the time. The total work stays the same, and for a hard circuit it doubles with each gate across the circuit's best cut.
  102. ## Reproduce every claim
  103. Every claim on the [Evidence page](https://catalyst-q.strategic-innovations.ai/bench) has a script here that computes the answer a second way and compares. See [reproduce/](reproduce/).
  104. ## License
  105. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.