-
Notifications
You must be signed in to change notification settings - Fork 26
Expand file tree
/
Copy pathindex.html
More file actions
3786 lines (3554 loc) · 159 KB
/
index.html
File metadata and controls
3786 lines (3554 loc) · 159 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="icon" type="image/svg+xml" href="favicon.svg" />
<title>Claude Code Agent Monitor - Project Wiki</title>
<meta
name="description"
content="Comprehensive technical wiki for Claude Code Agent Monitor — real-time local monitoring with MCP server integration plus Claude Code and Codex extension scaffolding."
/>
<meta
name="keywords"
content="Claude Code, Codex, MCP, Model Context Protocol, Claude Code Agent Monitor, AI monitoring, real-time dashboard, WebSocket, SQLite, React, TypeScript, developer tools, session tracking, agent skills"
/>
<meta name="author" content="Son Nguyen Hoang" />
<meta name="robots" content="index, follow" />
<meta name="theme-color" content="#6366f1" />
<!-- Open Graph -->
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Claude Code Agent Monitor" />
<meta property="og:title" content="Claude Code Agent Monitor - Project Wiki" />
<meta
property="og:description"
content="Comprehensive technical wiki for Claude Code Agent Monitor — real-time local monitoring with MCP server integration plus Claude Code and Codex extension scaffolding."
/>
<meta property="og:image" content="og-image.svg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:type" content="image/svg+xml" />
<meta
property="og:image:alt"
content="Claude Code Agent Monitor — real-time Claude Code monitoring platform"
/>
<!-- Twitter / X Card -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Claude Code Agent Monitor - Project Wiki" />
<meta
name="twitter:description"
content="Real-time local monitoring for Claude Code agent activity with MCP integration, extension scaffolding, analytics, and WebSocket push."
/>
<meta name="twitter:image" content="og-image.svg" />
<meta
name="twitter:image:alt"
content="Claude Code Agent Monitor — real-time Claude Code monitoring platform"
/>
<meta name="twitter:creator" content="@hoangsonww" />
<!-- JSON-LD structured data -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "Claude Code Agent Monitor",
"description": "Real-time monitoring platform for Claude Code agent activity. Tracks sessions, agents, and tool events via native hooks, stores them in SQLite, and streams updates to a React UI over WebSocket.",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Windows, macOS, Linux",
"license": "https://opensource.org/licenses/MIT",
"author": {
"@type": "Person",
"name": "Son Nguyen Hoang",
"url": "https://sonnguyenhoang.com"
},
"codeRepository": "https://github.com/hoangsonww/Claude-Code-Agent-Monitor",
"programmingLanguage": ["TypeScript", "JavaScript", "Python"],
"runtimePlatform": "Node.js",
"keywords": "Claude Code, Codex, MCP, Model Context Protocol, agent monitoring, real-time dashboard, WebSocket, SQLite, React"
}
</script>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;600&display=swap"
/>
<link rel="stylesheet" href="wiki/style.css" />
<style>
:root {
--sidebar-expanded: 260px;
--sidebar-collapsed: 56px;
}
body {
--sidebar-current: var(--sidebar-expanded);
overflow-x: hidden;
}
body.sidebar-collapsed {
--sidebar-current: var(--sidebar-collapsed);
}
.sidebar {
display: flex !important;
position: fixed;
left: 0;
top: 0;
bottom: 0;
width: var(--sidebar-current);
overflow-x: hidden;
transition: width 0.2s ease;
}
.main-content {
margin-left: var(--sidebar-current) !important;
width: calc(100vw - var(--sidebar-current)) !important;
max-width: calc(100vw - var(--sidebar-current)) !important;
overflow-x: clip;
transition:
margin-left 0.2s ease,
width 0.2s ease;
}
.diagram-wrap .mermaid {
display: block;
width: 100%;
}
.diagram-wrap .mermaid svg {
width: 118%;
max-width: 118%;
height: auto;
}
.sidebar-topbar {
display: flex;
align-items: center;
justify-content: space-between;
gap: 10px;
}
.sidebar-logo .logo-sub {
margin-top: 7px;
}
.sidebar-toggle {
width: 30px;
height: 30px;
border: 1px solid var(--border, #252538);
border-radius: 7px;
background: var(--bg-card, #1a1a2b);
color: var(--text, #e2e2f0);
font-size: 15px;
line-height: 1;
cursor: pointer;
flex-shrink: 0;
}
body.sidebar-collapsed .sidebar .logo-text,
body.sidebar-collapsed .sidebar .search-wrap,
body.sidebar-collapsed .sidebar .nav-section,
body.sidebar-collapsed .sidebar .sidebar-footer {
display: none;
}
body.sidebar-collapsed .sidebar .sidebar-header {
padding: 12px 8px;
}
body.sidebar-collapsed .sidebar .sidebar-logo {
justify-content: center;
margin-bottom: 0;
}
body.sidebar-collapsed .sidebar .sidebar-topbar {
flex-direction: column;
align-items: center;
gap: 8px;
}
body.sidebar-collapsed .sidebar .sidebar-nav {
padding-top: 8px;
}
body.sidebar-collapsed .sidebar .nav-link {
justify-content: center;
gap: 0;
padding-left: 0;
padding-right: 0;
font-size: 0;
}
body.sidebar-collapsed .sidebar .nav-link .nav-icon {
width: auto;
font-size: 13px;
}
.sidebar-scrim {
position: fixed;
inset: 0;
background: rgba(0, 0, 0, 0.35);
opacity: 0;
pointer-events: none;
transition: opacity 0.18s ease;
z-index: 180;
}
.wiki-footer.footer-enhanced {
margin-top: 84px;
padding: 24px;
border: 1px solid var(--border, #252538);
border-radius: 14px;
background: linear-gradient(135deg, rgba(99, 102, 241, 0.08), rgba(16, 185, 129, 0.06));
display: grid;
grid-template-columns: 1.6fr 1fr 1fr;
gap: 22px;
align-items: start;
}
.footer-brand-name {
font-size: 16px;
font-weight: 700;
color: var(--text, #e2e2f0);
margin-bottom: 6px;
}
.footer-note {
font-size: 13px;
color: var(--text-muted, #8888aa);
margin-bottom: 12px;
line-height: 1.55;
}
.footer-badges {
display: flex;
flex-wrap: wrap;
gap: 8px;
}
.footer-badge {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 4px 9px;
border-radius: 999px;
font-size: 11px;
color: var(--text-muted, #8888aa);
border: 1px solid var(--border, #252538);
background: rgba(18, 18, 30, 0.75);
}
.footer-col-title {
font-size: 11px;
letter-spacing: 0.08em;
text-transform: uppercase;
color: var(--text-dim, #55556a);
margin-bottom: 10px;
font-weight: 700;
}
.footer-col-links {
display: flex;
flex-direction: column;
gap: 8px;
}
.footer-col-links a {
color: var(--text-muted, #8888aa);
text-decoration: none;
font-size: 13px;
overflow-wrap: anywhere;
}
.footer-col-links a:hover {
color: var(--text, #e2e2f0);
}
@media (max-width: 1400px) {
.sidebar {
display: flex !important;
z-index: 200;
}
.main-content {
display: block;
padding: 32px 16px;
margin-left: var(--sidebar-collapsed) !important;
width: calc(100vw - var(--sidebar-collapsed)) !important;
max-width: calc(100vw - var(--sidebar-collapsed)) !important;
}
.diagram-wrap .mermaid svg {
width: 100%;
max-width: 100%;
}
body:not(.sidebar-collapsed) .sidebar {
width: min(86vw, 320px);
box-shadow: 10px 0 28px rgba(0, 0, 0, 0.4);
}
body:not(.sidebar-collapsed) .sidebar-scrim {
opacity: 1;
pointer-events: auto;
}
.wiki-footer.footer-enhanced {
grid-template-columns: 1fr;
gap: 16px;
padding: 20px;
}
}
</style>
<!-- Mermaid -->
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
</head>
<body>
<div class="wiki-layout">
<div id="sidebar-scrim" class="sidebar-scrim" aria-hidden="true"></div>
<!-- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SIDEBAR ━━━ -->
<nav id="wiki-sidebar" class="sidebar" aria-label="Wiki navigation">
<div class="sidebar-header">
<div class="sidebar-topbar">
<a href="#hero" class="sidebar-logo">
<div class="logo-icon">⬡</div>
<div class="logo-text">
Claude Code Agent Monitor
<span class="logo-sub">Project Wiki</span>
</div>
</a>
<button
id="sidebar-toggle"
class="sidebar-toggle"
type="button"
aria-label="Toggle sidebar"
aria-controls="wiki-sidebar"
aria-expanded="true"
>
‹
</button>
</div>
</div>
<div class="search-wrap">
<input
id="sidebar-search"
class="search-input"
type="text"
placeholder="Search docs…"
autocomplete="off"
/>
</div>
<div class="sidebar-nav">
<div class="nav-section">Getting Started</div>
<a href="#overview" class="nav-link"><span class="nav-icon">◈</span>Overview</a>
<a href="#features" class="nav-link"><span class="nav-icon">◈</span>Features</a>
<a href="#quickstart" class="nav-link"><span class="nav-icon">◈</span>Quick Start</a>
<a href="#configuration" class="nav-link"><span class="nav-icon">◈</span>Configuration</a>
<a href="#scripts" class="nav-link"><span class="nav-icon">◈</span>Scripts Reference</a>
<div class="nav-section">Architecture</div>
<a href="#arch-overview" class="nav-link"
><span class="nav-icon">◈</span>System Overview</a
>
<a href="#data-flow" class="nav-link"><span class="nav-icon">◈</span>Data Flow</a>
<a href="#server-arch" class="nav-link"
><span class="nav-icon">◈</span>Server Architecture</a
>
<a href="#client-arch" class="nav-link"
><span class="nav-icon">◈</span>Client Architecture</a
>
<a href="#state-mgmt" class="nav-link"><span class="nav-icon">◈</span>State Management</a>
<div class="nav-section">Data & APIs</div>
<a href="#database-design" class="nav-link"><span class="nav-icon">◈</span>Database Design</a>
<a href="#api-reference" class="nav-link"><span class="nav-icon">◈</span>API Reference</a>
<a href="#websocket" class="nav-link"
><span class="nav-icon">◈</span>WebSocket Protocol</a
>
<div class="nav-section">Integrations</div>
<a href="#hooks" class="nav-link"><span class="nav-icon">◈</span>Hook Integration</a>
<a href="#mcp-agent-extensions" class="nav-link"
><span class="nav-icon">◈</span>MCP & Agent Extensions</a
>
<a href="#plugin-marketplace" class="nav-link"
><span class="nav-icon">◈</span>Plugin Marketplace</a
>
<a href="#statusline" class="nav-link"
><span class="nav-icon">◈</span>Statusline Utility</a
>
<a href="#settings-page" class="nav-link"><span class="nav-icon">◈</span>Settings Page</a>
<div class="nav-section">Ops & Reference</div>
<a href="#deployment" class="nav-link"><span class="nav-icon">◈</span>Deployment Modes</a>
<a href="#docker" class="nav-link"><span class="nav-icon">◈</span>Docker / Podman</a>
<a href="#performance" class="nav-link"><span class="nav-icon">◈</span>Performance</a>
<a href="#security" class="nav-link"><span class="nav-icon">◈</span>Security</a>
<a href="#troubleshoot" class="nav-link"
><span class="nav-icon">◈</span>Troubleshooting</a
>
<a href="#tech-choices" class="nav-link"><span class="nav-icon">◈</span>Tech Choices</a>
</div>
<div class="sidebar-footer">
<div class="sidebar-links">
<a href="https://github.com/hoangsonww" target="_blank" rel="noopener">
<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor">
<path
d="M12 2C6.477 2 2 6.477 2 12c0 4.42 2.865 8.166 6.839 9.489.5.092.682-.217.682-.482 0-.237-.008-.866-.013-1.7-2.782.603-3.369-1.342-3.369-1.342-.454-1.155-1.11-1.462-1.11-1.462-.908-.62.069-.608.069-.608 1.003.07 1.531 1.03 1.531 1.03.892 1.529 2.341 1.087 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.11-4.555-4.943 0-1.091.39-1.984 1.029-2.683-.103-.253-.446-1.27.098-2.647 0 0 .84-.269 2.75 1.025A9.578 9.578 0 0112 6.836c.85.004 1.705.114 2.504.336 1.909-1.294 2.747-1.025 2.747-1.025.546 1.377.202 2.394.1 2.647.64.699 1.028 1.592 1.028 2.683 0 3.842-2.339 4.687-4.566 4.935.359.309.678.919.678 1.852 0 1.336-.012 2.415-.012 2.741 0 .267.18.578.688.48C19.138 20.163 22 16.418 22 12c0-5.523-4.477-10-10-10z"
/>
</svg>
hoangsonww
</a>
<a href="https://sonnguyenhoang.com" target="_blank" rel="noopener">
<svg
width="14"
height="14"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
>
<circle cx="12" cy="12" r="10" />
<line x1="2" y1="12" x2="22" y2="12" />
<path
d="M12 2a15.3 15.3 0 014 10 15.3 15.3 0 01-4 10 15.3 15.3 0 01-4-10 15.3 15.3 0 014-10z"
/>
</svg>
sonnguyenhoang.com
</a>
<a href="README.md" target="_blank" rel="noopener">
<svg
width="14"
height="14"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
>
<path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z" />
<polyline points="14 2 14 8 20 8" />
<line x1="16" y1="13" x2="8" y2="13" />
<line x1="16" y1="17" x2="8" y2="17" />
<polyline points="10 9 9 9 8 9" />
</svg>
README
</a>
</div>
</div>
</nav>
<!-- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ MAIN CONTENT ━━━ -->
<main class="main-content">
<!-- ─── Hero ─────────────────────────────────────────────────────── -->
<div id="hero" class="hero">
<div class="hero-badge">
<span class="dot"></span>
Real-time · Local-first · Zero-config
</div>
<h1 style="padding-bottom: 2px">Claude Code Agent Monitor</h1>
<p class="hero-desc">
A professional monitoring platform for Claude Code agent activity. Captures sessions,
agents, and tool events via native hooks, persists them in SQLite, and streams updates
to a React UI over WebSocket — with no external services required.
</p>
<div class="marquee-wrapper">
<div class="marquee-track">
<div class="marquee-content">
<span class="tech-badge badge-node">Node.js ≥ 18</span>
<span class="tech-badge badge-react">React 18.3</span>
<span class="tech-badge badge-ts">TypeScript Strict</span>
<span class="tech-badge badge-sqlite">SQLite WAL</span>
<span class="tech-badge badge-ws">WebSocket</span>
<span class="tech-badge badge-vite">Vite 6</span>
<span class="tech-badge badge-express">Express</span>
<span class="tech-badge badge-d3">D3.js</span>
<span class="tech-badge badge-tailwind">Tailwind CSS</span>
<span class="tech-badge badge-router">React Router</span>
<span class="tech-badge badge-zod">Zod</span>
<span class="tech-badge badge-vitest">Vitest</span>
<span class="tech-badge badge-mcp">MCP SDK</span>
<span class="tech-badge badge-docker">Docker</span>
<span class="tech-badge badge-node">Local MCP Server</span>
<span class="tech-badge badge-react">Claude + Codex Extensions</span>
<span class="tech-badge badge-python">Python 3.6+</span>
<span class="tech-badge badge-lucide">Lucide Icons</span>
<span class="tech-badge badge-postcss">PostCSS</span>
<span class="tech-badge badge-esbuild">esbuild</span>
<span class="tech-badge badge-mit">MIT License</span>
</div>
<div class="marquee-content" aria-hidden="true">
<span class="tech-badge badge-node">Node.js ≥ 18</span>
<span class="tech-badge badge-react">React 18.3</span>
<span class="tech-badge badge-ts">TypeScript Strict</span>
<span class="tech-badge badge-sqlite">SQLite WAL</span>
<span class="tech-badge badge-ws">WebSocket</span>
<span class="tech-badge badge-vite">Vite 6</span>
<span class="tech-badge badge-express">Express</span>
<span class="tech-badge badge-d3">D3.js</span>
<span class="tech-badge badge-tailwind">Tailwind CSS</span>
<span class="tech-badge badge-router">React Router</span>
<span class="tech-badge badge-zod">Zod</span>
<span class="tech-badge badge-vitest">Vitest</span>
<span class="tech-badge badge-mcp">MCP SDK</span>
<span class="tech-badge badge-docker">Docker</span>
<span class="tech-badge badge-node">Local MCP Server</span>
<span class="tech-badge badge-react">Claude + Codex Extensions</span>
<span class="tech-badge badge-python">Python 3.6+</span>
<span class="tech-badge badge-lucide">Lucide Icons</span>
<span class="tech-badge badge-postcss">PostCSS</span>
<span class="tech-badge badge-esbuild">esbuild</span>
<span class="tech-badge badge-mit">MIT License</span>
</div>
</div>
</div>
</div>
<!-- ─── Overview ──────────────────────────────────────────────────── -->
<section id="overview">
<div class="section-label">◈ Introduction</div>
<h2>System Overview</h2>
<div class="screenshot-gallery gallery-single">
<div class="screenshot-card">
<img src="images/analytics.png" alt="Claude Code Agent Monitor dashboard showing live agent cards, stats, and recent activity feed" loading="lazy" />
<div class="screenshot-caption"><span class="caption-icon">📡</span> Live dashboard — real-time agent cards, stats, and activity feed</div>
</div>
</div>
<p>
Claude Code Agent Monitor integrates with Claude Code through its native hook system. When Claude
Code performs any action — tool use, session start, subagent orchestration, session end
— it fires a hook that calls a small Node.js script bundled with this project. That
script forwards the event over HTTP to the dashboard server, which stores it in SQLite
and broadcasts it to the browser over WebSocket.
</p>
<div class="diagram-wrap">
<!-- prettier-ignore -->
<div class="mermaid">
graph LR
CC["Claude Code\nSession"]:::cc -->|"hooks fire on\ntool use / stop"| HH["hook-handler.js\n(stdin → HTTP)"]:::mid
HH -->|"HTTP POST\n/api/hooks/event"| SRV["Express Server\n+ SQLite"]:::mid
SRV -->|"WebSocket\nbroadcast"| UI["React Dashboard\n(browser)"]:::ui
classDef cc fill:#6366f1,stroke:#818cf8,color:#fff
classDef mid fill:#1a1a2b,stroke:#2e2e48,color:#e2e2f0
classDef ui fill:#10b981,stroke:#34d399,color:#fff
</div>
<p class="diagram-label">End-to-end data pipeline from Claude Code to the browser</p>
</div>
<div class="stats-row">
<div class="stat-highlight">
<div class="stat-val">< 50ms</div>
<div class="stat-label">Hook latency</div>
</div>
<div class="stat-highlight">
<div class="stat-val">7</div>
<div class="stat-label">Hook types captured</div>
</div>
<div class="stat-highlight">
<div class="stat-val">~30 MB</div>
<div class="stat-label">Server memory</div>
</div>
<div class="stat-highlight">
<div class="stat-val">1 M+</div>
<div class="stat-label">Events before slowdown</div>
</div>
</div>
<div class="callout callout-info">
<div class="callout-icon">ℹ</div>
<div class="callout-body">
<strong>Local-first by design</strong>
<p>
The server binds to <code>0.0.0.0</code> but everything runs on your machine. No
data leaves your system. No API keys. No external services.
</p>
</div>
</div>
</section>
<!-- ─── Features ──────────────────────────────────────────────────── -->
<section id="features">
<div class="section-label">◈ Features</div>
<h2>What's Included</h2>
<p>
Every feature is driven by real hook events — nothing is hardcoded or simulated in
production mode.
</p>
<div class="carousel" id="feature-carousel">
<div class="carousel-viewport">
<div class="carousel-track">
<div class="feature-card">
<div class="feature-icon ic-indigo">📡</div>
<h3>Live Dashboard</h3>
<p>
Overview stats, active agent cards with collapsible subagent hierarchy, and recent
activity feed — all updating in real-time via WebSocket.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-emerald">📋</div>
<h3>Kanban Board</h3>
<p>
5-column agent status board (Idle / Connected / Working / Completed / Error) with
paginated columns (10 per page) and horizontal scroll on overflow.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-amber">📂</div>
<h3>Sessions Table</h3>
<p>
Searchable, filterable, paginated table of all sessions with color-coded status
badges, agent counts, duration, and model info. Filter by active, completed,
error, or abandoned status. Click any row to drill into the full session detail.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-violet">🔬</div>
<h3>Session Detail</h3>
<p>
Per-session agent hierarchy tree (parent/child with expand/collapse) and full
chronological event timeline with tool names and summaries.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-pink">📰</div>
<h3>Activity Feed</h3>
<p>
Real-time streaming event log showing tool calls, agent state changes, errors,
and compaction events as they happen. Pause/resume with buffering, paginated
history, and automatic scrolling. Each entry is color-coded by event type.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-cyan">📊</div>
<h3>Analytics</h3>
<p>
Token usage breakdown by model, tool frequency bar charts, agent type distribution,
52-week activity heatmap (day-of-week aligned with tooltips), 30-day sparkline
trends, session outcome donut charts, and cost summary. Live/offline indicator
with auto-refresh.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-blue">⚡</div>
<h3>WebSocket Push</h3>
<p>
All UI updates are pushed over WebSocket with sub-5ms latency — no polling.
Automatic 2-second reconnection on disconnect, heartbeat ping/pong for
dead-connection detection, and a visual connection indicator in the sidebar
so you always know when you're live.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-rose">🖥️</div>
<h3>Statusline</h3>
<p>
Standalone CLI statusline for Claude Code showing model name, user, working
directory, git branch, a color-coded context window usage bar (green/yellow/red),
and token counts. ANSI-colored output that updates on every turn. Python-based
with a shell wrapper for easy integration.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-emerald">🔄</div>
<h3>History Import</h3>
<p>
Automatically imports sessions from <code>~/.claude/</code> on startup with
correct timestamps. Deep JSONL extraction captures API errors, per-turn
durations, thinking blocks, usage extras, and parses subagent JSONL files for
per-subagent model, token, and tool breakdowns. Recently-modified sessions
are imported as active so the dashboard reflects real state immediately.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-cyan">💾</div>
<h3>Transcript Cache</h3>
<p>
Stat-based incremental JSONL reader shared across hook handler and compaction
scanner. Avoids duplicate I/O with byte-offset reads, bounds memory via LRU
eviction, and detects API errors, turn durations, thinking blocks, and usage
extras from live transcripts in real-time as sessions progress.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-violet">🌳</div>
<h3>Subagent Hierarchy</h3>
<p>
Collapsible parent-child agent tree on Dashboard and Session Detail. Agents with
subagents show expand/collapse chevrons; leaf agents show a dot indicator.
Auto-expands when subagents are active. Correctly tracks backgrounded subagents
without premature completion.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-amber">💰</div>
<h3>Cost Tracking</h3>
<p>
Per-model cost estimation with configurable pricing rules. View total and per-session
cost breakdowns based on input, output, and cache token rates. Compaction-aware token
accounting preserves totals across context compressions so no usage is ever lost.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-indigo">⚙️</div>
<h3>Settings & Management</h3>
<p>
Model pricing editor with per-token rate configuration, hook installation status
and one-click reinstall, full JSON data export, session cleanup controls (abandon
stale sessions, purge old data by age), browser notification preferences with
per-event toggles, and a system information dashboard showing DB stats and
server health.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-blue">🔌</div>
<h3>Local MCP Server</h3>
<p>
Local MCP sidecar with three transport modes (stdio, HTTP+SSE, interactive REPL),
25 typed tools across 6 domains, retry-aware API access, and tiered policy gates
for mutation and destructive operations.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-rose">🧩</div>
<h3>Claude + Codex Extensions</h3>
<p>
Comprehensive instruction, skills, rules, and custom-agent layers for both Claude
Code and Codex. Includes path-scoped rules for backend, frontend, MCP, and docs,
reusable skills for onboarding, feature shipping, debugging, and MCP operations,
plus specialized subagents for backend, frontend, and MCP code review.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-teal">🔀</div>
<h3>Workflow Graphs</h3>
<p>
D3.js-powered agent orchestration DAG showing spawn patterns across sessions,
tool execution Sankey diagram mapping tool-to-tool transitions, and a directed
agent pipeline graph revealing which agent types run after which with frequency labels.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-indigo">📊</div>
<h3>Workflow Analytics</h3>
<p>
Subagent effectiveness scorecards with success rings and day-of-week activity
charts. Auto-detected workflow patterns, model delegation flow, error propagation
with horizontal bars and API error cards, concurrency swim-lanes, and complexity
bubble charts. Status filter (Active/Completed/All) filters all sections.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-cyan">🔍</div>
<h3>Session Drill-In</h3>
<p>
Searchable session selector with pagination to explore any session's agent tree,
tool call timeline, and event sequence. Cross-filtering from DAG nodes, compaction
impact analysis, JSON export, and real-time WebSocket auto-refresh.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-pink">🔔</div>
<h3>Browser Notifications</h3>
<p>
Native browser notifications for session starts, completions, errors, and subagent
spawns — even when the dashboard tab is in the background. Per-event toggles in
Settings let you choose exactly which events trigger alerts, with automatic
permission management and graceful fallback.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-teal">🐳</div>
<h3>Docker Deployment</h3>
<p>
Ready-to-use Dockerfile and docker-compose.yml for one-command deployment.
Supports both Docker and Podman with persistent volume mounts, automatic
rebuilds, and configurable port mapping. Run
<code>docker compose up -d --build</code> and you're live.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-violet">🏪</div>
<h3>Plugin Marketplace</h3>
<p>
Official Claude Code plugin marketplace with 5 plugins (18 skills, 4 agents, 3 CLI
tools). Deep analytics with compaction baselines, productivity automation, developer
diagnostics, AI-powered insights via workflow intelligence, and dashboard MCP
integration. Install with <code>claude plugin install</code>.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-emerald">📱</div>
<h3>Responsive Design</h3>
<p>
Mobile-first layouts with stacking grids, scrollable tables, and a collapsible
sidebar that auto-hides below 1400px. All seven pages adapt seamlessly from phone
to ultrawide with consistent navigation, readable typography, and full touch support.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-sky">🌊</div>
<h3>Concurrency Timeline</h3>
<p>
Visualize parallel agent execution with a Gantt-style timeline showing overlapping
subagent lifetimes, tool call concurrency, and idle gaps. Identify bottlenecks in
multi-agent orchestration and optimize task parallelism across complex sessions.
</p>
</div>
<div class="feature-card">
<div class="feature-icon ic-rose">🛡️</div>
<h3>Error Propagation Map</h3>
<p>
Trace how errors cascade across agents and tool calls with a directed graph showing
failure origins, retry paths, and recovery points. Pinpoint root causes in deep
subagent chains and understand which tool failures trigger upstream session aborts.
</p>
</div>
</div>
</div>
<div class="carousel-controls">
<button class="carousel-btn carousel-prev" aria-label="Previous features">‹</button>
<div class="carousel-dots" id="carousel-dots"></div>
<button class="carousel-btn carousel-next" aria-label="Next features">›</button>
</div>
</div>
<h3>Screenshots</h3>
<div class="screenshot-gallery">
<div class="screenshot-card">
<img src="images/sessions.png" alt="Sessions table with search, filters, status badges, and pagination" loading="lazy" />
<div class="screenshot-caption"><span class="caption-icon">📋</span> Sessions table — searchable, filterable, paginated</div>
</div>
<div class="screenshot-card">
<img src="images/session.png" alt="Session detail view with agent hierarchy tree and event timeline" loading="lazy" />
<div class="screenshot-caption"><span class="caption-icon">🔬</span> Session detail — agent tree and event timeline</div>
</div>
<div class="screenshot-card">
<img src="images/board.png" alt="Kanban board showing agents in Idle, Connected, Working, Completed, and Error columns" loading="lazy" />
<div class="screenshot-caption"><span class="caption-icon">📂</span> Kanban board — 5-column agent status view</div>
</div>
<div class="screenshot-card">
<img src="images/feed.png" alt="Real-time activity feed with streaming events and pause/resume controls" loading="lazy" />
<div class="screenshot-caption"><span class="caption-icon">📰</span> Activity feed — real-time streaming event log</div>
</div>
<div class="screenshot-card">
<img src="images/analytics.png" alt="Analytics dashboard with token usage charts, tool frequency, and session trends" loading="lazy" />
<div class="screenshot-caption"><span class="caption-icon">📊</span> Analytics — token usage, tool frequency, and trends</div>
</div>
<div class="screenshot-card">
<img src="images/workflows.png" alt="Workflow graphs showing agent orchestration DAGs and tool execution Sankey diagrams" loading="lazy" />
<div class="screenshot-caption"><span class="caption-icon">🔀</span> Workflows — agent DAGs and tool Sankey diagrams</div>
</div>
</div>
<h3>Hook Events Captured</h3>
<div class="table-wrap">
<table>
<thead>
<tr>
<th>Hook Type</th>
<th>Trigger</th>
<th>Dashboard Action</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>SessionStart</code></td>
<td>Claude Code session begins</td>
<td>
Creates session and main agent. Reactivates resumed sessions. Abandons orphaned sessions with no activity for 5+ minutes.
</td>
</tr>
<tr>
<td><code>PreToolUse</code></td>
<td>Agent begins using a tool</td>
<td>
Agent →
<span class="status-chip chip-working"
><span class="chip-dot"></span>Working</span
>, <code>current_tool</code> set. If tool is <code>Agent</code>, subagent record
created.
</td>
</tr>
<tr>
<td><code>PostToolUse</code></td>
<td>Tool execution completes</td>
<td>
<code>current_tool</code> cleared. Agent stays
<span class="status-chip chip-working"
><span class="chip-dot"></span>Working</span
> (no status change).
</td>
</tr>
<tr>
<td><code>Stop</code></td>
<td>Session/turn ended</td>
<td>
Main agent →
<span class="status-chip chip-idle"
><span class="chip-dot"></span>Idle</span
> if subagents still running, else
<span class="status-chip chip-completed"
><span class="chip-dot"></span>Completed</span
>. Running subagents are preserved. Token usage recorded.
</td>
</tr>
<tr>
<td><code>SubagentStop</code></td>
<td>Background agent finished</td>
<td>
Matched subagent →
<span class="status-chip chip-completed"
><span class="chip-dot"></span>Completed</span
>. Auto-completes session when the last subagent finishes.
</td>
</tr>
<tr>
<td><code>Notification</code></td>
<td>Agent sends notification</td>
<td>Event logged to activity feed. Compaction-related notifications tagged as <code>Compaction</code> events.</td>
</tr>
<tr>
<td><code>Compaction</code></td>
<td><code>/compact</code> detected in JSONL</td>
<td>
Creates a compaction subagent →
<span class="status-chip chip-completed"
><span class="chip-dot"></span>Completed</span
>. Detected via <code>isCompactSummary</code> entries in the transcript. Token baselines preserve pre-compaction totals. Periodic scanner (every 2 min) catches compactions when no hooks fire.
</td>
</tr>
<tr>
<td><code>APIError</code></td>
<td>API error detected in transcript</td>
<td>
Extracted from JSONL during history import or real-time transcript scanning.
Captures quota limits, rate limits, and other API failures.
</td>
</tr>
<tr>
<td><code>TurnDuration</code></td>
<td>Per-turn timing recorded</td>
<td>
Extracted from JSONL turn boundaries. Records the duration of each
assistant turn for latency analysis.
</td>
</tr>
<tr>
<td><code>SessionEnd</code></td>
<td>Claude Code CLI process exits</td>
<td>
Marks all agents and the session as
<span class="status-chip chip-completed"
><span class="chip-dot"></span>Completed</span
>.
</td>
</tr>
</tbody>
</table>
</div>
</section>
<!-- ─── Quick Start ───────────────────────────────────────────────── -->
<section id="quickstart">
<div class="section-label">◈ Getting Started</div>
<h2>Quick Start</h2>
<div class="quick-start-grid">
<div class="qs-card">
<div class="qs-step">1</div>
<h3>Clone</h3>
<p>Clone the repository to your machine</p>
</div>
<div class="qs-card">
<div class="qs-step">2</div>
<h3>Install</h3>
<p>Run <code>npm run setup</code> to install all dependencies</p>
</div>
<div class="qs-card">
<div class="qs-step">3</div>
<h3>Start</h3>
<p>Run <code>npm run dev</code> — server + client launch automatically</p>
</div>
<div class="qs-card">
<div class="qs-step">4</div>
<h3>Use Claude</h3>
<p>Start a new Claude Code session — events appear in real-time</p>
</div>
</div>
<div class="code-header"><span class="code-lang">bash</span></div>
<pre><code># 1. Clone
git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
cd Claude-Code-Agent-Monitor
# 2. Install all dependencies (server + client)
npm run setup