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-manager.ts Plugin install/uninstall/load from ~/.openacp/plugins/
    setup/            Interactive setup wizard and reconfigure flow

  adapters/
    telegram/         Built-in Telegram adapter (grammY)
    discord/          Built-in Discord adapter
    slack/            Built-in Slack adapter

---

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

• 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