open-index/open-npm huggingface dataset:
npm package: @martin0x/aac
Description: 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`)
Latest version: 0.1.8

# 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:postgres@127.0.0.1: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`