Skip to content

Commit 1d1d396

Browse files
AnExiledDevAnExiledDev
committed
Update docs, tests, and config across packages
- Add dashboard and memories feature docs, update astro sidebar config - Expand plugin guard tests with edge cases and new test fixtures - Add pyproject.toml, dashboard README, CLI README task subcommands - Update changelog, architecture, and getting-started docs
1 parent 4d8a675 commit 1d1d396

31 files changed

+2756
-66
lines changed

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Each package has its own `CLAUDE.md` with package-specific development rules:
2727
- [`container/CLAUDE.md`](container/CLAUDE.md) — changelog, documentation, and configuration rules for the devcontainer package
2828
- `cli/` — Bun/TypeScript CLI; run `bun test` for tests
2929
- `docs/` — Astro/Starlight site; run `npm run build` to verify
30-
- [`dashboard/CLAUDE.md`](dashboard/CLAUDE.md) — Svelte 5 SPA + Bun backend for session analytics
30+
- [`dashboard/CLAUDE.md`](dashboard/CLAUDE.md) | [`dashboard/README.md`](dashboard/README.md) — Svelte 5 SPA + Bun backend for session analytics
3131

3232
### Cross-Package Changes
3333

‎cli/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,12 @@ codeforge session list # List recent sessions
3737
codeforge session show <id> # Show session details
3838
```
3939

40-
### `codeforge task` — Task Search
40+
### `codeforge task` — Task Management
4141

4242
```bash
4343
codeforge task search "query" # Search tasks across sessions
44+
codeforge task list # List tasks
45+
codeforge task show <id> # Show task details
4446
```
4547

4648
### `codeforge plan` — Plan Search

‎dashboard/README.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# CodeForge Dashboard
2+
3+
Session analytics dashboard for Claude Code. Parses JSONL session files into a SQLite database and serves a Svelte 5 SPA for browsing sessions, conversations, plans, tasks, agents, and memory.
4+
5+
> **v0.1.0** — Ships with CodeForge v2.1.1.
6+
7+
## Quick Start
8+
9+
```bash
10+
# Development — starts the Bun backend (port 5173)
11+
bun run dev
12+
13+
# Development — starts only the Vite frontend dev server
14+
bun run dev:web
15+
16+
# Build the SPA for production
17+
bun run build
18+
19+
# Preview the production build
20+
bun run preview
21+
22+
# Run tests
23+
bun test
24+
```
25+
26+
Requires [Bun](https://bun.sh) >= 1.0.0.
27+
28+
## Architecture
29+
30+
The dashboard is a three-layer pipeline:
31+
32+
1. **Parser** (`src/parser/`) — Reads `~/.claude/` session JSONL files, detects projects, extracts messages/tokens/tool calls, and writes everything into a local SQLite database at `~/.codeforge/data/dashboard.db`.
33+
2. **Server** (`src/server/`) — A `Bun.serve` HTTP server that exposes a REST API over the database, watches for file changes via SSE, and runs memory analysis.
34+
3. **Web** (`src/web/`) — A Svelte 5 SPA built with SvelteKit's static adapter. Routes, components, and shared state live here.
35+
36+
## Tech Stack
37+
38+
| Layer | Technology |
39+
|-------|------------|
40+
| Runtime | Bun |
41+
| Frontend | Svelte 5, SvelteKit (static adapter) |
42+
| Styling | TailwindCSS 4 |
43+
| Charts | LayerChart (d3-scale) |
44+
| Database | SQLite (bun:sqlite, WAL mode) |
45+
| Markdown | marked + shiki |
46+
| Build | Vite 8 |
47+
| Language | TypeScript 5 |
48+
49+
## API Reference
50+
51+
All endpoints are defined in `src/server/routes/api.ts`.
52+
53+
### GET Endpoints
54+
55+
| Path | Description |
56+
|------|-------------|
57+
| `/api/projects` | List all projects |
58+
| `/api/projects/:id` | Project detail |
59+
| `/api/sessions` | List sessions (filterable by project, model, since; paginated) |
60+
| `/api/sessions/:id` | Session detail (tokens, files touched, cost, agents) |
61+
| `/api/sessions/:id/messages` | Session messages (supports incremental fetch via afterId) |
62+
| `/api/sessions/:id/plan` | Plan associated with session |
63+
| `/api/sessions/:id/context` | Context snapshots (memories, rules) for session |
64+
| `/api/sessions/:id/tasks` | Tasks for the session's team |
65+
| `/api/sessions/:id/agents` | Subagents spawned by session |
66+
| `/api/analytics/global` | Global analytics (filterable by date range) |
67+
| `/api/analytics/project/:id` | Per-project analytics |
68+
| `/api/plans` | List all plans |
69+
| `/api/plans/:slug/history` | Plan version history |
70+
| `/api/tasks` | List all task teams |
71+
| `/api/agents` | List all agents across sessions |
72+
| `/api/context` | All context files (memories, rules) |
73+
| `/api/search` | Full-text search across messages (query, project, role filters) |
74+
| `/api/ingestion/status` | Parser ingestion status |
75+
| `/api/memory/runs` | List memory analysis runs |
76+
| `/api/memory/runs/:id` | Memory run detail (events, result) |
77+
| `/api/memory/observations` | List observations (filterable by project, category, status) |
78+
| `/api/memory/observations/:id/history` | Observation change history |
79+
| `/api/memory/memories` | List approved memories |
80+
| `/api/memory/stats` | Memory statistics |
81+
| `/api/memory/stats-by-project` | Observation stats grouped by project |
82+
83+
### POST Endpoints
84+
85+
| Path | Description |
86+
|------|-------------|
87+
| `/api/memory/analyze` | Trigger memory analysis for a session |
88+
| `/api/memory/maintain` | Trigger maintenance for a project |
89+
| `/api/memory/analyze-project` | Trigger project-wide analysis |
90+
| `/api/memory/observations/:id/approve` | Promote observation to memory |
91+
| `/api/memory/observations/:id/dismiss` | Dismiss an observation |
92+
| `/api/memory/memories/:id/revoke` | Revoke an approved memory |
93+
94+
## Database Schema
95+
96+
The SQLite database (`~/.codeforge/data/dashboard.db`) uses WAL mode. Core tables defined in `src/parser/db.ts`:
97+
98+
| Table | Purpose |
99+
|-------|---------|
100+
| `projects` | Detected project paths and names |
101+
| `sessions` | One row per session — tokens, timestamps, git branch, parent/agent info |
102+
| `messages` | Individual messages with role, tokens, model, and raw JSON |
103+
| `messages_fts` | FTS5 virtual table for full-text search |
104+
| `tool_calls` | Tool invocations extracted from assistant messages |
105+
| `files_touched` | Files read/written/edited per session |
106+
| `history_entries` | Session history with display text and project |
107+
| `file_changes` | Write/edit operations with content diffs |
108+
| `plan_snapshots` | Plan content captured at points in time |
109+
| `context_snapshots` | CLAUDE.md, memory, and rule file snapshots |
110+
| `file_snapshots` | Arbitrary file content snapshots |
111+
| `subagents` | Agent spawns linked to parent sessions |
112+
| `memory_runs` | Memory analysis run metadata and results |
113+
| `observations` | Extracted observations with status lifecycle |
114+
| `memories` | Promoted memories with category and confidence |
115+
| `run_observations` | Join table: runs to observations |
116+
| `observation_history` | Audit log of observation changes |
117+
118+
## Project Structure
119+
120+
```
121+
dashboard/
122+
bin/codeforge-dashboard # CLI entry point (bash)
123+
src/
124+
parser/ # Session file parsing and database
125+
db.ts # Schema, migrations, connection management
126+
types.ts # TypeScript interfaces for messages/sessions
127+
queries.ts # All database query functions
128+
server/ # Bun HTTP server
129+
index.ts # Server entry point
130+
routes/api.ts # REST API route handlers
131+
memory-analyzer.js # AI-powered memory extraction
132+
memory-sync.js # Sync memories to MEMORY.md files
133+
web/ # Svelte 5 SPA
134+
routes/ # SvelteKit file-based routes
135+
lib/ # Shared components and utilities
136+
app.html # HTML template
137+
tests/
138+
parser/ # Parser unit tests
139+
server/ # API and server tests
140+
mockups/ # Static HTML mockups for design validation
141+
svelte.config.js # SvelteKit config (static adapter)
142+
package.json
143+
```
144+
145+
## Design Decisions
146+
147+
- **Read-only** — The dashboard never writes to `~/.claude/` session files. All state lives in its own SQLite database.
148+
- **Dark mode only** — No light theme. Simplifies the CSS and matches terminal-centric workflows.
149+
- **Svelte 5 runes** — Uses `$state`, `$derived`, `$effect` instead of Svelte stores. Global `runes: true` is NOT set in `svelte.config.js` (LayerChart incompatibility).
150+
- **Fork, don't import** — Patterns from `cli/` are forked into the dashboard. The CLI is never imported as a dependency.
151+
- **ISO 8601 UTC** — All timestamps stored and displayed in UTC.
152+
- **Static SPA adapter** — SvelteKit builds to a static `index.html` with client-side routing, served by the Bun backend.
153+
- **Session ID prefix matching** — API endpoints accept partial session IDs and resolve them via prefix match.
154+
155+
## Testing
156+
157+
```bash
158+
bun test
159+
```
160+
161+
Tests live in `tests/` and cover:
162+
163+
| File | Coverage |
164+
|------|----------|
165+
| `tests/parser/analytics.test.ts` | Token analytics and aggregation |
166+
| `tests/parser/cost.test.ts` | Cost estimation logic |
167+
| `tests/parser/project-detector.test.ts` | Project path detection |
168+
| `tests/parser/session-reader.test.ts` | JSONL session file parsing |
169+
| `tests/server/api.test.ts` | API route handlers |
170+
| `tests/server/event-bus.test.ts` | SSE event bus |
171+
| `tests/server/file-snapshots.test.ts` | File snapshot capture |
172+
173+
## License
174+
175+
GPL-3.0 — see [LICENSE](../LICENSE.txt).

‎docs/astro.config.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,8 @@ export default defineConfig({
167167
label: "Code Intelligence",
168168
slug: "features/code-intelligence",
169169
},
170+
{ label: "Dashboard", slug: "features/dashboard" },
171+
{ label: "Memories", slug: "features/memories" },
170172
],
171173
},
172174
{

‎docs/src/content/docs/customization/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ DevContainer features install runtimes and tools. CodeForge pins external featur
192192
// "ghcr.io/devcontainers/features/rust:1.5.0": { "version": "latest" }, // Opt-in
193193
"ghcr.io/anthropics/devcontainer-features/claude-code:1.0.5": {},
194194
"./features/ruff": { "version": "latest" },
195-
// "./features/ccms": {} // Currently disabled — replacement pending
195+
// "./features/ccms": {} // Currently disabled — replaced by `codeforge session search`
196196
}
197197
}
198198
```

