Linting

ados plugin lint is a local, advisory analyzer. It unpacks a packed archive and checks every entry against a fixed rule set. The registry runs its own, narrower scan at submission, and every submission is reviewed before it is published (see Catalog and registry).

Quickstart

ados plugin lint extensions/my-plugin/dist/com.example.my-plugin-1.0.0.signed.adosplug

Output:

plugin com.example.my-plugin 1.0.0
archive size: 18432 bytes
score: 100/100
verdict: pass

no findings.

JSON form for CI:

ados plugin lint --json extensions/my-plugin/dist/com.example.my-plugin-1.0.0.signed.adosplug \
  | jq '.data.score, .data.passed'

Exit code 0 means pass. Exit code 1 means at least one finding at severity error or critical. The other exit codes are on the Plugin CLI reference.

What it checks

Findings are keyed by rule id, with a severity and the source location.

Python rules

Rule	Severity	What it flags
PY001-os-system	error	`os.system()` call
PY002-os-popen	error	`os.popen()` call
PY003-eval	error	`eval()` call
PY004-exec	error	`exec()` call
PY005-subprocess-shell	error	`subprocess` call with `shell=True`
PY006-raw-socket	error	`socket.socket(...)`
PY007-pickle-load	error	`pickle.load()` or `pickle.loads()`
PY008-marshal-loads	error	`marshal.load()` or `marshal.loads()`
PY009-ctypes-load	error	Native library load via `ctypes.CDLL` and friends
PY020-requests	warn	`requests`, `httpx`, `aiohttp`, `urllib3` or `urllib.request` used without `network.outbound`
FS001-open-write	info	File opened for writing (check the path is under the plugin’s data, config or temp dir)
FS002-shutil-rmtree	info	`shutil.rmtree()` (check the scope is the plugin’s own directory)

GCS bundle rules

Rule	Severity	What it flags
GCS001-top-location	warn	Reads `top.location` or `parent.location`
GCS002-document-cookie	warn	Reads `document.cookie`
GCS003-localstorage	warn	Reads `localStorage` or `sessionStorage`
GCS004-eval	warn	`eval()` call in the bundle
GCS005-function-ctor	warn	`new Function(...)`
GCS006-fetch-direct	warn	Direct `fetch()` call (use the host bridge)
GCS007-xhr-direct	warn	Direct `XMLHttpRequest`
GCS008-websocket-direct	warn	Direct `WebSocket`

Manifest and archive rules

Rule	Severity	What it flags
ARC001-archive-size	error	Archive exceeds the 50 MB archive cap
ARC002-entry-size	error	A single entry exceeds the 25 MB per-entry cap
ARC003-read-fail	error	An archive entry could not be read
SIG001-unsigned	warn	Archive carries no `SIGNATURE` file
VND001-vendor-binary	info	The manifest sets `agent.contains_vendor_binary` (see Vendor binaries)
PERM001-high-risk	info	The manifest declares any capability rated high or critical, for example `mavlink.write`, `process.spawn`, `estimator.pose.inject`, `flight.rate_setpoint`

info findings are advisory. warn findings show in the report but still pass. error and critical findings fail. Risk ratings come from the capability catalog on Permissions.

Score

Each finding deducts points, with a floor of 0:

Severity	Penalty
info	0
warn	2
error	10
critical	25

The score is for your own tracking. The verdict, not the score, sets the exit code.

Network imports and permissions

If your plugin uses requests, httpx, aiohttp, urllib3 or urllib.request, the linter warns unless the manifest declares network.outbound. The host enforces the capability at runtime either way.

False positives

The rules are plain pattern matches. A finding can fire on a comment or a data file. If a finding is wrong for your case, open an issue on the agent repo with the archive and the finding.

Manifest-versus-code check (monorepo)

Inside the ADOSExtensions monorepo, each extension’s GCS package has a lint:manifest script that checks the manifest against the code it describes:

pnpm -C extensions/my-plugin/gcs lint:manifest

It runs node scripts/lint-manifest.mjs ../manifest.yaml and exits 1 with one FAIL line per disagreement:

A telemetry.subscribe.<topic> permission with no matching ctx.telemetry.subscribe("<topic>") call, or a subscribe call with no matching permission.
A host-surface permission with no call site, on either half. On the agent half this includes every hardware.* permission.
A contributes slot with no implementation.
A version that disagrees across manifest.yaml, the extension package.json, gcs/package.json, the definePlugin({ version }) literal, and the agent half’s pyproject.toml or Cargo.toml.
A permission id that is neither in the capability catalog nor scoped to the plugin as plugin.<leaf>.<...>, where <leaf> is the last segment of the manifest id.
A documentation_url on the docs site whose page does not exist in a sibling Documentation checkout. The check is skipped with a note when no checkout is present; ADOS_DOCS_ROOT overrides the path.
An agent config read of a key that is in neither config-schema.json, a manifest config_key:, nor an agent write of that key.

node scripts/lint-manifest.mjs --self-test runs every case under scripts/lint-fixtures/. The repo’s extensions.yml workflow runs the manifest lint for each extension, together with a manifest schema check against the agent’s schema and the extension’s tests.

Run before every release

./scripts/pack.sh my-plugin
ADOS_SIGNING_KEY=keys/acme-2026-A.priv.pem ADOS_SIGNING_KEY_ID=acme-2026-A \
  ./scripts/sign.sh extensions/my-plugin/dist/com.example.my-plugin-1.0.0.adosplug
ados plugin lint \
  extensions/my-plugin/dist/com.example.my-plugin-1.0.0.signed.adosplug

Run the same steps in your release workflow before the GitHub Release upload, and let a failing lint block the release.

Next steps

Local install

Pack, sign and install the archive.

Signing keys

Generate and enrol your publisher key.

Permissions

Capability risk levels.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

Quickstart

What it checks

Python rules

GCS bundle rules

Manifest and archive rules

Score

Network imports and permissions

False positives

Manifest-versus-code check (monorepo)

Run before every release

Next steps

Local install

Signing keys

Permissions

​Quickstart

​What it checks

​Python rules

​GCS bundle rules

​Manifest and archive rules

​Score

​Network imports and permissions

​False positives

​Manifest-versus-code check (monorepo)

​Run before every release

​Next steps

Local install

Signing keys

Permissions

Quickstart

What it checks

Python rules

GCS bundle rules

Manifest and archive rules

Score

Network imports and permissions

False positives

Manifest-versus-code check (monorepo)

Run before every release

Next steps