OpenACP/docs/gitbook/getting-started/for-contributors.md
0xmrpeter 63bee61daa fix: update outdated docs + add system command tests
- 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>
2026-03-26 22:14:52 +07:00

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 build completes without errors.
  • Make sure pnpm test passes.
  • For new features, add tests in src/core/__tests__/ or alongside the relevant module.
  • Follow the ESM-only convention — all imports use .js extensions, even for TypeScript source files.

Where to go next