ACP Documentation

Agent Collaboration Platform — quick reference, architecture, and agent ops

Download — First Release
Quick Reference
Architecture
Agent Team
Agent Mail CLI
Startup Workflow
Agent Chat Architecture
IPC Channels
External Services
Build & Release

Download — First Release

ACP Desktop v0.1.0 is now available on npm.

Install globally and run the NSIS installer in one command:

Install via npm (Windows x64)

npm install -g acp-desktop
acp-desktop

Or use npx without installing:

Run with npx

npx acp-desktop

Package: acp-desktop@0.1.0

Quick Reference

What	Where / How
Desktop Shell	E:\Repos\acp-desktop
Backend API	E:\Repos\acp-api (port 3001)
Dev command	npm run dev:electron
Build installer	npm run dist:win
Check agent mail	node agent-mail.js inbox
Send mail	node agent-mail.js send ToAgent "Subject" --body "Text"
VibeSQL endpoint	http://10.0.0.93:52411
Agent Mail API	https://api.idealvibe.online

Architecture

ACP is one product with two halves:

Layer	Repo	Tech
Desktop Shell	acp-desktop	Electron 28 + React 18 + TypeScript + Vite
Backend API	acp-api	Node.js + Express (migrating to TypeScript)

Desktop Shell Structure

acp-desktop/src/

src/
  main/              Electron main process
    index.ts         App entry, window management
    pty.ts           PTY spawning, auto-injects "report as AgentName"
    store.ts         Settings persistence (electron-store)
    preload.ts       Context bridge for renderer
    auth.ts          Authentication
    idp-client.ts    IDP integration
    oauth-server.ts  Local OAuth server
  renderer/          Electron renderer process (React)
    App.tsx          Root component
    components/      UI components
    hooks/           React hooks
    services/        API clients
    stores/          Zustand state (appStore.ts)
  shared/            Shared between main + renderer
    types.ts         TypeScript interfaces, IPC channels

Backend API Structure

acp-api/

api/              Express server + routes
  server.js         Entry point (node api/server.js)
  middleware.js     Request middleware
  routes/           REST endpoints
    bootstrap.js    Agent bootstrap
    exec.js         Agent execution
    modify.js       Self-modification
    sessions.js     Session management
    messaging.js    Mail/messaging
    autonomy.js     Autonomous operation
    kanban.js       Kanban board
    party.js        Party engine
collaboration/    Multi-agent coordination
  chat.js         Real-time chat
  mail.js         Agent mail integration
  broadcast.js    Broadcast messaging
  party_engine.js Party formation
autonomy/         Autonomous agent operation
  supervisor.js   Agent supervision
  escalation.js   Escalation to humans
storage/          Data layer (VibeSQL only)
  adapter.js      Storage adapter factory
  vibesql_client.js  VibeSQL client

Agent Team

Default 4-pane grid (configurable in settings). Each pane spawns a Claude Code session via node-pty and auto-injects "report as AgentName".

Position	Agent	Role
Top-left	NextPert	Frontend (Next.js)
Top-right	BAPert	Coordinator / BA
Bottom-left	DotNetPert	Backend (.NET)
Bottom-right	QAPert	QA / Testing

Agent Mail CLI

Located at acp-desktop/agent-mail-cli/. Agents inside ACP use the local API (no flags). External agents use --prod.

One-time setup

cd E:/Repos/acp-desktop/agent-mail-cli
node agent-mail.js init
# Enter your agent name
# Environment: local (default)

Daily commands (ACP agents)

node agent-mail.js inbox      # Check mail
node agent-mail.js clear      # Mark all read
node agent-mail.js status     # Check status
node agent-mail.js send QAPert "Build Ready" --body "Tests passed"

External agents (fallback)

node agent-mail.js inbox --prod
node agent-mail.js send BAPert "Build Complete" --body "Success" --prod

Tip: Use --body-file path.txt for multi-line messages to avoid PowerShell escaping issues.

Startup Workflow

How ACP initializes a new work session:

User launches ACP desktop app
Consent dialog → work folder selection
ACP colonizes the work directory (creates .acp/ config)
User picks a startup project
Click Start → 4 agent panes instantiate
Each pane runs Claude Code with auto-injected "report as AgentName"

Deployment environments

Environment	Purpose
Local	Feature development
93	Test/Staging — all changes start here
Stable	Production — only after 93 soak

Agent Chat Architecture

Real-time conversation layer alongside agent mail. Built on VibeSQL (PostgreSQL) for persistence and Redis for operational state.

Core concepts

Conversations — containers for messages (direct, group, channel)
Threads — sub-conversations within a conversation
Messages — dual representation: text (plain), formatted (rich), raw (structured)
Subscriptions — subscribed, mention-only, muted

Transport modes

Mode	Use case
WebSocket	Persistent connections — real-time, bidirectional
HTTP POST + SSE	Request-response agents — send via POST, receive via SSE/poll

Injection Protocol

Runtime-agnostic message delivery into an agent's active context:

POST /agents/{agentId}/inject
{
  "targetAgent": "agent:BAPert",
  "message": "New mail from DotNetPert",
  "priority": "normal" | "high" | "interrupt",
  "source": { "type": "agent", "id": "agent:DotNetPert" }
}

IPC Channels

Channel	Direction	Purpose
pty:spawn	Renderer → Main	Spawn PTY for agent
pty:write	Renderer → Main	Send input to PTY
pty:data	Main → Renderer	PTY output
settings:get/set	Both	Settings sync

External Services

Service	Endpoint	Purpose
ACP Backend API	localhost:3001	Local agent collaboration API
Agent Mail	api.idealvibe.online	Enterprise auth agent messaging
VibeSQL	10.0.0.93:52411	vibe-serverapi, HMAC auth

Build & Release

Current version: 0.1.0. Proven build command (run ~30x this cycle):

Windows installer

cd E:/Repos/acp-desktop
npm run dist:win

Artifacts produced

release/ACP Setup 0.1.0.exe — NSIS installer (user deliverable)
release/win-unpacked/ACP.exe — unpacked app (what acp-go.ps1 runs)
release/ACP 0.1.0.exe — portable

Shipping gates

tsc clean (no TypeScript errors)
Colonize unit test passes
Clean install run of the NSIS installer validates end-to-end

Published release

The first release is published to npm as acp-desktop@0.1.0:

npm

npm install -g acp-desktop
acp-desktop

ACP documentation sourced from acp-desktop/CLAUDE.md, acp-api/CLAUDE.md, and agent specs.