Start Here

Start Here

This path gets a local CCAM instance from zero to a trustworthy first session. It assumes Node.js 20+, npm, Git, and either Claude Code or Codex CLI are already available.

1. Install and start

git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
cd Claude-Code-Agent-Monitor
npm run setup
npm run dev

Open the URL printed by the development server. npm run setup installs dependencies, builds required components, and installs hooks. For a production-style local run, use npm run build followed by npm start.

2. Confirm the system is healthy

In another terminal:

npx ccam status
npx ccam health

Check four things before trusting the dashboard:

1. The server responds as healthy.
2. The dashboard establishes a live connection.
3. At least one provider's hooks are installed.
4. The data directory is writable and has free disk space.

If hooks are missing, run:

npm run install-hooks

Choose the provider or providers you actually use. Hook execution is intentionally non-blocking: a dashboard outage should not block your coding agent.

3. Generate a known event

Start a small Claude Code or Codex session in any test project, ask it to inspect a file, and end the session normally. In CCAM you should see:

• a session appear with its project and provider;
• the main agent's state change while it works;
• tool calls and transcript activity;
• token and cost totals after usage data arrives;
• the session eventually settle into a terminal state.

Do not begin by debugging an old or unusually large transcript. A short controlled session separates installation problems from historical-data edge cases.

4. Learn the status model

Read Core Concepts, especially the difference between a session, an agent, an event, and a task. A card that says “waiting” is not automatically stuck; it may be waiting for input, a child agent, or the next provider event.

5. Choose your operating path

• Solo/local use: Reading the Dashboard
• Shared or remote deployment: Deployment Decision Guide
• Automation: CLI Automation Patterns

First-session acceptance checklist

• Dashboard and CLI health checks succeed.
• A new session appears without manual import.
• Provider, project path, and timestamps look correct.
• A tool call is visible in the timeline or transcript.
• The final session state is sensible.
• Restarting CCAM preserves the session.

If any item fails, use the Troubleshooting Decision Tree rather than reinstalling blindly.