Contributing to ADHDev Providers

June 3, 2026 · View on GitHub

How to add new providers or improve existing ones for ADHDev.

Read this first

External contributions follow the CLI provider contract v1: docs/provider-contract/cli/v1.md.

That document is the source of truth for what a CLI provider must export, what input it receives, and what it returns. It exists so you do not have to read the daemon-core source to get started.

If you are looking at the implementations of the 4 production CLI providers (codex, claude, antigravity, hermes), the line-level audit in docs/provider-contract/cli/audit-cli-v1.md tells you which parts of each provider follow standard patterns (reusable in your own provider) vs which are provider-specific quirks.

For the bigger picture of where this is going — the provider marketplace, the SDK packages (@adhdev/provider-types, @adhdev/provider-schemas), declarative vs override tier, trust model — see the design document at adhdev-cloud/docs/design/provider-marketplace.md.

Validation

Every CLI provider must pass the v1 JSON schema. Validate locally:

node scripts/validate-cli-schema.mjs              # all CLI providers
node scripts/validate-cli-schema.mjs my-cli       # a specific one

CI runs the same check on every PR (see .github/workflows/validate-cli.yml). PRs that break schema validation are blocked from merging.

Quick Start

Inventory vs Support

This repository now distinguishes between:

Built-in inventory: a provider exists in the shipped registry and can be loaded by ADHDev
Verified support: the provider has been explicitly tested and promoted with evidence

Submitting a provider PR usually lands the first, not the second.

If you want a provider to graduate from unverified to partial or verified, include:

tested OS
tested provider version
exact flows validated
last validation date
known gaps or caveats
an evidence source such as a PR link, issue, or reproducible test note
updates to COMPATIBILITY.md and any user-facing support docs that claim verification

Use this operating sequence when doing promotion work:

Pick one provider only.
Decide the exact flows you are validating before you run anything.
Exercise the real daemon/runtime path, not just isolated script snippets.
Record both what worked and what failed.
Update the canonical support record in the main repo catalog.
Mirror the same result in this repository's COMPATIBILITY.md.
Prefer partial before verified.

If the result is ambiguous, keep the provider lower.

1. Fork & Clone

git clone https://github.com/YOUR_USERNAME/adhdev-providers.git
cd adhdev-providers

2. Create a Provider

# IDE provider
mkdir -p ide/my-ide/scripts/1.0
touch ide/my-ide/provider.json

# CLI agent
mkdir -p cli/my-cli
touch cli/my-cli/provider.json

# ACP agent
mkdir -p acp/my-agent
touch acp/my-agent/provider.json

# VS Code extension
mkdir -p extension/my-ext/scripts/1.0
touch extension/my-ext/provider.json

3. Provider Structure

provider.json (required)

{
  "type": "my-ide",
  "name": "My IDE",
  "category": "ide",
  "displayName": "My IDE",
  "icon": "🔧",
  "providerVersion": "1.0.0",
  "contractVersion": 2,
  "versionCommand": "my-ide --version",
  "compatibility": [
    { "ideVersion": ">=1.0.0", "scriptDir": "scripts/1.0" }
  ],
  "defaultScriptDir": "scripts/1.0",
  "cdpPorts": [9357, 9358],
  "cli": "my-ide",
  "processNames": { "darwin": "My IDE" },
  "paths": { "darwin": ["/Applications/My IDE.app"] }
}

scripts/1.0/scripts.js (IDE/Extension)

module.exports = {
  readChat() { return `(() => { /* DOM scraping */ })()`; },
  sendMessage(params) { const text = typeof params === 'string' ? params : params?.message; return `(() => { /* type + send */ })()`; },
  listModels() { return `(() => { /* list available models */ })()`; },
  setModel(model) { return `(() => { /* select model */ })()`; },
  // ... more scripts
};

Alternative: Individual Script Files

Instead of one scripts.js, you can create individual files:

scripts/1.0/
  read_chat.js          → exports single function, auto-mapped to readChat
  send_message.js       → sendMessage
  list_models.js        → listModels
  set_model.js          → setModel

Both approaches work. scripts.js takes priority if both exist.

📖 Full guide: Check the provider development section at docs.adhf.dev

4. Version Compatibility

The compatibility array maps IDE versions to script directories:

"compatibility": [
  { "ideVersion": ">=1.1.0", "scriptDir": "scripts/1.1" },
  { "ideVersion": ">=1.0.0", "scriptDir": "scripts/1.0" }
]

Rules:

Order matters: first match wins (most recent version first)
Version ranges use semver syntax: >=1.0.0, <2.0.0, >=1.0.0 <1.5.0
defaultScriptDir: required fallback when IDE/CLI version is unknown or doesn't match any range
CLI providers must also export parseSession from their versioned scripts.js when parse_session.js exists; daemon-core loads runtime hooks from scripts.js
Each script directory should be self-contained (all scripts for that version)

When to create a new version directory:

IDE DOM structure changed (selectors broke)
New UI elements to interact with
Major API changes

When NOT to create a new version:

Minor visual changes that don't affect selectors
Backend-only updates
Same DOM structure with new features (extend existing scripts)

5. Validate

# Syntax check
node -c ide/my-ide/scripts/1.0/scripts.js

# Schema validation (required fields, port conflicts, etc.)
node validate.js ide/my-ide/provider.json

# Validate all providers
node validate.js

6. Local Testing

# Copy your provider to the user directory for instant loading
mkdir -p ~/.adhdev/providers/ide/my-ide
cp -r ide/my-ide/* ~/.adhdev/providers/ide/my-ide/

# Restart daemon to pick up changes
# Stop your running adhdev-standalone process and start it again

# Test scripts via DevConsole
# Open http://127.0.0.1:19280 → IDE tab → Scripts → Run

7. Submit PR

git checkout -b feat/add-my-ide
git add -A
git commit -m "feat: add My IDE provider"
git push origin feat/add-my-ide
# Open a Pull Request on GitHub

registry.json is auto-regenerated by GitHub Actions — do not edit manually.

If your PR is also claiming support promotion, include compatibility evidence in the PR body. “It launched once” is not enough.

Good promotion PRs say:

OS
provider version
exact validated flows
known gaps
why the chosen status is still conservative

PR Checklist

node validate.js passes with no errors
type does not conflict with existing providers
CDP ports do not overlap (for IDE providers)
provider.json has providerVersion, contractVersion, compatibility, defaultScriptDir
At least readChat + sendMessage scripts implemented
Tested via DevConsole (if ADHDev is available)
registry.json NOT manually edited
If claiming support promotion: COMPATIBILITY.md updated with evidence and caveats

Reference Implementations

Category	Reference	Key Features
IDE	`ide/antigravity/`	`compatibility` matrix, versioned scripts
IDE (webview)	`ide/kiro/`	`webviewMatchText`, `webview*` scripts
CLI	`cli/gemini-cli/`	`aliases`, spawn config
ACP	`acp/gemini-cli/`	`auth`, `spawn`, `settings`
Extension	`extension/cline/`	`extensionIdPattern`, webview

CDP Port Registry

Port	Provider
9333–9334	Cursor
9335–9336	Antigravity
9337–9338	Windsurf
9339–9340	VS Code
9343–9344	VSCodium
9351–9352	Kiro
9353–9354	Trae
9355–9356	PearAI

Next available: 9357+

Need Help?

Full provider guide: docs.adhf.dev
DOM exploration tips & DevConsole usage are covered in the official docs site.