Two files, one repository

lepinkainen/network-monitor ships 3 formats across 3 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareAGENTS.md ↔ CLAUDE.md AGENTS.md ↔ Cline rules CLAUDE.md ↔ Cline rules

A · AGENTS.md · 537 words B · CLAUDE.md · 869 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	11	36	0%
Commands	6	7	1	43%
Section tags	6	1	9	38%

What each file covers

Sections

0 shared · 11 only in A · 36 only in B

− 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
+ 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

Commands

6 shared · 7 only in A · 1 only in B

− task clean
− go run . --dev
− docker-compose up --build
− docker-compose down
− go test ./...
− go.md
− task report
+ docker-compose.yml
task build
task build-linux
task lint
task dev
task test
task test-ci

Section tags

6 shared · 1 only in A · 9 only in B

− do-not
+ lint-format
+ types
+ testing-strategy
+ dependencies
+ database
+ api
+ ui
+ deployment
+ docs
build
test
code-style
architecture
git-pr
agent-behaviour

Line diff

+174 added−27 removed21 unchanged10.8% identical

lepinkainen/network-monitor · AGENTS.md

@@ −1 @@

1# Agent Handbook

3## Project Structure & Core Modules

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/`.

7## Build, Test, and Runtime Commands

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`.

11## Git & Workflow Norms

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.

17## Coding Style & Language Guidance

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.

21## Testing Expectations

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.

25## Commit & PR Conventions

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/`.

29## LLM Shared Resources

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.

37## Shared Utilities & Templates

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.

41## Shell & Tooling Expectations

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.

45## Operations & Configuration Notes

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.

lepinkainen/network-monitor · CLAUDE.md

@@ +1 @@

1# CLAUDE.md

3Network Connectivity Monitor - AI Agent Guidelines

5## Project Overview

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.

9**Key Purpose**: Long-term ISP issue documentation with compelling visual evidence.

11## Architecture & Entry Points

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

18### Critical Components

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```

31## Database Schema Strategy

33**Smart Retention Pattern**:

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

40**Key Insight**: Maintenance runs hourly via `internal/database/maintenance.go` - automatic data aggregation and cleanup.

42## Build & Development Workflow

44### Essential Commands

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```

54### Development Mode for UI Work

56**Live Static File Editing**: The `task dev` command now enables live editing of HTML, CSS, and JavaScript files without server restarts.

58```bash

59task dev # Runs: go run . --dev

60```

62**Development Mode Features**:

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

70**Development vs Production**:

72- **Development** (`--dev` flag): Serves files from `static/` directory (live editing)

73- **Production** (default): Uses embedded `//go:embed` files (compile-time)

75### UI Testing with Playwright

77**Automated UI Testing**: Use the general-purpose agent with Playwright browser automation for comprehensive UI testing.

79```bash

80# Start development server in background

81task dev

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```

93**UI Development Workflow**:

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

@@ −1 +1 @@

1−# Agent Handbook

1+# CLAUDE.md

3−## Project Structure & Core Modules

3+Network Connectivity Monitor - AI Agent Guidelines

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/`.

5+## Project Overview

7−## Build, Test, and Runtime Commands

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.

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`.

9+**Key Purpose**: Long-term ISP issue documentation with compelling visual evidence.

1010

11−## Git & Workflow Norms

11+## Architecture & Entry Points

1212

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.

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

1617

17−## Coding Style & Language Guidance

18+### Critical Components

1819

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.

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+```

2030

21−## Testing Expectations

31+## Database Schema Strategy

2232

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.

33+**Smart Retention Pattern**:

2434

25−## Commit & PR Conventions

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

2639

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/`.

40+**Key Insight**: Maintenance runs hourly via `internal/database/maintenance.go` - automatic data aggregation and cleanup.

2841

29−## LLM Shared Resources

42+## Build & Development Workflow

3043

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.

44+### Essential Commands

3645

37−## Shared Utilities & Templates

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+```

3853

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.

54+### Development Mode for UI Work

4055

41−## Shell & Tooling Expectations

56+**Live Static File Editing**: The `task dev` command now enables live editing of HTML, CSS, and JavaScript files without server restarts.

4257

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.

58+```bash

59+task dev # Runs: go run . --dev

60+```

4461

45−## Operations & Configuration Notes

62+**Development Mode Features**:

4663

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.

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

48195