Core Concepts

Core Concepts

CCAM turns provider events and transcript history into a live, queryable view. These concepts make the UI and troubleshooting guides much easier to interpret.

The data flow

Claude Code / Codex
        │
        ├─ live hooks ───────────────┐
        └─ transcript import/mirror ─┤
                                    ▼
                              CCAM server
                         SQLite + live broadcasts
                                    │
                       ┌────────────┼────────────┐
                       ▼            ▼            ▼
                    Web UI         CLI          MCP

Live hooks give low-latency state changes. Transcript import fills historical detail and supports sources that do not send local hooks. The server persists normalized records in SQLite and broadcasts changes to connected clients.

Session

A session is one top-level provider run associated with a project or working directory. It has a lifecycle, provider, source, token/cost totals, agents, events, and transcript entries. A remote mirrored session may infer liveness from recent transcript activity because it cannot send local process hooks.

Agent

An agent is a participant inside a session. The main agent may spawn subagents, which can work in parallel and have their own state and tool activity. Agent state describes the most recent known condition; it is not a process supervisor.

Event and transcript entry

An event is normalized operational evidence such as a tool use, notification, lifecycle transition, or hook delivery. A transcript entry is the provider-native conversational record. Use events for sequence and filtering; use the transcript when you need the exact surrounding context.

Task and Kanban card

Tasks are work items surfaced from agent activity. The Kanban view groups them by progress state so you can see active, waiting, completed, and problematic work across sessions. A task is not the same as an OS process and may outlive one agent turn.

Source

The source identifies where the session was collected. Local sessions arrive from this machine. A remote data source is an SSH-accessible machine whose Claude and/or Codex transcript directories are mirrored and imported. Credentials remain with the host SSH stack; CCAM stores connection metadata, not passwords.

Live state versus durable history

Websocket updates make the UI feel live, but SQLite is the durable record. A disconnected browser can be stale while ingestion remains healthy. Conversely, a connected browser can display an old session correctly if no fresh hook or transcript has arrived. Always separate these questions:

1. Is the producer still generating activity?
2. Is CCAM receiving or importing it?
3. Is the server storing it?
4. Is this client displaying the newest stored state?

That four-step model drives the Troubleshooting Decision Tree.

Safety boundaries

• Hooks fail open so agent work is not blocked by monitoring.
• Remote hook destinations require HTTPS and a token.
• MCP is read-only unless mutations are explicitly enabled.
• Destructive MCP operations require a second gate and a confirmation token.
• Deleting a remote source retains imported data unless purge is explicitly requested.

Next: Reading the Dashboard.