|
| 1 | +--- |
| 2 | +status: planned |
| 3 | +created: '2025-12-05' |
| 4 | +tags: [architecture, simplification, go, refactor] |
| 5 | +priority: high |
| 6 | +created_at: '2025-12-05T03:18:55.302Z' |
| 7 | +--- |
| 8 | + |
| 9 | +# 014-core-simplification |
| 10 | + |
| 11 | +> **Status**: 📅 Planned · **Priority**: High · **Created**: 2025-12-05 |
| 12 | +
|
| 13 | +## Overview |
| 14 | + |
| 15 | +Reposition devlog as a **Go-only AI agent event collector and parser**. The current TypeScript/Node.js codebase has accumulated unnecessary complexity. Go provides the right foundation: single binary, low resource footprint, excellent concurrency for file watching and event streaming. |
| 16 | + |
| 17 | +### Core Mission |
| 18 | + |
| 19 | +A lightweight daemon that: |
| 20 | + |
| 21 | +1. **Watches** AI coding tool log files (Copilot, Cursor, Claude, Windsurf, etc.) |
| 22 | +2. **Parses** sessions and events into structured data |
| 23 | +3. **Sends** events to configurable remote endpoints (agent-relay, custom backends) |
| 24 | + |
| 25 | +### Why Go-Only? |
| 26 | + |
| 27 | +- Single static binary - no Node.js/npm runtime dependencies |
| 28 | +- Low memory footprint for always-on daemon |
| 29 | +- Excellent file watching and concurrent I/O |
| 30 | +- Already have `collector-go/` as foundation |
| 31 | +- Matches agent-relay's Go backend |
| 32 | + |
| 33 | +### What Gets Removed |
| 34 | + |
| 35 | +- **All TypeScript packages** (`packages/*` except `collector-go`) |
| 36 | +- **All Node.js tooling** (pnpm, turbo, vitest, etc.) |
| 37 | +- **Web UI** (`apps/web/`) |
| 38 | +- **Prisma/database layer** - events sent to remote, not stored locally |
| 39 | + |
| 40 | +## Design |
| 41 | + |
| 42 | +### Target Architecture |
| 43 | + |
| 44 | +``` |
| 45 | +devlog (Go-only) |
| 46 | +├── cmd/ |
| 47 | +│ └── devlog/ # Main binary entry point |
| 48 | +├── internal/ |
| 49 | +│ ├── watcher/ # File system watching |
| 50 | +│ ├── parser/ # Log parsing (Copilot, Cursor, Claude, etc.) |
| 51 | +│ ├── events/ # Event types and serialization |
| 52 | +│ └── sender/ # Remote event dispatch |
| 53 | +├── pkg/ # Public APIs if needed |
| 54 | +└── configs/ # Default configurations |
| 55 | +``` |
| 56 | + |
| 57 | +### Event Flow |
| 58 | + |
| 59 | +``` |
| 60 | +[Log Files] → [Watcher] → [Parser] → [Events] → [Sender] → [Remote] |
| 61 | + ↓ |
| 62 | + agent-relay / custom |
| 63 | +``` |
| 64 | + |
| 65 | +### Configuration |
| 66 | + |
| 67 | +```yaml |
| 68 | +# ~/.config/devlog/config.yaml |
| 69 | +watchers: |
| 70 | + - name: copilot |
| 71 | + path: ~/.config/github-copilot/logs/ |
| 72 | + parser: copilot |
| 73 | + - name: cursor |
| 74 | + path: ~/.cursor/logs/ |
| 75 | + parser: cursor |
| 76 | + |
| 77 | +remote: |
| 78 | + endpoint: http://localhost:8080/api/events |
| 79 | + # or: ws://localhost:8080/ws/events |
| 80 | + auth_token: ${DEVLOG_TOKEN} |
| 81 | + batch_size: 100 |
| 82 | + flush_interval: 5s |
| 83 | +``` |
| 84 | +
|
| 85 | +### Supported Parsers (Initial) |
| 86 | +
|
| 87 | +- GitHub Copilot |
| 88 | +- Cursor |
| 89 | +- Claude Code (Anthropic) |
| 90 | +- Windsurf |
| 91 | +- Generic JSON/JSONL |
| 92 | +
|
| 93 | +### Remote Integration |
| 94 | +
|
| 95 | +Events are POSTed or streamed via WebSocket to configurable endpoints: |
| 96 | +
|
| 97 | +- **agent-relay**: Native integration for session visualization |
| 98 | +- **Custom backends**: Webhook-style event ingestion |
| 99 | +- **stdout**: For piping to other tools |
| 100 | +
|
| 101 | +## Plan |
| 102 | +
|
| 103 | +- [ ] Phase 1: Audit `collector-go/` - identify reusable parsing logic |
| 104 | +- [ ] Phase 2: Design event schema and remote API contract |
| 105 | +- [ ] Phase 3: Implement core watcher → parser → sender pipeline |
| 106 | +- [ ] Phase 4: Add parser support (Copilot, Cursor, Claude, Windsurf) |
| 107 | +- [ ] Phase 5: Configuration and CLI interface |
| 108 | +- [ ] Phase 6: Remove all TypeScript/Node.js code |
| 109 | +- [ ] Phase 7: Update build/release (single binary, Docker image) |
| 110 | +- [ ] Phase 8: Document agent-relay integration |
| 111 | + |
| 112 | +## Test |
| 113 | + |
| 114 | +- [ ] Daemon starts and watches configured paths |
| 115 | +- [ ] Events parsed correctly for each supported tool |
| 116 | +- [ ] Events sent to remote endpoint with retries |
| 117 | +- [ ] Single binary works without external dependencies |
| 118 | +- [ ] Configuration loading from file and env vars |
| 119 | + |
| 120 | +## Notes |
| 121 | + |
| 122 | +### Migration from TypeScript |
| 123 | + |
| 124 | +| Current | Action | |
| 125 | +| ------------------------ | -------------------------- | |
| 126 | +| `packages/collector-go/` | Promote to root, expand | |
| 127 | +| `packages/collector/` | Port parsing logic to Go | |
| 128 | +| `packages/core/` | Port event types to Go | |
| 129 | +| `packages/ai/` | Remove (not needed) | |
| 130 | +| `packages/cli/` | Replace with Go CLI | |
| 131 | +| `packages/mcp/` | Remove or separate project | |
| 132 | +| `packages/shared/` | Remove | |
| 133 | +| `packages/web/` | Remove | |
| 134 | +| `apps/web/` | Remove | |
| 135 | +| `prisma/` | Remove (no local DB) | |
| 136 | + |
| 137 | +### Event Schema (Draft) |
| 138 | + |
| 139 | +```go |
| 140 | +type Event struct { |
| 141 | + ID string `json:"id"` |
| 142 | + Type string `json:"type"` // session_start, completion, error, etc. |
| 143 | + Source string `json:"source"` // copilot, cursor, claude, etc. |
| 144 | + Timestamp time.Time `json:"timestamp"` |
| 145 | + SessionID string `json:"session_id,omitempty"` |
| 146 | + Data map[string]any `json:"data"` |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +### Open Questions |
| 151 | + |
| 152 | +1. Should we embed agent-relay integration or keep it generic? |
| 153 | +2. Local event buffering strategy when remote is unavailable? |
| 154 | +3. Plugin system for custom parsers? |
0 commit comments