- Fix adapter-reference.md and building-adapters.md (AdapterFactory → plugin pattern) - Fix contributing.md (src/adapters/ → src/plugins/) - Fix for-contributors.md (plugin-manager → PluginRegistry) - Update configuration.md for per-plugin settings - Update environment-variables.md for plugin-level env vars - Add system command handler tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3.6 KiB
Quick Start for Contributors
Welcome, and thank you for wanting to contribute! This guide gets your local development environment running so you can explore the code, fix bugs, or build new features.
Prerequisites
- Node.js 20 or later — check with
node --version - pnpm — OpenACP uses pnpm for package management. Install it with
npm install -g pnpm - Git
Set up the repository
# Clone the repo
git clone https://github.com/openacp/OpenACP.git
cd OpenACP
# Install dependencies
pnpm install
# Build the project
pnpm build
# Run the tests — everything should pass
pnpm test
# Start watch mode (rebuilds on every file save)
pnpm dev
That's it. You now have a fully working local build.
To run your local build instead of the globally installed version:
node dist/cli.js --version
Project structure
src/
cli.ts Entry point for the CLI (start, install, uninstall, plugins, --version, --help)
main.ts Server startup — registers adapters and starts listening
index.ts Public API exports (for use as a library)
core/ The heart of OpenACP
config.ts Zod-validated config loader (~/.openacp/config.json)
core.ts OpenACPCore — the main orchestrator
session.ts Session lifecycle, prompt queue, auto-naming
agent-instance.ts ACP subprocess client — spawns and talks to agents
channel.ts ChannelAdapter abstract base class
plugin/ Plugin system (PluginRegistry, LifecycleManager, PluginContext)
command-registry.ts Central command registry with namespace resolution
commands/ Built-in system command handlers
setup/ Interactive setup wizard and reconfigure flow
plugins/
telegram/ Telegram adapter plugin (grammY)
discord/ Discord adapter plugin
slack/ Slack adapter plugin
Key concepts
Understanding these three abstractions covers most of the codebase:
ChannelAdapter (src/core/channel.ts)
The abstract base that every platform integration extends. Implementations provide sendMessage, sendPermissionRequest, sendNotification, createSessionThread, and renameSessionThread. If you're adding a new platform, you're writing a ChannelAdapter.
Session (src/core/session.ts)
Represents one conversation between a user and an agent. It owns a prompt queue (so messages are processed serially, never in parallel), handles auto-naming after the first prompt, and manages the lifecycle of the underlying agent instance.
AgentInstance (src/core/agent-instance.ts)
The bridge between OpenACP and an AI agent. It spawns the agent as a subprocess, communicates via the ACP protocol, and converts ACP events into the internal AgentEvent types that the rest of the system understands.
Running a single test file
pnpm test src/core/__tests__/session-lifecycle.test.ts
Or run all tests in watch mode:
pnpm test --watch
Before you open a PR
- Make sure
pnpm buildcompletes without errors. - Make sure
pnpm testpasses. - For new features, add tests in
src/core/__tests__/or alongside the relevant module. - Follow the ESM-only convention — all imports use
.jsextensions, even for TypeScript source files.
Where to go next
- Contributing — PR process, code conventions, and testing guidelines
- Building Adapters — step-by-step guide to adding a new platform
- Plugin System — how the plugin system works