Tool
execute
Combine RepoQL operations in a JavaScript script when you need loops, branching, or a custom result.
execute runs JavaScript in a local WASM sandbox. A script can query the index, read source, transform the results, and write an artifact. It is useful when the next operation depends on what an earlier one returned.
Build on queries and reads
Use SQL to filter, join, and aggregate data. Use JavaScript for decisions around those results: selecting another source to read, assembling a report, or preparing a diagram. Keeping large data operations in SQL reduces the amount the script needs to handle.
Scripts can also invoke approved tools from connected MCP servers. Those calls retain the bridge’s authority checks and may access external services.
The script runs inside RepoQL
The runtime is QuickJS, rather than Node.js or a browser. File and tool access comes through the APIs RepoQL supplies. Read, write, and delete scopes control which addresses a script can access; time and memory limits bound its execution.
Writes can modify repository files within the configured scope. By default, writes are allowed inside the repository and deletes are limited to .repoql/tmp/. Choose output paths deliberately, just as you would for a local script.
Example: return filenames from a query
Terminal
rql execute 'const rows = repoql.query("SELECT uri FROM Files ORDER BY uri LIMIT 3");
rows.map(row => row.uri.split("/").pop());'The last expression supplies the result. The query returns rows; JavaScript transforms each URI into a filename. repoql.query is synchronous, so this does not need await.
Runtime and API reference
| API | Use |
|---|---|
| repoql.query(sql) | Run SQL and return rows. |
| repoql.read(uriGlob, { budget }) | Read indexed content and its representation metadata. |
| repoql.write(uri, content) | Write a file within the write scope. |
| repoql.delete(uri) | Delete a file within the delete scope. |
| repoql.graphviz(dot) | Render a DOT diagram, normally as SVG. |
| repoql.svgToPng(svg, width) | Convert an SVG to a base64 PNG. |
| mcp.servers / tools / describe | Discover configured bridge tools. |
| mcp.server.tool(args) | Call an approved external tool. |
Top-level return and await are not supported. End with the value you want back, or use a function expression when you need a return statement. Dynamic import() loads an embedded or registered module and returns a promise; a promise returned by the script is resolved.
repoql.ffmpeg requires installed ffmpeg and ffprobe binaries. repoql.pandoc requires an optional WASM module that released builds do not include. Do not assume these conversions are available on every host.
| MCP parameter | Use |
|---|---|
| code | Required. JavaScript source. |
| intent | Optional. Description of the result you want. |
| tokenBudget | Optional. Maximum response size. |
| timeout | Optional. Execution time limit. |
Further reference
In the installed manual: help:///tools/execute.md.