Contributing to ADHDev

Thank you for your interest in contributing to ADHDev! 🦦

🔌 Adding a New Provider

Are you looking to add support for a new IDE, CLI, or ACP agent?

Providers live in the external vilmire/adhdev-providers repository. The daemon automatically downloads these providers on startup and mirrors the category-based structure in your local ~/.adhdev/providers/ directory.

👉 Start with the Provider Contribution Guide in the providers repository.

For a deeper walkthrough, see the provider guide on docs.adhf.dev.

---

🛠️ Contributing to ADHDev Core

If you want to contribute to the core ADHDev engine (the daemon, the web dashboard, or the DevConsole), you are in the right place.

Development Setup

git clone https://github.com/vilmire/adhdev.git
cd adhdev
npm install

# Canonical full build (encodes the current package order)
npm run build

# Common focused builds while iterating
npm run build -w packages/daemon-core
npm run build -w packages/web-standalone
npm run build -w packages/daemon-standalone

# Run the daemon (dashboard at http://localhost:3847)
node packages/daemon-standalone/dist/index.js

# Or use dev mode (Vite hot-reload for dashboard)
npm run dev

📁 Project Structure

packages/
├── daemon-core/           # Core engine — CDP, providers, commands, lifecycle
├── daemon-standalone/     # Self-hosted HTTP/WS server (localhost:3847)
├── session-host-core/     # Session registry + transport protocol
├── session-host-daemon/   # Long-lived session runtime (adhdev-sessiond)
├── terminal-mux-core/     # Terminal mux runtime
├── terminal-mux-control/  # Terminal mux control/storage helpers
├── terminal-mux-cli/      # adhmux client
├── terminal-render-web/   # Web terminal renderer
├── ghostty-vt-node/       # Ghostty VT bindings
├── web-core/              # Shared React components, pages, CSS design system
├── web-standalone/        # Standalone React dashboard (Vite + React)
└── web-devconsole/        # DevConsole — provider debugging tools

Key Source Files

Package	Key File	Purpose
daemon-core	src/boot/daemon-lifecycle.ts	initDaemonComponents() / shutdownDaemonComponents()
daemon-core	src/cdp/initializer.ts	DaemonCdpInitializer — multi-IDE CDP management
daemon-core	src/commands/router.ts	DaemonCommandRouter — unified command routing
daemon-core	src/providers/provider-loader.ts	ProviderLoader — load/update provider.js
daemon-standalone	src/index.ts	HTTP/WS server + lifecycle integration
web-core	src/pages/Dashboard.tsx	Main dashboard page

🏗️ Build Order

Use the root npm run build whenever possible. It already encodes the current dependency order, including the session-host and terminal-mux packages.

If you need to build selectively, keep the dependency chain in mind:

1. session-host-core / ghostty-vt-node
2. daemon-core / terminal-mux-core / terminal-mux-control
3. terminal-mux-cli / session-host-daemon / terminal-render-web
4. web-core
5. web-standalone / web-devconsole
6. daemon-standalone

🧪 Testing

# Type-check (no emit)
npx tsc --noEmit -p packages/daemon-core/tsconfig.json
npx tsc --noEmit -p packages/session-host-daemon/tsconfig.json
npx tsc --noEmit -p packages/daemon-standalone/tsconfig.json

# Run standalone daemon
node packages/daemon-standalone/dist/index.js
# Dashboard at http://localhost:3847

# Verify the build
head -1 packages/daemon-standalone/dist/index.js | grep '#!/usr/bin/env node'

📝 Code Style

• TypeScript strict mode
• Prefer explicit types over any — use unknown for generic data, cast with type guards
• JSDoc comments on public interfaces and exported functions
• Use standard React hooks for the frontend (no class components)

🔄 Development Workflow

1. Fork the repository and create a branch: git checkout -b feat/my-new-feature
2. Implement your changes in the appropriate package.
3. Build affected packages in dependency order.
4. Test by running the standalone daemon locally.
5. Submit a PR to the main branch.

❓ Need Help?

If you find a bug or have a feature request for the core engine, please open an Issue.

📜 Contributor License Agreement (CLA)

Before your Pull Request can be merged, you must sign our CLA.

When you open a PR, a bot will automatically prompt you. Reply with:

I have read the CLA Document and I hereby sign the CLA

This is a one-time step that allows ADHDev to distribute your contribution under both AGPL-3.0 and commercial licenses.