Configuration management and real-time agent monitoring platform for Claude Code, with AG-UI protocol support
| Formation | Ports | Skills |
|---|---|---|
 |
 |
 |
| Ralph | Timeline |
|---|---|
 |
 |
CCEM is a three-component system for managing Claude Code environments at scale:
-
TypeScript CLI/TUI (
@ccem/core) - Merge configurations across projects, audit for security issues, back up and restore settings, discover forks in conversation history, and validate schemas. Includes a full interactive terminal UI. -
APM v4/v5 (Phoenix/Elixir) - A persistent real-time dashboard server running on port 3032 that tracks Claude Code agent activity across multiple projects simultaneously. Provides token usage tracking, D3.js dependency graphs, Ralph methodology visualization, toast notifications, UPM execution tracking, port management, AG-UI protocol event streaming, and a built-in documentation wiki.
-
CCEM Agent (SwiftUI/macOS) - A native macOS menubar application that surfaces APM data at a glance: project count, active sessions, UPM wave progress, story pass rates, and quick links to the dashboard and docs.
-
AG-UI Elixir SDK (
ag_ui) - A standalone Elixir library implementing the AG-UI (Agent-User Interaction) protocol. Provides 15 core type structs, 30 event structs, SSE and JSON encoding, Phoenix Channel transport, middleware pipeline, RFC 6902 JSON Patch state management, and an HTTP agent client. 75 tests, 0 failures. Source at~/Developer/ag-ui-elixir/ag_ui/.
| Feature | Component | Status |
|---|---|---|
| Config merge (5 strategies: recommended, default, conservative, hybrid, custom) | CLI/TUI | Stable |
| Fork discovery from conversation history | CLI/TUI | Stable |
| Security audit with severity filtering | CLI/TUI | Stable |
| Backup and restore (compressed tar.gz) | CLI/TUI | Stable |
| Schema validation (Zod) | CLI/TUI | Stable |
| Interactive TUI (6 views, keyboard navigation) | CLI/TUI | Stable |
| Real-time APM dashboard (Phoenix LiveView) | APM v4 | Stable |
| Agent fleet monitoring (token usage, tool calls, status) | APM v4 | Stable |
Multi-project tenancy (?project=<name> scoping) |
APM v4 | Stable |
| UPM execution tracking (waves, stories, pass rates) | APM v4 | Stable |
| D3.js dependency graph (agent relationships by tier) | APM v4 | Stable |
| Ralph methodology display (flowchart + story progress) | APM v4 | Stable |
| Toast notification system (browser + in-app) | APM v4 | Stable |
Documentation wiki at /docs |
APM v4 | Stable |
Formation system (/formation) |
APM v4 | Stable |
| Port manager (clash detection, assignment) | APM v4 | Stable |
Skills tracking (/skills) |
APM v4 | Stable |
Session timeline (/timeline) |
APM v4 | Stable |
| AG-UI SSE event stream (v1) | APM v4 | Stable |
| AG-UI v2 protocol integration (EventRouter, HookBridge, StateManager) | APM v5 | Dev |
AG-UI v2 REST + SSE endpoints (/api/v2/ag-ui/*) |
APM v5 | Dev |
| AG-UI Elixir SDK (standalone library) | ag_ui | Stable |
| v2 REST API (SLOs, alerts, audit log, OpenAPI spec) | APM v4 | Stable |
| v3 backward-compatible API endpoints (19 legacy routes) | APM v4 | Stable |
| SwiftUI macOS menubar agent | CCEM Agent | Stable |
| Launch at login (ServiceManagement) | CCEM Agent | Stable |
┌──────────────────────────────────────────────────────────────────┐
│ Developer Machine │
│ │
│ ┌─────────────────────┐ ┌──────────────────────────────┐ │
│ │ CCEM CLI/TUI │ │ CCEM Agent (SwiftUI) │ │
│ │ @ccem/core v2.2.1 │ │ macOS menubar │ │
│ │ TypeScript/Node 18 │ │ polling :3032/api/... │ │
│ │ │ │ - project count │ │
│ │ ccem merge │ │ - active sessions │ │
│ │ ccem backup │ │ - UPM wave/story progress │ │
│ │ ccem restore │ │ - open dashboard │ │
│ │ ccem audit │ │ - open /docs │ │
│ │ ccem validate │ └──────────────┬───────────────┘ │
│ │ ccem fork-discover │ │ HTTP │
│ │ ccem tui │ │ │
│ └──────────┬───────────┘ │ │
│ │ apm_config.json │ │
│ │ session_init.sh hook │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ APM v4/v5 :3032 │ │
│ │ Phoenix 1.8 / Elixir 1.15 │ │
│ │ │ │
│ │ OTP Supervision Tree │ │
│ │ ├── ConfigLoader ├── AgentRegistry │ │
│ │ ├── DashboardStore ├── UpmStore │ │
│ │ ├── ApiKeyStore ├── SkillTracker │ │
│ │ ├── AuditLog ├── AlertRulesEngine │ │
│ │ ├── ProjectStore ├── MetricsCollector │ │
│ │ ├── SloEngine ├── EventStream │ │
│ │ ├── AgentDiscovery ├── EnvironmentScanner │ │
│ │ ├── CommandRunner ├── DocsStore │ │
│ │ ├── PortManager ├── AG-UI EventRouter │ │
│ │ ├── AG-UI HookBridge ├── AG-UI StateManager │ │
│ │ └── ...30+ GenServers total │ │
│ │ │ │
│ │ LiveViews: Dashboard, AllProjects, RalphFlowchart, │ │
│ │ Skills, SessionTimeline, Docs, Formation, │ │
│ │ Ports │ │
│ │ │ │
│ │ REST API: /api (v3-compat + v4), /api/v2 (SLO/alerts) │ │
│ │ AG-UI API: /api/v2/ag-ui/* (emit, SSE, state, stats) │ │
│ │ ETS tables: agents, sessions, tasks, notifications │ │
│ │ PubSub: real-time LiveView updates │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Claude Code Sessions (multiple projects) │ │
│ │ session_init.sh → POST /api/register │ │
│ │ Heartbeats → POST /api/heartbeat │ │
│ │ Notifications → POST /api/notify │ │
│ │ UPM events → POST /api/upm/event │ │
│ └───────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
# Clone with submodules
git clone --recurse-submodules https://github.com/peguesj/ccem.git
cd ccem
# Install and build the TypeScript CLI
npm install
npm run build
# Set up and start APM v4
cd apm-v4
mix setup
mix phx.server
# Dashboard available at http://localhost:3032The APM server also starts automatically when Claude Code sessions begin, via the ~/Developer/ccem/apm/hooks/session_init.sh hook. The hook starts the server on port 3032 if it is not already running, then registers the current session.
# Merge configs across projects (5 strategies)
ccem merge --strategy recommended --config ./proj1/.claude ./proj2/.claude
# Create a compressed backup
ccem backup --source ~/.claude --compress 9
# Restore from backup
ccem restore backup.tar.gz --target ~/.claude --force
# Security audit (filter by severity)
ccem audit --config ~/.claude --severity high
# Validate a config file
ccem validate ~/.claude/config.json
# Analyze conversation history for fork points
ccem fork-discover --chat conversation.json
# Launch the interactive TUI
ccem tui# From inside a Claude Code session, use the /ccem slash command:
/ccem apm init # re-register current project
/ccem apm start # start server
/ccem apm stop # stop server
/ccem apm restart # restart server
/ccem apm status # check server health
/ccem apm open # open dashboard in browser| Route | Description |
|---|---|
GET / |
Main dashboard - agent fleet, token usage, project selector |
GET /apm-all |
All-projects overview |
GET /ralph |
Ralph methodology flowchart and story progress |
GET /skills |
Skills tracking view |
GET /timeline |
Session timeline |
GET /docs |
Documentation wiki (root) |
GET /docs/*path |
Documentation wiki (nested pages) |
GET /formation |
Formation system view |
GET /ports |
Port manager view |
GET /dev/dashboard |
Phoenix LiveDashboard (development only) |
| Route | Description |
|---|---|
GET /health |
Health check (v3-compatible) |
GET /api/status |
Server status and uptime |
GET /api/agents |
List registered agents |
GET /api/agents/discover |
Trigger agent discovery scan |
POST /api/register |
Register a new session/agent |
POST /api/agents/register |
Register agent (v3-compat alias) |
POST /api/agents/update |
Full agent update (v3-compat) |
POST /api/heartbeat |
Agent heartbeat |
POST /api/notify |
Send a notification |
GET /api/projects |
List all projects |
PATCH /api/projects |
Update project metadata |
GET /api/data |
Dashboard data snapshot (v3-compat) |
GET /api/notifications |
List notifications |
POST /api/notifications/add |
Add notification (v3-compat) |
POST /api/notifications/read-all |
Mark all notifications read |
GET /api/ralph |
Ralph story data |
GET /api/ralph/flowchart |
Ralph flowchart data |
GET /api/commands |
Registered slash commands |
POST /api/commands |
Register slash commands |
GET /api/input/pending |
Get pending input requests |
POST /api/input/request |
Create input request |
POST /api/input/respond |
Respond to input request |
POST /api/tasks/sync |
Replace project task list |
POST /api/config/reload |
Hot-reload multi-project config |
POST /api/reload |
Alias for config reload |
POST /api/plane/update |
Update Plane PM context |
POST /api/upm/register |
Register a UPM execution |
POST /api/upm/agent |
Register UPM agent |
POST /api/upm/event |
Post a UPM event |
GET /api/upm/status |
Current UPM execution status |
GET /api/ports |
List tracked ports |
POST /api/ports/scan |
Scan for active ports |
POST /api/ports/assign |
Assign a port to a project |
GET /api/ports/clashes |
Detect port conflicts |
POST /api/ports/set-primary |
Set primary port for project |
GET /api/skills |
List tracked skills |
POST /api/skills/track |
Track a skill invocation |
GET /api/environments |
List CCEM environments |
GET /api/environments/:name |
Get environment detail |
POST /api/environments/:name/exec |
Execute command in environment |
POST /api/environments/:name/session/start |
Launch Claude Code session |
POST /api/environments/:name/session/stop |
Kill Claude Code session |
GET /api/ag-ui/events |
AG-UI SSE event stream (v1) |
GET /api/a2ui/components |
A2UI declarative component specs |
POST /api/v2/ag-ui/emit |
Emit AG-UI events |
GET /api/v2/ag-ui/events |
AG-UI v2 SSE stream (all events) |
GET /api/v2/ag-ui/events/:agent_id |
AG-UI v2 SSE stream (per-agent) |
GET /api/v2/ag-ui/state/:agent_id |
Get agent state snapshot |
PUT /api/v2/ag-ui/state/:agent_id |
Set agent state (full snapshot) |
PATCH /api/v2/ag-ui/state/:agent_id |
Patch agent state (RFC 6902 delta) |
GET /api/v2/ag-ui/router/stats |
AG-UI routing statistics |
GET /api/v2/agents |
v2 agent list (paginated) |
GET /api/v2/agents/:id |
v2 agent detail with metrics |
GET /api/v2/sessions |
v2 session list |
GET /api/v2/metrics |
Fleet metrics |
GET /api/v2/metrics/:agent_id |
Per-agent metrics |
GET /api/v2/slos |
SLO definitions with error budgets |
GET /api/v2/slos/:name |
Single SLO with history |
GET /api/v2/alerts |
Alert history |
GET /api/v2/alerts/rules |
Alert rules |
POST /api/v2/alerts/rules |
Create alert rule |
GET /api/v2/audit |
Audit log |
GET /api/v2/export |
Export APM data (JSON or CSV) |
POST /api/v2/import |
Import APM data from JSON |
GET /api/v2/openapi.json |
OpenAPI specification |
CCEM APM v5 introduces the AG-UI (Agent-User Interaction) protocol as a parallel event layer alongside the existing REST API and PubSub infrastructure. This enables any AG-UI-compliant frontend or agent framework to observe CCEM agent activity in real time.
A standalone Elixir library at ~/Developer/ag-ui-elixir/ag_ui/ (Plane project: AGUI 3e16b3ea). Modules:
| Module | Description |
|---|---|
| Core Types | 15 structs: Message, RunConfig, Tool, ToolResult, Context, etc. |
| Core Events | 30 event structs across 7 categories (lifecycle, text, tool call, state, activity, reasoning, special) |
| EventEncoder | SSE and JSON encoding for all event types |
| SSE Transport | Server-Sent Events transport layer |
| Phoenix Channel Transport | WebSocket transport via Phoenix Channels |
| Middleware Pipeline | Composable event processing middleware |
| State Manager | RFC 6902 JSON Patch state sync (snapshot + delta) |
| HTTP Agent Client | Client for communicating with AG-UI agents |
Tests: 75 passing, 0 failures.
Three new GenServers under lib/apm_v4/ag_ui/ (Plane project: CCEM5 a898419a):
| GenServer | Description |
|---|---|
ApmV4.AgUi.EventRouter |
Routes AG-UI events to AgentRegistry, FormationStore, Dashboard, MetricsCollector |
ApmV4.AgUi.HookBridge |
Translates legacy hook payloads (register, heartbeat, notify, tool-use) to AG-UI events |
ApmV4.AgUi.StateManager |
ETS-backed per-agent state with snapshot/delta pattern |
| Method | Path | Description |
|---|---|---|
| POST | /api/v2/ag-ui/emit |
Emit AG-UI events into the router |
| GET | /api/v2/ag-ui/events |
SSE stream of all AG-UI events |
| GET | /api/v2/ag-ui/events/:agent_id |
SSE stream filtered to a single agent |
| GET | /api/v2/ag-ui/state/:agent_id |
Get current agent state snapshot |
| PUT | /api/v2/ag-ui/state/:agent_id |
Replace agent state (full snapshot) |
| PATCH | /api/v2/ag-ui/state/:agent_id |
Apply JSON Patch delta to agent state |
| GET | /api/v2/ag-ui/router/stats |
Routing statistics (event counts, subscribers) |
All existing v4 endpoints, hooks, and CCEMAgent polling continue to work unchanged. The HookBridge automatically translates legacy POST /api/register, POST /api/heartbeat, POST /api/notify, and tool-use payloads into AG-UI events, so existing integrations get AG-UI event emission for free.
The CCEM Agent is a native macOS application (Swift/SwiftUI) that lives in the menu bar and polls the APM server.
Location: CCEMAgent/ (Xcode project)
Features:
- Connection state indicator (connected / connecting / disconnected)
- Project count and active session count displayed in the header
- UPM wave progress bar with story pass rate when a UPM execution is active
- All/Active filter for environment rows
- Per-environment status rows with session details
- "Open Dashboard" button linking to
http://localhost:3032 - "Help & Docs" button linking to
http://localhost:3032/docs - Manual refresh
- "Launch at Login" toggle (ServiceManagement framework)
- Graceful degraded view when the APM server is unreachable
Build:
cd CCEMAgent
xcodebuild -scheme CCEMAgent -configuration Release build
The APM v4 server hosts a built-in documentation wiki at http://localhost:3032/docs.
The wiki content is served from apm-v4/priv/docs/ and rendered via the DocsStore GenServer and DocsLive LiveView. Markdown files are parsed with Earmark at startup.
Key wiki sections available in the browser:
- Getting started guide
- Dashboard usage
- Ralph methodology reference
- API reference
- Multi-project support
Static docs are also available in the docs/ and wiki/ directories of this repository.
| Document | Description |
|---|---|
| docs/architecture.md | System architecture overview |
| docs/apm-v4-api.md | Complete REST API reference |
| docs/configuration.md | Config files, schemas, hooks, environment variables |
| docs/deployment.md | Running, managing, and troubleshooting |
| docs/development-history.md | Project evolution from initial commit to APM v4 |
| wiki/Home.md | Wiki index |
CCEM APM provides first-class tracking for UPM (Universal Project Manager) executions. When /upm is invoked in a Claude Code session, the execution lifecycle is reported to APM v4 via dedicated endpoints.
What is tracked:
- UPM session registration (
POST /api/upm/register) - Individual agent registrations within the wave (
POST /api/upm/agent) - Story-level events: started, passed, failed (
POST /api/upm/event) - Current wave number, total waves, and aggregate pass rate (
GET /api/upm/status)
Dashboard surfaces:
- Main dashboard header shows active UPM wave and story progress bar
- SwiftUI menubar agent mirrors the same data for at-a-glance visibility
- Ralph flowchart view (
/ralph) shows methodology step and story statuses
APM v4 runs as a single persistent server and monitors all Claude Code projects on the machine simultaneously. Projects self-register when sessions start via the session_init.sh hook.
- Data is namespaced per project in ETS and
ProjectStore - All REST API endpoints accept an optional
?project=<name>query parameter for scoped queries - The dashboard project selector switches the active project view without reloading
apm_config.jsonat~/Developer/ccem/apm/apm_config.jsontracks the current project for hook-based registration
See wiki/Multi-Project-Support.md for details.
| Tool | Version |
|---|---|
| Node.js | 18+ |
| TypeScript | 5.3+ |
| Elixir | 1.15+ |
| Erlang/OTP | 26+ |
| Phoenix | 1.8+ |
| Xcode (optional, for CCEM Agent) | 15+ |
npm install
npm run build # compile TypeScript
npm run typecheck # tsc --noEmit
npm run lint # ESLint
npm test # Jest test suite (867 tests, 96.89% coverage)
npm run test:coverage # with coverage reportcd apm-v4
mix setup # deps.get + assets.setup + assets.build
mix compile --warnings-as-errors
mix test # 233 tests
mix phx.server # start dev server on :3032Pre-commit hook (runs automatically):
mix precommit # compile --warnings-as-errors + deps.unlock --unused + format + test- Fork the repository
- Create a feature branch:
git checkout -b feat/my-feature - TypeScript changes: ensure
npm testandnpm run typecheckpass - Elixir changes: ensure
mix precommitpasses - Open a pull request against
main
See CONTRIBUTING.md for detailed guidelines.
| Version | Notes |
|---|---|
| 5.0.0-dev | AG-UI protocol integration: Elixir SDK, EventRouter/HookBridge/StateManager GenServers, 7 new v2 endpoints, backward-compatible with all v4 APIs |
| 4.3.0 | Skills registry, background tasks, project scanner, action engine, CCEMAgent UI consistency |
| 2.2.1 | Multi-project awareness, port manager, formation system, docs wiki, AG-UI SSE, v2 API (SLOs, alerts, audit, OpenAPI) |
| 2.x | APM v4 (Phoenix/Elixir) with LiveView dashboard, UPM tracking, SwiftUI menubar agent |
| 1.0.0 | Initial CLI/TUI release - 7 commands, 867 tests, 96.89% coverage |
Full changelog: CHANGELOG.md
MIT - Jeremiah Pegues