- Updated the documentation to indicate the total number of middleware hooks has increased from 18 to 19. - Adjusted references in the getting-started-plugin guide to ensure consistency with the updated middleware hook count. - Corrected the middleware hooks section in the plugin template to reflect the accurate total.
9.9 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Build & Run
pnpm install # Install dependencies
pnpm build # TypeScript compile (tsc)
pnpm build:publish # Bundle for npm publish (tsup → dist-publish/)
pnpm start # Run: node dist/cli.js
pnpm dev # Watch mode (tsc --watch)
pnpm test # Run tests (vitest)
Architecture
OpenACP bridges AI coding agents to messaging platforms via the Agent Client Protocol (ACP). The flow:
User (Telegram) → ChannelAdapter → OpenACPCore → Session → AgentInstance (ACP subprocess)
Project Layout
src/
cli.ts — CLI entry (start, install, uninstall, plugins, --version, --help)
main.ts — Server startup, plugin boot
index.ts — Public API exports
core/ — Core modules
config/ — Zod-validated config, migrations, editor
agents/ — Agent instance, catalog, installer, store
sessions/ — Session, session-manager, session-bridge, permission-gate
plugin/ — Plugin infrastructure (LifecycleManager, ServiceRegistry, MiddlewareChain, PluginContext)
commands/ — System chat commands (session, agents, admin, help, menu)
adapter-primitives/ — Shared adapter framework (MessagingAdapter, StreamAdapter, SendQueue, etc.)
utils/ — Logger, typed-emitter, file utilities
setup/ — First-run setup wizard
plugins/ — All plugins (adapters + services)
telegram/ — Telegram adapter (grammY)
slack/ — Slack adapter (@slack/bolt)
speech/ — TTS/STT (Edge TTS, Groq STT)
tunnel/ — Port forwarding (Cloudflare, ngrok, Bore, Tailscale)
security/ — Access control, rate limiting
usage/ — Cost tracking, budget
api-server/ — REST API + SSE
file-service/ — File I/O for agents
notifications/ — Cross-session alerts
context/ — Conversation history
cli/
commands/ — CLI commands (start, plugins, dev, etc.)
plugin-template/ — Scaffold templates for `openacp plugin create`
packages/
plugin-sdk/ — @openacp/plugin-sdk (types + testing utilities)
Core Abstractions
OpenACPCore (core.ts) — Registers adapters, routes messages, creates sessions, wires agent events to adapters. Accesses services via ServiceRegistry.
Session (session.ts) — Wraps an AgentInstance with a prompt queue (serial processing), auto-naming, and lifecycle management.
AgentInstance (agent-instance.ts) — Spawns agent subprocess, implements full ACP Client interface. Converts ACP events to AgentEvent types.
LifecycleManager (plugin/lifecycle-manager.ts) — Boots plugins in dependency order (topo-sort), manages setup/teardown, handles version migration.
ServiceRegistry (plugin/service-registry.ts) — Central service discovery. Plugins register services, core accesses them via typed interfaces.
CommandRegistry (command-registry.ts) — Central command registry for chat commands. System and plugin commands registered here, adapters dispatch via generic handler.
PluginContext (plugin/plugin-context.ts) — Scoped API for plugins: events, services, middleware, commands, storage, logging.
Plugin System
All features are plugins. Core only provides infrastructure (ServiceRegistry, MiddlewareChain, EventBus, LifecycleManager). Plugins register services, commands, and middleware in their setup() hook.
- 19 middleware hook points (message:incoming, agent:beforePrompt, permission:beforeRequest, etc.)
- 9 permission types (events:read, services:register, commands:register, etc.)
- Per-plugin settings via SettingsManager (~/.openacp/plugins//settings.json)
Adapter Patterns
- Topics (Telegram): Each session gets its own topic
- Callback routing: Permission buttons use
p:prefix, command buttons usec/prefix - Response renderers: Adapters render CommandResponse types (text, menu, list, confirm, error, silent) per platform
npm Publishing
Published as @openacp/cli on npm. Users install with npm install -g @openacp/cli.
pnpm build:publishbundles CLI via tsup + builds SDK via tsc- GitHub Action auto-publishes both
@openacp/cliand@openacp/plugin-sdkon tag push (v*) - Plugin system:
openacp plugin install <name>installs from npm to~/.openacp/plugins/
Versioning
Format: YYYY.MMDD.<patch> — e.g. 2026.327.1 is the first patch on March 27, 2026.
YYYY— yearMMDD— month (2-digit) + day (2-digit), leading zeros stripped by semver. Jan 5 =105, Mar 27 =327, Apr 1 =401, Dec 5 =1205<patch>— sequential patch number for that day, starting from 1
Documentation Sync
When changing code, you must update corresponding docs to keep code and documentation in sync:
- New features: Must update README and
docs/(GitBook) to describe the feature, usage, and config if applicable. - Feature updates: Update related docs to reflect changes.
- Bug fixes: Update docs if the bug relates to documented behavior. Not required if docs are still accurate.
- General rule: Do not merge code without updating docs for new features or changes. README is for users,
docs/is for both users and contributors. - Plugin Template Sync: When changing plugin API, architecture, PluginContext, CommandDef, middleware hooks, permissions, or anything affecting how plugins are written → must update plugin template at
src/cli/plugin-template/(especiallyclaude-md.tsandplugin-guide.ts) so templates always reflect the current API. These templates are the primary reference for both AI agents and plugin developers.
Conventions
- English only: All code, comments, commit messages, documentation, specs, plans, and any text in the repository must be written in English. No exceptions.
- ESM-only (
"type": "module"), all imports use.jsextension - TypeScript strict mode, target ES2022, NodeNext module resolution
Testing Conventions
General Principles
- Test framework: Vitest. Test files live in
src/**/__tests__/*.test.tsorsrc/**/*.test.ts. - Objective tests: Tests must be objective — verify behavior against specifications and expected outcomes, not against current implementation details. The source code is for understanding, but tests should validate what the code should do.
- Test flows, not internals: Focus on testing user-facing flows and integration between components rather than individual private methods. Test the public API surface.
- Edge cases matter: Always test boundary conditions, error paths, and state machine transitions. These are where bugs hide.
What to Test
- State machines: Test ALL valid transitions AND all invalid transitions. Verify events emitted on each transition.
- Flow tests: Test complete user flows end-to-end (e.g., message → session lookup → prompt → response → notification).
- Error recovery: Test that errors don't leave the system in a broken state. After an error, the system should be usable again.
- Concurrency: Test serial processing guarantees, queue ordering, lock behavior, and race conditions.
- Boundary values: Test exact boundaries (e.g.,
maxConcurrentSessionsat exactly the limit, budget at exactly the threshold). - Cleanup: Test that resources (timers, listeners, files) are cleaned up properly.
- Idempotency: Test double-calls (double connect, double disconnect, double resolve) are safe.
How to Write Tests
// Use vi.fn() for mocks, TypedEmitter for event-based mocks
function mockAgentInstance() {
const emitter = new TypedEmitter<{ agent_event: (event: AgentEvent) => void }>();
return Object.assign(emitter, {
sessionId: "agent-sess-1",
prompt: vi.fn().mockResolvedValue(undefined),
cancel: vi.fn().mockResolvedValue(undefined),
destroy: vi.fn().mockResolvedValue(undefined),
onPermissionRequest: vi.fn(),
}) as any;
}
- Mock at boundaries: Mock AgentInstance, ChannelAdapter, SessionStore — not internal classes.
- Use
vi.waitFor()for async assertions on fire-and-forget operations. - Use
vi.useFakeTimers()for timeout-based tests (e.g., PermissionGate timeout). - Cleanup in afterEach: Always destroy stores, clear timers, remove temp files.
- No sleep/polling: Use
await Promise.resolve()for microtask timing,vi.waitFor()for async ops.
Test Organization
src/core/__tests__/— Core module tests (session, bridge, queue, permissions, store, etc.)src/__tests__/— Integration tests and adapter-level testssrc/plugins/*/— Plugin-specific unit tests- Name files descriptively:
session-lifecycle.test.ts,session-bridge-autoapprove.test.ts
Backward Compatibility
Users who installed and ran older versions will have config, data, and storage in the old format. When adding or changing anything related, you must ensure backward compatibility:
- Config (
~/.openacp/config.json): When adding new fields to Zod schema, always use.default()or.optional()so old configs don't fail validation. Never rename or remove fields without migration. - Storage / Data files (
~/.openacp/): When changing data format (sessions, topics, state...), must handle old format — read old data and auto-migrate to new format if needed. Must not crash on data from previous versions. - CLI flags & commands: Do not remove or rename existing commands/flags. If deprecating, keep them working and log a warning.
- Plugin API: When changing interfaces that plugins use, must maintain backward compat or bump major version.
- General rule: New code must work with old data/config without requiring user action. If migration is needed, run it automatically on startup.