AAC (MVP)

Minimal Node/TypeScript server + CLI for the Agent-Aware Collaboration (AAC) MVP:

• Realtime awareness via WebSocket events
• Redis-backed presence + leases
• Postgres-backed Change Capsules
• Hosted-first onboarding via CLI (aac init, aac watch)

Requirements

• Node.js >= 18
• Redis
• Postgres

Environment

PORT=8080
REDIS_URL=redis://127.0.0.1:6379
PG_URL=postgres://postgres:[email protected]:5432/aac
PRESENCE_TTL_SECONDS=30
LEASE_TTL_SECONDS=300
JWT_SECRET=replace_me
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_APP_SLUG=your-app-slug
GITHUB_WEBHOOK_SECRET=...
PUBLIC_BASE_URL=http://localhost:8080

Install & Run

npm install
npm run dev

CLI (Hosted-First)

Initialize the repo and start monitoring immediately:

npm install
npm run build
./dist/cli/index.js init

This writes .aac/config.json in the repo and starts emitting events to the hosted server. Repo registration is optional by default. Use --no-watch to only initialize without starting monitoring. Use --require-app to force GitHub App install (org mode). Use --output json to stream warnings as machine-readable JSON. Use --notify-webhook <url> to POST warnings to an agent endpoint. Use --exit-on-warning to stop watching after the first conflict signal.

Help

Show available commands and options:

npx @martin0x/aac --help
npx @martin0x/aac init --help
npx @martin0x/aac watch --help
npx @martin0x/aac agent --help
npx @martin0x/aac preflight --help

GitHub Integration

1. Create a GitHub OAuth App and set:

• Authorization callback URL: https://<your-host>/auth/github/callback

2. Create a GitHub App, subscribe to webhooks:

• Events: installation, installation_repositories
• Webhook URL: https://<your-host>/github/webhook

3. Set the env vars above on the server.

Org Mode (Optional)

Require GitHub App install and repo registration:

npx @martin0x/aac init --require-app
npx @martin0x/aac org install

Agent Wrapper (Fully Automated)

Run an agent command and auto-stop on conflicts:

./dist/cli/index.js agent --server http://localhost:8080 -- your-agent-command --arg1 --arg2

Run with Docker

docker compose up --build

HTTP Endpoints

• GET /health
• POST /capsules
• PATCH /capsules/:id
• POST /capsules/:id/seal
• GET /capsules/:id
• POST /leases/request
• POST /leases/override
• GET /leases/:boundaryId

WebSocket

Connect to the same server and send JSON events matching the AAC realtime schema:

• session_start
• intent_update
• editing_file
• touched_boundary
• lease_request
• override_recorded
• heartbeat