| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 36 | 11 | 0% |
| Commands | 6 | 1 | 7 | 43% |
| Section tags | 6 | 9 | 1 | 38% |
What each file covers
Sections
0 shared · 36 only in A · 11 only in B- − CLAUDE.md
- − Project Overview
- − Architecture & Entry Points
- − Critical Components
- − Database Schema Strategy
- − Build & Development Workflow
- − Essential Commands
- − Development Mode for UI Work
- − UI Testing with Playwright
- − Start development server in background
- − Use Task tool with browser automation to test UI changes
- − The agent can:
- − - Navigate to localhost:8080
- − - Take screenshots of UI components
- − - Test hover interactions on heatmap cells
- − - Verify responsive layout behavior
- − - Test different time range selections
- − - Validate tooltips and interactive elements
- − Pre-commit Requirements
- − Project-Specific Conventions
- − Error Handling Pattern
- − Configuration Philosophy
- − Ping Implementation Detail
- − Web Interface Integration
- − API Patterns
- − Static Assets
- − Testing & CI/CD
- − Test Strategy
- − Docker Deployment
- − Integration Points
- − llm-shared Submodule
- − External Dependencies
- − ISP Documentation Workflow
- − Data Collection Strategy
- − Report Generation
- − Development Notes
- + Agent Handbook
- + Project Structure & Core Modules
- + Build, Test, and Runtime Commands
- + Git & Workflow Norms
- + Coding Style & Language Guidance
- + Testing Expectations
- + Commit & PR Conventions
- + LLM Shared Resources
- + Shared Utilities & Templates
- + Shell & Tooling Expectations
- + Operations & Configuration Notes
Commands
6 shared · 1 only in A · 7 only in B- − docker-compose.yml
- + task clean
- + go run . --dev
- + docker-compose up --build
- + docker-compose down
- + go test ./...
- + go.md
- + task report
- task build
- task dev
- task test
- task lint
- task build-linux
- task test-ci
Section tags
6 shared · 9 only in A · 1 only in B- − lint-format
- − types
- − testing-strategy
- − dependencies
- − database
- − api
- − ui
- − deployment
- − docs
- + do-not
- build
- test
- code-style
- architecture
- git-pr
- agent-behaviour
Line diff
lepinkainen/network-monitor · CLAUDE.md
@@ −1 @@
1# CLAUDE.md
2
3Network Connectivity Monitor - AI Agent Guidelines
4
5## Project Overview
6
7A Go-based network monitoring tool that performs continuous ping tests to detect ISP issues and connectivity patterns. Features intelligent data retention, pattern detection via heatmaps, and web-based visualization.
8
9**Key Purpose**: Long-term ISP issue documentation with compelling visual evidence.
10
11## Architecture & Entry Points
12
13- **Main Entry**: `main.go` - Orchestrates all components with graceful shutdown
14- **Internal Structure**: Clean separation via `internal/` packages
15- **Static Assets**: Embedded via `//go:embed static/*` in main.go (production) or filesystem serving (development)
16- **Database**: SQLite with WAL mode for concurrent access
17
18### Critical Components
19
20```plain
21internal/
22├── config/ - CLI flags and validation (config.go, flags.go)
23├── database/ - SQLite operations, schema, maintenance (db.go, queries.go)
24├── models/ - Data structures (ping.go, stats.go, types.go)
25├── monitor/ - Worker orchestration and lifecycle (monitor.go, worker.go)
26├── ping/ - Cross-platform ping implementation
27├── report/ - PNG chart generation using go-chart/v2
28└── web/ - HTTP server and REST API (handlers.go, server.go)
29```
30
31## Database Schema Strategy
32
33**Smart Retention Pattern**:
34
35- `ping_results`: Raw data (7-day retention)
36- `hourly_patterns`: Aggregated for heatmap (90-day retention)
37- `outages`: Detected failures (permanent)
38- `hourly_stats`: Statistical summaries
39
40**Key Insight**: Maintenance runs hourly via `internal/database/maintenance.go` - automatic data aggregation and cleanup.
41
42## Build & Development Workflow
43
44### Essential Commands
45
46```bash
47task build # Build after tests+lint (required for deployment)
48task dev # Development server with live static file editing
49task test # Run all tests
50task lint # goimports + vet + golangci-lint
51task build-linux # Cross-compile for Linux deployment
52```
53
54### Development Mode for UI Work
55
56**Live Static File Editing**: The `task dev` command now enables live editing of HTML, CSS, and JavaScript files without server restarts.
57
58```bash
59task dev # Runs: go run . --dev
60```
61
62**Development Mode Features**:
63
64- **Live HTML editing**: Changes to `static/index.html` visible on browser refresh
65- **Live CSS editing**: Modifications to `static/css/*.css` applied immediately
66- **Live JavaScript editing**: Updates to `static/js/*.js` served instantly from filesystem
67- **No server restart required**: Only browser refresh needed to see changes
68- **Production safety**: Build process unchanged, still uses embedded files
69
70**Development vs Production**:
71
72- **Development** (`--dev` flag): Serves files from `static/` directory (live editing)
73- **Production** (default): Uses embedded `//go:embed` files (compile-time)
74
75### UI Testing with Playwright
76
77**Automated UI Testing**: Use the general-purpose agent with Playwright browser automation for comprehensive UI testing.
78
79```bash
80# Start development server in background
81task dev
82
83# Use Task tool with browser automation to test UI changes
84# The agent can:
85# - Navigate to localhost:8080
86# - Take screenshots of UI components
87# - Test hover interactions on heatmap cells
88# - Verify responsive layout behavior
89# - Test different time range selections
90# - Validate tooltips and interactive elements
91```
92
93**UI Development Workflow**:
94
951. Start development server: `task dev`
962. Edit static files (HTML/CSS/JS) in your editor
973. Refresh browser to see changes immediately
984. Use Playwright agent to verify functionality
995. Take screenshots for documentation/validation
100
101### Pre-commit Requirements
102
103- **Always run**: `task build` before considering changes complete
104- **Format**: Uses `goimports -w .` (NOT gofmt) for imports management
105- **Linting**: golangci-lint with `.golangci.yml` config
106
107## Project-Specific Conventions
108
109### Error Handling Pattern
110
111```go
112// Preferred throughout codebase
113if errors.Is(err, database.ErrOutageExists) {
114 // handle specifically
115}
116```
117
118### Configuration Philosophy
119
120- CLI flags via `internal/config/flags.go`
121- Validation in separate `config.Validate()` method
122- Defaults optimized for home ISP monitoring
123
124### Ping Implementation Detail
125
126- Cross-platform: Windows/Mac/Linux support in `internal/ping/ping.go`
127- **Outage Detection**: 5+ failures in any 10 consecutive pings
128- Uses OS-native ping (not raw sockets) for reliability
129
130## Web Interface Integration
131
132### API Patterns
133
134- RESTful JSON endpoints in `internal/web/handlers.go`
135- Real-time data serving for D3.js frontend
136- **Key Route**: `/api/data` powers the heatmap visualization
137
138### Static Assets
139
140- Single `static/index.html` with embedded D3.js
141- **Production Pattern**: All static files embedded at compile time via `//go:embed`
142- **Development Pattern**: Files served directly from filesystem for live editing
143- No build step for frontend - vanilla HTML/JS/CSS
144- **Live Development**: Use `task dev` for immediate UI changes without server restart
145
146## Testing & CI/CD
147
148### Test Strategy
149
150- `*_test.go` files for critical functionality only
151- **CI Pattern**: Separate test/lint/build jobs in GitHub Actions
152- Uses `task test-ci` for coverage reporting
153
154### Docker Deployment
155
156- `Dockerfile` + `docker-compose.yml` for containerization
157- **Volume Pattern**: `./data:/app/data` for database persistence
158- Health checks via web interface availability
159
160## Integration Points
161
162### llm-shared Submodule
163
164- Development tools in `llm-shared/utils/`
165- **Key Tool**: `gofuncs.go` for function analysis
166- Project validation via `validate-docs.go`
167
168### External Dependencies
169
170- **Database**: `modernc.org/sqlite` (pure Go SQLite)
171- **Charts**: `github.com/wcharczuk/go-chart/v2` for PNG report generation
172- **Minimal Dependencies**: Prefers standard library
173
174## ISP Documentation Workflow
175
176### Data Collection Strategy
177
1781. **Hour 1**: Basic connectivity data
1792. **Day 1**: Initial pattern recognition
1803. **Week 1**: Clear time-of-day patterns
1814. **Month 1**: Compelling evidence for ISP discussions
182
183### Report Generation
184
185- PNG charts via `internal/report/` package
186- **Visual Evidence**: Heatmap screenshots after 1-2 weeks most effective
187- Export capability for CSV data analysis
188
189## Development Notes
190
191- **Deployment Target**: Single-user, private monitoring (not SaaS)
192- **Service Integration**: Includes launchd/systemd service examples in README
193- **Resource Efficient**: <1% CPU, 20-50MB RAM with default settings
194- **Cross-Platform**: Full macOS/Linux/Windows support with OS-specific deployment guides
195
lepinkainen/network-monitor · AGENTS.md
@@ +1 @@
1# Agent Handbook
2
3## Project Structure & Core Modules
4
5Source code centers on `main.go` with feature logic under `internal/`. Key packages: `internal/monitor` for worker orchestration, `internal/ping` for ICMP sampling, `internal/database` for SQLite, and `internal/web` for the dashboard. Static assets live in `static/`, build artefacts in `build/`, generated reports in `reports/`, and shared automation aids in `llm-shared/`.
6
7## Build, Test, and Runtime Commands
8
9Run `task build` before claiming work complete; it wraps linting, tests, and the build. Use `task build-linux` for cross-compiles, `task lint` to enforce formatting/vetting, `task clean` to reset `build/`, and `task dev` (or `go run . --dev`) for the live dashboard. For containers, prefer `docker-compose up --build` / `docker-compose down`.
10
11## Git & Workflow Norms
12
13- Never commit directly to `main`/`master`; develop on feature branches and keep commits focused.
14- Rebase before merge, rely on pull requests for review, and close the loop with linked tracking issues.
15- When working from checklists, tick items as you go and treat a task as complete only once `task build` passes and tests exist for the new logic.
16
17## Coding Style & Language Guidance
18
19Target Go 1.21 in this repo, but align with the broader Go practices in `llm-shared/languages/go.md`: prefer the latest stable Go toolchain (currently 1.24), use `goimports -w .` for formatting/imports, justify third-party deps, and lean on standard library packages. Keep packages lower_snake_case, exported identifiers in PascalCase, and split oversized files across focused modules.
20
21## Testing Expectations
22
23Collocate tests with code (e.g. `internal/ping/ping_test.go`). Run `task test` or `go test ./...` prior to push; CI mirrors this through `task test-ci`. Write table-driven tests with descriptive names like `TestWorkerHandlesTimeout`, and ensure even small changes land with basic coverage.
24
25## Commit & PR Conventions
26
27Use Conventional Commits (`feat:`, `fix:`, `refactor:`). Summarise monitoring/UI impact in PRs, attach screenshots or CLI output when user-facing, and audit docs whenever touching pieces like `Taskfile.yml` or `static/`.
28
29## LLM Shared Resources
30
31- `llm-shared/README.md` points to shared playbooks. Review it at the start of an engagement.
32- `llm-shared/project_tech_stack.md` covers repository hygiene: branch policy, Gemini CLI usage for large-code analysis, and the `validate-docs` workflow.
33- `llm-shared/GITHUB.md` documents `gh` CLI flows for managing issues/labels; bootstrap recommended labels with `./llm-shared/create-gh-labels.sh`.
34- `llm-shared/shell_commands.md` standardises shell tooling (`rg`, `fd`, etc.).
35- Language primers in `llm-shared/languages/` hold deeper Go/Python/JavaScript notes; consult `go.md` for dependency policy, lint setup, and CI expectations.
36
37## Shared Utilities & Templates
38
39Automation helpers live under `llm-shared/utils/`: the Go/Python/JS function listers (`gofuncs`, `pyfuncs`, `jsfuncs`) aid rapid code discovery, while `validate-docs` checks repo structure. Template assets in `llm-shared/templates/` supply starter configs for Taskfiles, CI workflows, changelogs, and language-aware `.gitignore` variants.
40
41## Shell & Tooling Expectations
42
43Prefer the modern command set: `rg` over `grep`, `fd` over `find`, and embrace context-friendly flags (see `llm-shared/shell_commands.md`). Respect `.gitignore` defaults, use glob filters, and rely on these tools for fast code searches and batch operations.
44
45## Operations & Configuration Notes
46
47Runtime configuration comes from CLI flags and files in `config/`. SQLite state lives in `network_monitor.db`; keep database files out of commits. Before `task report`, ensure `build/network-monitor` exists. Coordinate schema or retention updates with reporting charts so exported PNGs stay accurate. Any running web service must expose `/whoami` with project metadata, and existing processes should be identified via that endpoint before restarting or terminating them.
48
@@ −1 +1 @@
1−# CLAUDE.md
1+# Agent Handbook
22
3−Network Connectivity Monitor - AI Agent Guidelines
3+## Project Structure & Core Modules
44
5−## Project Overview
5+Source code centers on `main.go` with feature logic under `internal/`. Key packages: `internal/monitor` for worker orchestration, `internal/ping` for ICMP sampling, `internal/database` for SQLite, and `internal/web` for the dashboard. Static assets live in `static/`, build artefacts in `build/`, generated reports in `reports/`, and shared automation aids in `llm-shared/`.
66
7−A Go-based network monitoring tool that performs continuous ping tests to detect ISP issues and connectivity patterns. Features intelligent data retention, pattern detection via heatmaps, and web-based visualization.
7+## Build, Test, and Runtime Commands
88
9−**Key Purpose**: Long-term ISP issue documentation with compelling visual evidence.
9+Run `task build` before claiming work complete; it wraps linting, tests, and the build. Use `task build-linux` for cross-compiles, `task lint` to enforce formatting/vetting, `task clean` to reset `build/`, and `task dev` (or `go run . --dev`) for the live dashboard. For containers, prefer `docker-compose up --build` / `docker-compose down`.
1010
11−## Architecture & Entry Points
11+## Git & Workflow Norms
1212
13−- **Main Entry**: `main.go` - Orchestrates all components with graceful shutdown
14−- **Internal Structure**: Clean separation via `internal/` packages
15−- **Static Assets**: Embedded via `//go:embed static/*` in main.go (production) or filesystem serving (development)
16−- **Database**: SQLite with WAL mode for concurrent access
13+- Never commit directly to `main`/`master`; develop on feature branches and keep commits focused.
14+- Rebase before merge, rely on pull requests for review, and close the loop with linked tracking issues.
15+- When working from checklists, tick items as you go and treat a task as complete only once `task build` passes and tests exist for the new logic.
1716
18−### Critical Components
17+## Coding Style & Language Guidance
1918
20−```plain
21−internal/
22−├── config/ - CLI flags and validation (config.go, flags.go)
23−├── database/ - SQLite operations, schema, maintenance (db.go, queries.go)
24−├── models/ - Data structures (ping.go, stats.go, types.go)
25−├── monitor/ - Worker orchestration and lifecycle (monitor.go, worker.go)
26−├── ping/ - Cross-platform ping implementation
27−├── report/ - PNG chart generation using go-chart/v2
28−└── web/ - HTTP server and REST API (handlers.go, server.go)
29−```
19+Target Go 1.21 in this repo, but align with the broader Go practices in `llm-shared/languages/go.md`: prefer the latest stable Go toolchain (currently 1.24), use `goimports -w .` for formatting/imports, justify third-party deps, and lean on standard library packages. Keep packages lower_snake_case, exported identifiers in PascalCase, and split oversized files across focused modules.
3020
31−## Database Schema Strategy
21+## Testing Expectations
3222
33−**Smart Retention Pattern**:
23+Collocate tests with code (e.g. `internal/ping/ping_test.go`). Run `task test` or `go test ./...` prior to push; CI mirrors this through `task test-ci`. Write table-driven tests with descriptive names like `TestWorkerHandlesTimeout`, and ensure even small changes land with basic coverage.
3424
35−- `ping_results`: Raw data (7-day retention)
36−- `hourly_patterns`: Aggregated for heatmap (90-day retention)
37−- `outages`: Detected failures (permanent)
38−- `hourly_stats`: Statistical summaries
25+## Commit & PR Conventions
3926
40−**Key Insight**: Maintenance runs hourly via `internal/database/maintenance.go` - automatic data aggregation and cleanup.
27+Use Conventional Commits (`feat:`, `fix:`, `refactor:`). Summarise monitoring/UI impact in PRs, attach screenshots or CLI output when user-facing, and audit docs whenever touching pieces like `Taskfile.yml` or `static/`.
4128
42−## Build & Development Workflow
29+## LLM Shared Resources
4330
44−### Essential Commands
31+- `llm-shared/README.md` points to shared playbooks. Review it at the start of an engagement.
32+- `llm-shared/project_tech_stack.md` covers repository hygiene: branch policy, Gemini CLI usage for large-code analysis, and the `validate-docs` workflow.
33+- `llm-shared/GITHUB.md` documents `gh` CLI flows for managing issues/labels; bootstrap recommended labels with `./llm-shared/create-gh-labels.sh`.
34+- `llm-shared/shell_commands.md` standardises shell tooling (`rg`, `fd`, etc.).
35+- Language primers in `llm-shared/languages/` hold deeper Go/Python/JavaScript notes; consult `go.md` for dependency policy, lint setup, and CI expectations.
4536
46−```bash
47−task build # Build after tests+lint (required for deployment)
48−task dev # Development server with live static file editing
49−task test # Run all tests
50−task lint # goimports + vet + golangci-lint
51−task build-linux # Cross-compile for Linux deployment
52−```
37+## Shared Utilities & Templates
5338
54−### Development Mode for UI Work
39+Automation helpers live under `llm-shared/utils/`: the Go/Python/JS function listers (`gofuncs`, `pyfuncs`, `jsfuncs`) aid rapid code discovery, while `validate-docs` checks repo structure. Template assets in `llm-shared/templates/` supply starter configs for Taskfiles, CI workflows, changelogs, and language-aware `.gitignore` variants.
5540
56−**Live Static File Editing**: The `task dev` command now enables live editing of HTML, CSS, and JavaScript files without server restarts.
41+## Shell & Tooling Expectations
5742
58−```bash
59−task dev # Runs: go run . --dev
60−```
43+Prefer the modern command set: `rg` over `grep`, `fd` over `find`, and embrace context-friendly flags (see `llm-shared/shell_commands.md`). Respect `.gitignore` defaults, use glob filters, and rely on these tools for fast code searches and batch operations.
6144
62−**Development Mode Features**:
45+## Operations & Configuration Notes
6346
64−- **Live HTML editing**: Changes to `static/index.html` visible on browser refresh
65−- **Live CSS editing**: Modifications to `static/css/*.css` applied immediately
66−- **Live JavaScript editing**: Updates to `static/js/*.js` served instantly from filesystem
67−- **No server restart required**: Only browser refresh needed to see changes
68−- **Production safety**: Build process unchanged, still uses embedded files
69−
70−**Development vs Production**:
71−
72−- **Development** (`--dev` flag): Serves files from `static/` directory (live editing)
73−- **Production** (default): Uses embedded `//go:embed` files (compile-time)
74−
75−### UI Testing with Playwright
76−
77−**Automated UI Testing**: Use the general-purpose agent with Playwright browser automation for comprehensive UI testing.
78−
79−```bash
80−# Start development server in background
81−task dev
82−
83−# Use Task tool with browser automation to test UI changes
84−# The agent can:
85−# - Navigate to localhost:8080
86−# - Take screenshots of UI components
87−# - Test hover interactions on heatmap cells
88−# - Verify responsive layout behavior
89−# - Test different time range selections
90−# - Validate tooltips and interactive elements
91−```
92−
93−**UI Development Workflow**:
94−
95−1. Start development server: `task dev`
96−2. Edit static files (HTML/CSS/JS) in your editor
97−3. Refresh browser to see changes immediately
98−4. Use Playwright agent to verify functionality
99−5. Take screenshots for documentation/validation
100−
101−### Pre-commit Requirements
102−
103−- **Always run**: `task build` before considering changes complete
104−- **Format**: Uses `goimports -w .` (NOT gofmt) for imports management
105−- **Linting**: golangci-lint with `.golangci.yml` config
106−
107−## Project-Specific Conventions
108−
109−### Error Handling Pattern
110−
111−```go
112−// Preferred throughout codebase
113−if errors.Is(err, database.ErrOutageExists) {
114− // handle specifically
115−}
116−```
117−
118−### Configuration Philosophy
119−
120−- CLI flags via `internal/config/flags.go`
121−- Validation in separate `config.Validate()` method
122−- Defaults optimized for home ISP monitoring
123−
124−### Ping Implementation Detail
125−
126−- Cross-platform: Windows/Mac/Linux support in `internal/ping/ping.go`
127−- **Outage Detection**: 5+ failures in any 10 consecutive pings
128−- Uses OS-native ping (not raw sockets) for reliability
129−
130−## Web Interface Integration
131−
132−### API Patterns
133−
134−- RESTful JSON endpoints in `internal/web/handlers.go`
135−- Real-time data serving for D3.js frontend
136−- **Key Route**: `/api/data` powers the heatmap visualization
137−
138−### Static Assets
139−
140−- Single `static/index.html` with embedded D3.js
141−- **Production Pattern**: All static files embedded at compile time via `//go:embed`
142−- **Development Pattern**: Files served directly from filesystem for live editing
143−- No build step for frontend - vanilla HTML/JS/CSS
144−- **Live Development**: Use `task dev` for immediate UI changes without server restart
145−
146−## Testing & CI/CD
147−
148−### Test Strategy
149−
150−- `*_test.go` files for critical functionality only
151−- **CI Pattern**: Separate test/lint/build jobs in GitHub Actions
152−- Uses `task test-ci` for coverage reporting
153−
154−### Docker Deployment
155−
156−- `Dockerfile` + `docker-compose.yml` for containerization
157−- **Volume Pattern**: `./data:/app/data` for database persistence
158−- Health checks via web interface availability
159−
160−## Integration Points
161−
162−### llm-shared Submodule
163−
164−- Development tools in `llm-shared/utils/`
165−- **Key Tool**: `gofuncs.go` for function analysis
166−- Project validation via `validate-docs.go`
167−
168−### External Dependencies
169−
170−- **Database**: `modernc.org/sqlite` (pure Go SQLite)
171−- **Charts**: `github.com/wcharczuk/go-chart/v2` for PNG report generation
172−- **Minimal Dependencies**: Prefers standard library
173−
174−## ISP Documentation Workflow
175−
176−### Data Collection Strategy
177−
178−1. **Hour 1**: Basic connectivity data
179−2. **Day 1**: Initial pattern recognition
180−3. **Week 1**: Clear time-of-day patterns
181−4. **Month 1**: Compelling evidence for ISP discussions
182−
183−### Report Generation
184−
185−- PNG charts via `internal/report/` package
186−- **Visual Evidence**: Heatmap screenshots after 1-2 weeks most effective
187−- Export capability for CSV data analysis
188−
189−## Development Notes
190−
191−- **Deployment Target**: Single-user, private monitoring (not SaaS)
192−- **Service Integration**: Includes launchd/systemd service examples in README
193−- **Resource Efficient**: <1% CPU, 20-50MB RAM with default settings
194−- **Cross-Platform**: Full macOS/Linux/Windows support with OS-specific deployment guides
47+Runtime configuration comes from CLI flags and files in `config/`. SQLite state lives in `network_monitor.db`; keep database files out of commits. Before `task report`, ensure `build/network-monitor` exists. Coordinate schema or retention updates with reporting charts so exported PNGs stay accurate. Any running web service must expose `/whoami` with project metadata, and existing processes should be identified via that endpoint before restarting or terminating them.
19548
