multimeter
AGENTS.md14 starsChanged 3 months agoApache-2.0View on GitHub
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- llms-full.txtllms.txt
- llms.txtllms.txt
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
22 rules. About 0 are common, 2 are distinctive, and 20 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
20
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Do not reimplement parsing or execution pipelines in the extension or CLI – always go through runner.
- Very specific: line 25
No imports from vscode, fs, path, browser APIs, or Node globals that assume a specific runtime.
- Very specific: line 26
All file access, code execution, logging, and network plumbing come in via injected functions (fileLoader, jsRunner, logger, etc.).
- Very specific: line 37
Add/adjust unit tests in core/src/*.test.ts that cover the new pure logic.
- Very specific: line 49
Keep UI logic (layout, focus, interactions) here.
- Very specific: line 56
If you add new CLI flags, wire them through to runner.runFile rather than duplicating parsing/execution.
- Very specific: line 68
All HTTP/WS traffic flows through core/src/network/networkCore.ts + core/src/network/network.ts using NetworkConfig from NetworkData.ts.
- Very specific: line 73
If status < 0, the wrapper builds outputs then fails the run so the Response panel can still show the network error.
- Very specific: line 74
When extending logs, reuse helpers from createApiLogHelpers instead of ad-hoc console.log, and treat logs as append-only (especially in the …
- Very specific: line 81
Do NOT add a VS Code preLaunchTask (or similar) that rebuilds webview/extension on every Extension Development Host F5/restart — compile …
- Very specific: line 82
Do NOT touch CHANGELOG.md for regular fixes or features.
- Distinctive: line 86
Ask for the exact version.
- Distinctive: line 99
Never ship a VSIX whose version contains a hyphen.
- Very specific: line 108
Avoid per-package custom build scripts.
- Very specific: line 113
Always use curly braces for all control structures (e.g.
- Very specific: line 114
Keep core free of editor/FS/UI dependencies.
- Very specific: line 115
Commit message style: short, imperative (Add test auto complete, Improve UI of doc view).
- Very specific: line 117
Prefer implementing behavior in core first, then wiring it to the extension (src/), webview (mmtview/), CLI (mmtcli/), and finally updating …
- Very specific: line 118
Before refactoring shared APIs like runner.runFile or network helpers, search call sites in:
- Very specific: line 146
After the run, buildApiTesterResponse (core/src/runner/apiRunResult.ts) shapes outputs._ into the Response panel payload.
- Very specific: line 230
Not urgent — no current testlight breaking changes — but keep in mind:
- Very specific: line 233
MCP scaffold (
mmtmcp/): When changing scaffold_test / agent write paths, prefer PR-ready .mmt with real asserts/schema (“receipt”).
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Copilot Instructions for multimeter (mmt)
Project structure & architecture
- Website: https://mmt.dev (NOT multimeter.dev). Public test server: https://test.mmt.dev. In-process twin:
https://local.mmt.dev(andws:///wss:///*.local.mmt.dev) — answered insidenetworkCoreviacore/src/network/localTestServer.ts(shared with the Cloudflare worker); no DNS/sockets/internet. - Monorepo layout:
core/: pure TypeScript library with all parsing, execution and network logic (no VS Code, nofs– use dependency injection).mmtview/: React + VS Code webview UI for editing/running.mmtfiles.mmtcli/: CLI app; binary istestlight, used for CI and local runs.mmtaction/: GitHub Action product (action.yml), published tomshobeyri/testlight-action. Not an action this repo consumes.mmtazure/: Azure Pipelines task product (Testlight@1). Same idea asmmtaction/.mmtmcp/: MCP server package.- Root
src/: VS Code extension host code (activation, editor provider, assistant, network bridge). docs/: user-facing documentation (API, test, env, suite, CLI, convertor, etc.).AI/: internal AI-assisted development artifacts. Not shipped to users.sdd/: Software Design Documents (SDDs) — architectural decisions, competitive strategy, feature designs.marketing/: LinkedIn, YouTube, Hacker News / Show HN skills, drafts, and meeting memos (meetings/). Not part of the published Cursor plugin.skills/: local/dev agent skills (e.g. release & deploy). Not part of the published Cursor plugin.doc/: handover and context documents for AI agent sessions.
- Single source of truth for running
.mmtfiles iscore/src/runner/runner.ts:- Use
runner.runFile({ rawFile, filePath, inputs, envvar, fileLoader, jsRunner, logger }). - Do not reimplement parsing or execution pipelines in the extension or CLI – always go through
runner.
- Use
Core library (core/) patterns
- Keep
coreplatform-neutral:- No imports from
vscode,fs,path, browser APIs, or Node globals that assume a specific runtime. - All file access, code execution, logging, and network plumbing come in via injected functions (
fileLoader,jsRunner,logger, etc.).
- No imports from
- Key modules to know:
runner.ts: orchestrates.mmtexecution, builds API/test runners, and formats logs/docs.JSer.ts,testParsePack.ts,apiParsePack.ts: turn YAML.mmtinto executable JS flows.networkCore.ts,network.ts,NetworkData.ts: HTTP/WebSocket client, message routing, and shared network config types.outputExtractor.ts+pathAtPosition.test.ts: JSON/XML/xpath/jsonpath/regex extraction and “path at cursor” helpers.tokens/variableReplacer.ts: single source of truth for all token-matching regex and replacement logic. All regex patterns and token accessor handling fore:,i:,r:,c:tokens (including forms like[0],[0:3], and.field) live here. Other modules (JSerHelper,JSerTestFlow,JSerAPI, etc.) import helpers fromvariableReplacer— they must NOT define their own token-matching regexes.- YAML on disk: bare whole-value tokens (
r:int) and embedded<<prefix:name>>. API tester UI uses{{prefix:name}}; that curly form is also accepted in YAML and normalized to bare /<<>>on parse (markupConvertor+reviveDisplayRuntimeTokensInValue). SeeAI/sdd/sdd-token-form-consistency.md. - Return types for JSON UI quoting:
randomTokenValueType/currentTokenValueTypeinRandom.ts/Current.ts(not hardcoded allowlists in the UI layer).
- When extending behavior:
- First update the relevant data model types in
core/src/*Data.ts(e.g.APIData,TestData,NetworkConfig). - Add/adjust unit tests in
core/src/*.test.tsthat cover the new pure logic.
- First update the relevant data model types in
VS Code extension + webview
- Extension host (
src/):extension.ts: entrypoint; registers the.mmtcustom editor, side panels (temp files, history, mock server, environment, certificates), and chat participants fromsrc/assistant.ts.mmtEditorProvider.ts: glue between webview messages andrunner.runFile. It:- Receives
commandmessages likerunCurrentDocument,runCurlCommand, etc. - Calls
runner.runFile({ rawFile: document.getText(), filePath: document.uri.fsPath, inputs, envvar, fileLoader, jsRunner, logger }).
- Receives
vscodeNetwork.ts: adapts VS Code configuration and environment toNetworkConfigand bridges webview/network messages intocore.
- Webview React app (
mmtview/src/):- Uses
window.vscode.postMessagevia helpers invsAPI.tsinstead of importingcoredirectly. text/YamlEditorPanel.tsxdrives run glyphs for.mmtfiles; it sends structuredinputsshapes (type: 'defaults' | 'manual' | 'exampleId' | 'exampleIndex') back to the extension.- Keep UI logic (layout, focus, interactions) here; keep parsing/execution in
core.
- Uses
CLI (mmtcli/) workflow
- Entrypoint:
mmtcli/src/cli.tswrapscoreand exposes thetestlightbinary. - Typical usage (see
mmtcli/README.mdanddocs/features/testlight/index.md):npx testlight run path/to/test.mmt- Pass env via
--env-file,--preset, and-e KEY=VALUEflags; types are coerced bycoerceCliValue/parsePairsincli.ts(unquoted numbers/bools → numbers/bools, quoted → strings).
- If you add new CLI flags, wire them through to
runner.runFilerather than duplicating parsing/execution.
.mmt data model and docs
.mmtis YAML withtypedriving behavior, parsed byJSer.fileType:type: api→ HTTP/WebSocket API definitions (seedocs/files/api/index.md).type: test→ executable test flows (call,assert,check, etc.; seedocs/files/test/index.md).type: env→ environment and variable files (seedocs/files/env/index.md).
- Converters and docs:
core/src/convert/openapiConvertor.ts,postmanConvertor.ts: turn OpenAPI/Postman into.mmtAPI/test files.core/src/doc/docHtml.ts,docMarkdown.ts,core/src/parse/docParsePack.tsandres/doc-template.html: generate HTML/Markdown API docs from.mmt.
Network, logging, and errors
- All HTTP/WS traffic flows through
core/src/network/networkCore.ts+core/src/network/network.tsusingNetworkConfigfromNetworkData.ts. - HTTP helpers always return a structured
HttpResponse; network-level failures are normalized (e.g.status = -1, descriptivestatusText) so callers can distinguish unreachable hosts from HTTP errors. - Two layers: (1) Execution — request/response via
runner.runFile/send_(HTTP, GraphQL, gRPC, one-shot WS). (2) Live sessions — API tester Connect + Connections panel via the network bridge. Do not dual-fire HTTP Send (webview send + core run). - API runs use
buildApiRunnerWrapperinrunApi.ts:- Log
Request,Response,Environment, andInputssections with consistent key/value formatting. - If
status < 0, the wrapper builds outputs then fails the run so the Response panel can still show the network error.
- Log
- When extending logs, reuse helpers from
createApiLogHelpersinstead of ad-hocconsole.log, and treat logs as append-only (especially in the extension output channel).
Workflow / agent rules
- Start a Multimeter project. When the user (or you) is starting/scaffolding a project with several APIs + tests and no other layout is requested, follow
docs/AI/project-layout.mdand the mother guidedocs/tasks/start-a-project.md(especially Where values live: env = user knobs / API Send defaults; JSON = fixed shared catalogs; direct in the test = scenario values like date windows). Defaults: rootmultimeter.mmt,api/,test/<area>/{suite.mmt,test_*.mmt},+/…imports, unquoted operator expects,expect+report: allover single-outputcheck. Sample repos underexamples/real-projects/illustrate the same rules; they are not the only use of this layout. - Compile on every finished coding task. Whenever you finish a coding task with the user (task complete, “done”, wrapping up a multi-step change, or handing work back), run
npm run compileat the repo root, fix any compile errors, and only then treat the work as finished. Do this even if tests already passed. Skip only when no source files were changed (docs-only / SDD-only / config-only with no code). - Do NOT create, stage, or push git commits unless the user explicitly asks you to do so. Always ask for confirmation before running any
git add,git commit, orgit pushoperations. You may edit files in the workspace to make suggested changes, but do not record those changes in version control until the user gives explicit permission. When edits are made without committing, clearly list the modified files and the intended commit message so the user can approve. - Do NOT add a VS Code
preLaunchTask(or similar) that rebuilds webview/extension on every Extension Development Host F5/restart — compile explicitly vianpm run compile/ watch instead. Reloading the target while a heavy preLaunch rebuild runs is a common cause of the debug host stopping. - Do NOT touch
CHANGELOG.mdfor regular fixes or features. It is written only as part of the release workflow, from the commits included in that release.
Release workflow
Ask for the exact version. Do not invent one.
- "release X.Y.Z" → stable.
package.json,mmtcli/package.json, andmmtmcp/package.jsonare allX.Y.Z. TagvX.Y.Z. - "pre-release X.Y.Z" → extension
package.jsonisX.Y.Z(Marketplace cannot have-pre). CLI and MCP areX.Y.Z-pre. TagvX.Y.Z-pre.
CLI (mmt-testlight) and MCP (mmt-mcp) share one npm version and dist-tag: stable → @latest, pre → @pre. mmtmcp/server.json must match that same MCP version (CI --check enforces it). Then CHANGELOG, always pack a local VSIX (npm run pack or npm run pack-pre-release), commit Release version …, push the tag.
GitHub Actions (.github/workflows/release-testlight.yml) builds binaries, creates the GitHub Release, then publishes npm (both packages), Docker, Homebrew (stable), and the GitHub Action (stable only).
VS Code Marketplace pre-releases are published from Azure Pipelines (azure-pipelines.yml in Azure DevOps project mehrdadshobeyri / multimeter), not from GitHub Actions. Pushing vX.Y.Z-pre packs the VSIX and runs vsce publish --pre-release (publisher mshobeyri; secret VSCE_PAT on that pipeline). Manual pipeline runs on a branch only pack. v1.44.0-pre is skipped. After a pre-release tag, confirm that Azure run succeeded.
Stable Marketplace, Open VSX, and the official MCP Registry are not published from GitHub CI. After a stable release, publish the same VSIX to Marketplace and to Open VSX (npx ovsx publish ./multimeter-X.Y.Z.vsix), then check https://open-vsx.org/user-settings/extensions/mshobeyri/multimeter matches X.Y.Z. After npm mmt-mcp@X.Y.Z is on @latest, publish mmtmcp/server.json with mcp-publisher publish and confirm https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.mshobeyri/multimeter shows X.Y.Z. Skip Open VSX and the MCP Registry on pre-releases.
Never ship a VSIX whose version contains a hyphen.
Secrets: NPM_TOKEN, DOCKERHUB_*, TESTLIGHT_ACTION_TOKEN, HOMEBREW_TAP_TOKEN. Marketplace pre-release: Azure DevOps pipeline secret VSCE_PAT.
Build, test, and packaging
- From repo root:
npm run compile --silent– build all apps (core, extension, webview, CLI) via the shared pipeline.npm run test– run Jest tests (mostlycore/src/*.test.ts).
- VS Code extension packaging: run
npm run packat the repo root to create the.vsix(usesEXTENSION.mdas the marketplace readme). - Avoid per-package custom build scripts; integrate new build steps into the root
package.json.
Conventions and change strategy
- Style:
- 2-space indentation, no tabs; always use braces even for single-line
if/loops. - Always use curly braces for all control structures (e.g.
if,else,for,while,do,switch, etc.), even when the body is a single line. This avoids ambiguous or hard-to-read one-line constructs. - Keep
corefree of editor/FS/UI dependencies; put VS Code,fs, browser, and React code insrc/ormmtview/instead. - Commit message style: short, imperative (
Add test auto complete,Improve UI of doc view).
- 2-space indentation, no tabs; always use braces even for single-line
- Change flow:
- Prefer implementing behavior in
corefirst, then wiring it to the extension (src/), webview (mmtview/), CLI (mmtcli/), and finally updating docs underdocs/. - Before refactoring shared APIs like
runner.runFileor network helpers, search call sites in:core/src/runner/runner.ts,src/mmtEditorProvider.ts,src/assistant.ts,src/vscodeNetwork.ts,mmtcli/src/cli.ts,mmtview/src/**.
- For new user-facing features (commands, panels, assistant behaviors), keep CLI and VS Code behavior aligned when reasonable and document any intentional differences.
- Prefer implementing behavior in
Real execution flows (current code)
This section captures the current runtime flow through the webview → extension host → core runner, including how leafId is used end-to-end for suite targeting and report routing.
Run an API .mmt file (type: api)
flowchart TD
A["Webview UI - Send / Run API"] --> B["postMessage (runCurrentDocument)"]
B --> C["Extension host (mmtAPI/run)"]
C --> D["core runner (runner.runFile)"]
D --> E["JSer.fileType"]
E -->|api| F["runApi"]
F --> G["runCommon.runGeneratedJs"]
G --> H["jsRunner exec (sets globals)"]
F --> I["networkCore send_ / sendGrpc_"]
I --> F
F --> J["outputs + finish log duration from res.duration"]
J --> K["Extension posts multimeter.api.run.result"]
K --> L["Webview Response panel + toolbar duration"]Notes:
- Send (HTTP/GraphQL/gRPC) and Run in Core share this path — one network round-trip. Do not also call webview
network.sendfor those protocols. - After the run,
buildApiTesterResponse(core/src/runner/apiRunResult.ts) shapesoutputs._into the Response panel payload. - For API finish logs,
jsRunnerprefers lastsend_/sendGrpc_res.durationover wall-clock. - Interactive WebSocket Connect/live Send stays on the live network bridge (
network.ts+ Connections panel), notrunCurrentDocument. - One-shot WS in tests/CLI uses
sendWsRequest(connect → send → one reply → close). - Plain API runs generally don’t originate a
leafId.
Run a Test .mmt file (type: test)
flowchart TD
A["Webview UI - Run Test"] --> B["postMessage (runCurrentDocument)"]
B --> C["Extension host (mmtEditorProvider/run)"]
C --> D["core runner (runner.runFile)"]
D --> E["JSer.fileType"]
E -->|test| F["runTest (JSer -> JS)"]
F --> G["runCommon.runGeneratedJs"]
G --> H["jsRunner exec (with globals)"]
H --> I["testHelper emits test-step/test-step-run (includes leafId when set)"]
I --> J["Reporter callback (extension)"]
J --> K["Extension forwards runFileReport"]
K --> L["Webview shows steps/asserts"]Run a Suite .mmt file (type: suite) - suite bundle run (current)
flowchart TD
A["Suite webview - Run Suite"] --> B["postMessage (runSuite)"]
B --> C["Extension host (src/mmtAPI/run.ts)"]
C --> C0["Build suite hierarchy (core/suiteHierarchy)"]
C0 --> C1["Build suite bundle (core/suiteBundle)"]
C1 --> D["core runner (runner.runFile + suiteBundle + suiteTargets)"]
D --> E["executeSuiteBundle"]
E --> S0["Reporter: scope=suite-run-start"]
E --> G["Reporter: scope=suite-item + id (running/passed/failed)"]
E --> H["For each runnable node: run as child with runId + id"]
H --> D
D --> I["Child events (test-step/test-step-run/api logs) include id"]
S0 --> J0["Extension maps to command=suiteRunStart"]
G --> J1["Extension forwards command=runFileReport"]
I --> J1
E --> S1["Reporter: scope=suite-run-finished"]
S1 --> J2["Extension maps to command=suiteRunEnd"]
J0 --> K["Webview updates UI"]
J1 --> K
J2 --> K
Notes:
- A suite entry can resolve to a `type: test` file or another `type: suite` file. Both are runnable bundle node kinds.
- Targeting is by a single `target` **node id** (webview sends `target: string`), not a `leafId[]`.
- Execution semantics: bundle is traversed sequentially at the top-level, but `group` children run in parallel (mirrors `then` stage behavior).
- Child `runId` values are generated per runnable node and are stable enough for routing within a run.Run a subtree / node in the suite tree (partial run)
Per-item Run buttons send a single target: string (the bundle node id). The extension passes this into suiteBundle.createSuiteBundle({ target }), and core executes the subtree rooted at target.
flowchart TD
A["Click Run on node"] --> B["Suite webview computes targets (leafId[])"]
B --> C["postMessage (runSuite + target)"]
C --> D["Extension host (src/mmtAPI/run.ts)"]
D --> E["core runner.runFile (suiteBundle)"]
E --> F["executeSuiteBundle selects root by id"]
F --> G["Reporter events include id"]
G --> H["Webview routes output by id"]Notes:
- The bundle is built in the extension using
corehelpers, but execution happens incore. - The UI must never invent ids for targeting; only deterministic bundle node
ids are valid targets.
Suite bundle (current)
Suite runs are executed via a core-native suite bundle runner.
- Node identity:
idis the single end-to-end identifier for runnable nodes. - Lifecycle: core emits
scope: 'suite-run-start'/scope: 'suite-run-finished'reporter events. - Per-item: core emits
scope: 'suite-item'withstatus: 'running' | 'passed' | 'failed'and the relatedid. - Step routing: child runs receive
id, and downstream test-step events should be routed byid(extension currently backfillsidusingrunIdmapping when needed).
Open follow-ups (community, 2026-11-14)
Not urgent — no current testlight breaking changes — but keep in mind:
- CI docs (pinning): Quick-start may keep floating
npxfor try-it. Production CI docs should say to pinmshobeyri/testlight-action@v1(or lockmmt-testlightinpackage.json+ lockfile). Floating runner ⇒ green can break with no.mmtchange. - MCP scaffold (
mmtmcp/): When changingscaffold_test/ agent write paths, prefer PR-ready.mmtwith real asserts/schema (“receipt”). Avoid defaults that only pass against invented mocks so agents don’t ship green fiction.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

