Skip to content

CLAUDE.md

Latest commit

 

History

History
51 lines (35 loc) · 2.71 KB

CLAUDE.md

File metadata and controls

51 lines (35 loc) · 2.71 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claude Code Command Center (cccc) is a web-based monitoring and interaction hub for Claude Code sessions. It provides real-time visibility into active Claude processes, session history, usage statistics, and allows direct interaction with running sessions via a chat interface.

Development Commands

# Install dependencies
uv sync

# Run the application (any of these work)
uv run cccc                    # CLI entry point defined in pyproject.toml
uv run python -m src.main     # Direct module execution
uv run uvicorn src.main:app --host 0.0.0.0 --port 18799 --reload  # With auto-reload

The app runs at http://localhost:18799. There is no test suite yet.

Architecture

Backend: FastAPI (async) with Jinja2 templates, served by uvicorn on port 18799. Frontend: Server-rendered HTML with HTMX for live updates (5s polling) and Tailwind CSS via CDN.

Two core modules

  • src/main.py — FastAPI app with routes and Jinja2 template rendering. Routes: dashboard (/), session detail (/session/{id}), PID-to-session redirect (/pid/{pid}), chat endpoint (POST /session/{id}/chat), and HTMX partial (/partial/processes).

  • src/monitor.py — All Claude filesystem interaction logic. Reads from ~/.claude/ to discover processes (via psutil), session JSONL files, subagent conversations, plans, tasks, usage stats, and history. Contains the path-encoding/decoding logic for Claude's project directory structure.

Claude filesystem structure read by monitor.py

~/.claude/
├── projects/{encoded-path}/{session-id}.jsonl     # Session conversations
├── projects/{encoded-path}/{session-id}/subagents/ # Subagent conversations
├── plans/{session-id}*.md                          # Session plans
├── tasks/{session-id}/*.json                       # Active tasks
├── history.jsonl                                   # Global history
└── stats-cache.json                                # Usage statistics

Key patterns

  • Path encoding: Claude encodes project paths in ~/.claude/projects/ by replacing / with -. The decode_project_path() function reverses this by walking the filesystem to find valid path segments.
  • Session-PID resolution uses multiple fallback strategies: process open files, CLAUDE_SESSION_ID env var, CWD-to-project matching, and most-recent-session fallback.
  • Chat interaction shells out to claude --print --resume {session_id} {message} in the session's working directory.
  • Templates use a dark theme. Session messages are color-coded by type (user/assistant/subagent/tool call/pending).