‎docs/src/content/docs/features/dashboard.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Dashboard
3+
description: Visual analytics dashboard for Claude Code sessions — cost tracking, session replay, activity heatmaps, and real-time updates.
4+
sidebar:
5+
order: 6
6+
---
7+
8+
CodeForge includes a visual analytics dashboard — a Svelte 5 single-page application backed by a Bun HTTP server — that gives you a complete picture of your Claude Code usage. Browse sessions, replay conversations, track costs, and analyze token consumption patterns across projects, all from a dark-mode web interface.
9+
10+
## Accessing the Dashboard
11+
12+
The dashboard runs on **port 7847** and auto-launches when your DevContainer starts. You can also start it manually:
13+
14+
```bash
15+
codeforge-dashboard
16+
```
17+
18+
Once running, open `http://localhost:7847` in your browser. If you are using VS Code with port forwarding, the port is forwarded automatically.
19+
20+
## Analytics Overview
21+
22+
The main dashboard page shows a comprehensive set of analytics widgets covering your Claude Code usage. All widgets respect the active time range filter.
23+
24+
### KPI Cards
25+
26+
Four summary cards at the top of the page show key metrics at a glance:
27+
28+
| Card | What It Shows |
29+
|------|---------------|
30+
| **Sessions** | Total session count in the selected time range |
31+
| **Tokens** | Combined input and output token consumption |
32+
| **Cost** | Estimated API cost based on token usage and model pricing |
33+
| **Cache Efficiency** | Ratio of cache-read tokens to total input tokens |
34+
35+
### Charts and Visualizations
36+
37+
The dashboard provides a rich set of charts for deeper analysis:
38+
39+
| Widget | Description |
40+
|--------|-------------|
41+
| **Activity Heatmap** | GitHub-style calendar heatmap showing daily session activity |
42+
| **Cost Chart** | Cost over time, broken down by day |
43+
| **Token Trends** | Input and output token usage over time |
44+
| **Model Comparison** | Table comparing token usage, cost, and efficiency across models |
45+
| **Session Scatter Plot** | Sessions plotted by duration vs. token count to spot outliers |
46+
| **Project Costs** | Per-project cost breakdown chart |
47+
| **Model Distribution** | Pie/donut chart showing model usage proportions |
48+
| **Tool Usage** | Which Claude Code tools are used most frequently |
49+
| **Cache Efficiency** | Cache hit rate trends over time |
50+
| **Hourly Heatmap** | Session activity by hour-of-day and day-of-week |
51+
| **Duration Distribution** | Histogram of session durations |
52+
| **Insights Bar** | Auto-generated insights and anomaly highlights |
53+
54+
### Time Range Filtering
55+
56+
A time range selector at the top of the dashboard lets you scope all analytics to a specific window:
57+
58+
- **7 days** — last week of activity
59+
- **30 days** — last month
60+
- **90 days** — last quarter
61+
- **All time** — everything available
62+
63+
## Session Browsing and Replay
64+
65+
The **Sessions** page lists all parsed sessions with filtering by project, model, and time range. Each session row shows the project, model, token count, duration, and cost.
66+
67+
### Conversation Replay
68+
69+
Click any session to open the full conversation replay view. This renders the complete exchange between you and Claude, including:
70+
71+
- **Message bubbles** — user and assistant messages in a chat-style layout
72+
- **Tool call blocks** — expandable blocks showing tool invocations and their results
73+
- **Thinking blocks** — Claude's extended thinking content, when present
74+
- **Conversation search** — search within the current session's messages
75+
76+
### Session Detail Tabs
77+
78+
Each session detail page includes additional tabs for deeper inspection:
79+
80+
| Tab | Content |
81+
|-----|---------|
82+
| **Context** | CLAUDE.md files and memory files that were loaded into the session |
83+
| **Plan** | The session's plan (if one was created), with version history |
84+
| **Tasks** | Task list and progress for team sessions |
85+
| **Agents** | Timeline of subagent spawns, showing agent type, model, duration, and token usage |
86+
87+
## Search
88+
89+
The dashboard provides full-text search across all sessions from the top navigation bar. Search results show matching messages with context, linked back to their source sessions. Within a session detail view, conversation search lets you find specific messages in long sessions.
90+
91+
## Project Analytics
92+
93+
The **Projects** page shows per-project analytics:
94+
95+
- Session counts and activity timeline
96+
- Cost breakdown by project
97+
- Token usage patterns
98+
- Drill-down to individual sessions within a project
99+
100+
## Real-Time Updates
101+
102+
The dashboard uses **Server-Sent Events (SSE)** to push updates when new sessions are detected or existing sessions are modified. Active sessions show a live indicator, and analytics refresh automatically as new data arrives — no manual page refresh needed.
103+
104+
## Routes
105+
106+
The dashboard provides these pages:
107+
108+
| Route | Page |
109+
|-------|------|
110+
| `/` | Analytics overview with all charts and KPIs |
111+
| `/sessions` | Session list with filtering |
112+
| `/sessions/:id` | Session detail with conversation replay |
113+
| `/projects` | Project list with per-project analytics |
114+
| `/projects/:project` | Individual project detail |
115+
| `/plans` | Plan browser |
116+
| `/tasks` | Task browser for team sessions |
117+
| `/agents` | Agent activity across all sessions |
118+
| `/memories` | Memory management (see [Memories](./memories/)) |
119+
| `/context` | Context file browser |
120+
121+
## Related
122+
123+
- [Memories](./memories/) — memory management system accessible from the dashboard
124+
- [CLI Tools](./tools/) — `codeforge-dashboard` command reference
125+
- [Commands Reference](../reference/commands/) — all CLI commands

0 commit comments

Comments
 (0)