{"_id":"@6digit/sidetrack","_rev":"5-a6ddbfc44e083167561d6e178173e90a","name":"@6digit/sidetrack","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@6digit/sidetrack","version":"0.1.0","keywords":["observability","debugging","development","ai","claude","tracing","console","logging"],"author":{"name":"6digit Studio"},"license":"MIT","_id":"@6digit/sidetrack@0.1.0","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"homepage":"https://github.com/6digit-studio/sidetrack#readme","bugs":{"url":"https://github.com/6digit-studio/sidetrack/issues"},"bin":{"sidetrack":"cli/index.ts"},"dist":{"shasum":"5501de6fda4a918fd6f96e432da05e499cb3ff49","tarball":"https://registry.npmjs.org/@6digit/sidetrack/-/sidetrack-0.1.0.tgz","fileCount":19,"integrity":"sha512-a31oXAYu6JXbJWVRDnwdlwjRTaesd6DqngwRLbLaX5uzRncYbZeol0PqWe2PC8do7F2v9q6HbSFrR0m9mvHqGQ==","signatures":[{"sig":"MEYCIQDYOH/hGqyRlqkdTwoxVusqp15Rmufy9Sj2dWUGvXZcKwIhAMSmfKBJCrY8jJdhLeKi0Gb6Sq6LUbFn9UNvmbUOImDh","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":979149},"main":"./client/dist/index.cjs","type":"module","types":"./client/dist/index.d.ts","module":"./client/dist/index.mjs","exports":{".":{"types":"./client/dist/index.d.ts","import":"./client/dist/index.mjs","require":"./client/dist/index.cjs"},"./browser":"./client/dist/sidetrack.js"},"gitHead":"ac3e086b7246c4ee38eda04f30e78937af4a11e8","scripts":{"dev":"bun --hot server/index.ts","build":"cd client && bun run build.ts","start":"bun run server/index.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"repository":{"url":"git+https://github.com/6digit-studio/sidetrack.git","type":"git"},"_npmVersion":"11.4.2","description":"Development observability for AI-assisted coding - traceability and visibility into running code","directories":{},"_nodeVersion":"23.2.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/sidetrack_0.1.0_1775945401205_0.8464843652339158","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@6digit/sidetrack","version":"0.1.1","keywords":["observability","debugging","development","ai","claude","tracing","console","logging"],"author":{"name":"6digit Studio"},"license":"MIT","_id":"@6digit/sidetrack@0.1.1","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"homepage":"https://github.com/6digit-studio/sidetrack#readme","bugs":{"url":"https://github.com/6digit-studio/sidetrack/issues"},"bin":{"sidetrack":"cli/index.ts"},"dist":{"shasum":"69aa56ec61c6283502fe05757f6069f3120fd625","tarball":"https://registry.npmjs.org/@6digit/sidetrack/-/sidetrack-0.1.1.tgz","fileCount":19,"integrity":"sha512-61R3vyNK4cqktGMunqKyJwY21vUDUVdlt22NSQ0xkNlIpNAIyTBUYgdjwLQZ0yMIDK7LL/rKq2yHsMW7EFsHLQ==","signatures":[{"sig":"MEUCID8afCsYb6z+SEJDUKfzrIcQVbKGpXKUWfFcx/ZBaavWAiEArkMYACFiQzVVoGqYlDqfRFBr0T/enNH6kfOJzeaZj0c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":980191},"main":"./client/dist/index.cjs","type":"module","types":"./client/dist/index.d.ts","module":"./client/dist/index.mjs","exports":{".":{"types":"./client/dist/index.d.ts","import":"./client/dist/index.mjs","require":"./client/dist/index.cjs"},"./browser":"./client/dist/sidetrack.js"},"gitHead":"697c424ed35b658d6c4b85d28e7ec55fbc652ddf","scripts":{"dev":"bun --hot server/index.ts","build":"cd client && bun run build.ts","start":"bun run server/index.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"repository":{"url":"git+https://github.com/6digit-studio/sidetrack.git","type":"git"},"_npmVersion":"11.4.2","description":"Development observability for AI-assisted coding. Server, CLI, and client library. For client-only, see @6digit/sidetrack-client","directories":{},"_nodeVersion":"23.2.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/sidetrack_0.1.1_1775946566046_0.6503780994159865","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@6digit/sidetrack","version":"0.1.2","keywords":["observability","debugging","development","ai","claude","tracing","console","logging"],"author":{"name":"6digit Studio"},"license":"MIT","_id":"@6digit/sidetrack@0.1.2","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"homepage":"https://github.com/6digit-studio/sidetrack#readme","bugs":{"url":"https://github.com/6digit-studio/sidetrack/issues"},"bin":{"sidetrack":"cli/index.ts"},"dist":{"shasum":"b8db90e22d955dc0ebdcc90ae8598d1be4a8fdce","tarball":"https://registry.npmjs.org/@6digit/sidetrack/-/sidetrack-0.1.2.tgz","fileCount":19,"integrity":"sha512-i48oNLyQWY+RMiVIawRb53vJ3WF5sconn49+QUiNiou4VOEEp+MftHF9U1BP1fCVGeFOh6rT7ENUtKVD4GdBUw==","signatures":[{"sig":"MEYCIQC3PoRZQj8FFdMoE8oIBDNz3lutJ7YmKD7CkmkGmDTM3QIhANkdyRM/FaAoW8fB45LfAn5rUCLVd3/eUu9rN6+1mn27","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":980568},"main":"./client/dist/index.cjs","type":"module","types":"./client/dist/index.d.ts","module":"./client/dist/index.mjs","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./client/dist/index.d.ts","import":"./client/dist/index.mjs","require":"./client/dist/index.cjs"},"./browser":"./client/dist/sidetrack.js"},"gitHead":"10af31a91535ee91ede94e85ac3d93ebfc806d13","scripts":{"dev":"bun --hot server/index.ts","build":"cd client && bun run build.ts","start":"bun run server/index.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"repository":{"url":"git+https://github.com/6digit-studio/sidetrack.git","type":"git"},"_npmVersion":"11.4.2","description":"Development observability for AI-assisted coding. Server, CLI, and client library. For client-only, see @6digit/sidetrack-client","directories":{},"_nodeVersion":"23.2.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/sidetrack_0.1.2_1775950194378_0.9710082788527554","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@6digit/sidetrack","version":"0.1.3","keywords":["observability","debugging","development","ai","claude","tracing","console","logging"],"author":{"name":"6digit Studio"},"license":"MIT","_id":"@6digit/sidetrack@0.1.3","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"homepage":"https://github.com/6digit-studio/sidetrack#readme","bugs":{"url":"https://github.com/6digit-studio/sidetrack/issues"},"bin":{"sidetrack":"cli/index.ts"},"dist":{"shasum":"01bdc1f440f84df13acfcf2d60217f6aa81c91b6","tarball":"https://registry.npmjs.org/@6digit/sidetrack/-/sidetrack-0.1.3.tgz","fileCount":19,"integrity":"sha512-OXXcwDLyPH4Joc3mQvjhwg7YV6e+XPgNQFg69NPAF0dzCnU8n0c8ayOqOSnTNffhaf/TBPMutl9ojoT/IKSvkg==","signatures":[{"sig":"MEYCIQDPCPgTnnzZhFG+xFHjc2Cbl1Km8g6TKdcXJUGCJwDbAAIhANE6TyNWV7bHuAs2ZyGkRCI4AGAjN2IJB0Dzd5DCawID","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":993531},"main":"./client/dist/index.cjs","type":"module","types":"./client/dist/index.d.ts","module":"./client/dist/index.mjs","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./client/dist/index.d.ts","import":"./client/dist/index.mjs","require":"./client/dist/index.cjs"},"./browser":"./client/dist/sidetrack.js"},"gitHead":"49fc8aea7d8816dca26f6caa258397e0d8f551bb","scripts":{"dev":"bun --hot server/index.ts","build":"cd client && bun run build.ts","start":"bun run server/index.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"repository":{"url":"git+https://github.com/6digit-studio/sidetrack.git","type":"git"},"_npmVersion":"11.4.2","description":"Development observability for AI-assisted coding. Server, CLI, and client library. For client-only, see @6digit/sidetrack-client","directories":{},"_nodeVersion":"23.2.0","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/sidetrack_0.1.3_1776003289288_0.672738832783947","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@6digit/sidetrack","version":"0.2.0","description":"Development observability for AI-assisted coding. Server, CLI, and client library. For client-only, see @6digit/sidetrack-client","type":"module","bin":{"sidetrack":"cli/index.ts"},"main":"./client/dist/index.cjs","module":"./client/dist/index.mjs","types":"./client/dist/index.d.ts","exports":{".":{"import":"./client/dist/index.mjs","require":"./client/dist/index.cjs","types":"./client/dist/index.d.ts"},"./browser":"./client/dist/sidetrack.js"},"scripts":{"start":"bun run server/index.ts","dev":"bun --hot server/index.ts","build":"cd client && bun run build.ts","prepublishOnly":"npm run build"},"repository":{"type":"git","url":"git+https://github.com/6digit-studio/sidetrack.git"},"keywords":["observability","debugging","development","ai","claude","tracing","console","logging"],"author":{"name":"6digit Studio"},"license":"MIT","bugs":{"url":"https://github.com/6digit-studio/sidetrack/issues"},"homepage":"https://github.com/6digit-studio/sidetrack#readme","engines":{"bun":">=1.0.0"},"devDependencies":{"@types/bun":"latest","typescript":"^5"},"_id":"@6digit/sidetrack@0.2.0","gitHead":"a628cb85bd45c54a5955388b814f9a57e4d9ca38","_nodeVersion":"23.2.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-Knh2oUD/609ELmiGcQHpko3zL3vHYMQg4cMhrJVNvGqaAyaFFPmwdOYS4V35POedYyyWttP5AW5XJXV2SHyhtw==","shasum":"ddb10e5ad0d9a69c80fc66a1329562c7394e78a5","tarball":"https://registry.npmjs.org/@6digit/sidetrack/-/sidetrack-0.2.0.tgz","fileCount":22,"unpackedSize":1067890,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDiai4d77aqJaN0Vfbcikh1EmZYiXV4lC5bx9z0SkHL8QIgSGDjWAqwF1+n54DqZE5MPmRPsKbmgnlYyt+aDkR+mRg="}]},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"directories":{},"maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sidetrack_0.2.0_1776736462160_0.890077570173962"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-11T22:10:01.141Z","modified":"2026-04-21T01:54:22.481Z","0.1.0":"2026-04-11T22:10:01.356Z","0.1.1":"2026-04-11T22:29:26.262Z","0.1.2":"2026-04-11T23:29:54.556Z","0.1.3":"2026-04-12T14:14:49.468Z","0.2.0":"2026-04-21T01:54:22.331Z"},"bugs":{"url":"https://github.com/6digit-studio/sidetrack/issues"},"author":{"name":"6digit Studio"},"license":"MIT","homepage":"https://github.com/6digit-studio/sidetrack#readme","keywords":["observability","debugging","development","ai","claude","tracing","console","logging"],"repository":{"type":"git","url":"git+https://github.com/6digit-studio/sidetrack.git"},"description":"Development observability for AI-assisted coding. Server, CLI, and client library. For client-only, see @6digit/sidetrack-client","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"readme":"# Sidetrack\n\nDevelopment observability for AI-assisted coding. Your AI assistant can finally see what's happening in your app.\n\n## The Problem\n\nAI coding assistants are blind to runtime. They can read your code, but they can't see:\n- What's logging to the console\n- What network requests are failing\n- What errors are being thrown\n- What the user is clicking on\n\nDebugging becomes a game of copy-paste telephone between you and your AI.\n\n## The Solution\n\nSidetrack captures everything from your running app and makes it queryable. Your AI assistant can directly see what's happening - no more \"can you paste the error message?\"\n\n```bash\n# AI assistant runs this and instantly sees your app's state\ncurl http://localhost:6274/recent?_type=console.error\n```\n\n## Quick Start\n\n**1. Install sidetrack globally:**\n\n```bash\nbun add -g @6digit/sidetrack\n```\n\n**2. Initialize your project:**\n\n```bash\ncd your-project\nsidetrack init    # Creates .sidetrack/config.json\n```\n\n**3. Add to your app:**\n\n```bash\nnpm install @6digit/sidetrack-client\n# or: bun add @6digit/sidetrack-client\n```\n\n```typescript\nimport { init } from '@6digit/sidetrack-client'\n\ninit()  // Discovers config, auto-starts server, captures everything\n```\n\n**4. Query from anywhere in the project:**\n\n```bash\nsidetrack recent                  # Recent events\nsidetrack search \"error\"          # Search for errors\nsidetrack stats                   # Check if it's running\n```\n\nThe CLI automatically finds your `.sidetrack/config.json` and talks to the right server.\n\n## Project Configuration\n\nEach project can have its own sidetrack server, keeping events isolated:\n\n```bash\ncd ~/src/my-app\nsidetrack init              # Uses default port 6274\n```\n\n**For related projects** (frontend + API + worker) that should share a server:\n\n```bash\ncd ~/src/my-app-api\nsidetrack init --port=6280\n\ncd ~/src/my-app-frontend  \nsidetrack init --port=6280  # Same port = shared server\n\ncd ~/src/my-app-worker\nsidetrack init --port=6280\n```\n\nAll three projects now share the same observability backplane. Query from any of them and see the full picture.\n\n## What Gets Captured\n\nEverything. By default. No configuration needed.\n\n| Category | What's Captured |\n|----------|-----------------|\n| **Console** | All console methods (log, warn, error, debug, info, trace, table, etc.) with stack traces |\n| **Errors** | Uncaught exceptions, unhandled promise rejections |\n| **Network** | Every fetch/XHR/http request and response - URL, headers, body, timing |\n| **Async** | Promise lifecycle, setTimeout/setInterval (Node/Bun) |\n| **DOM** | Clicks, form submissions, navigation, visibility changes (browser) |\n\n## Multi-Runtime Support\n\nSidetrack auto-detects your environment and captures what's available:\n\n| Runtime | Console | Errors | Network | Async Hooks | DOM |\n|---------|:-------:|:------:|:-------:|:-----------:|:---:|\n| Browser | ✓ | ✓ | ✓ | - | ✓ |\n| Node.js | ✓ | ✓ | ✓ | ✓ | - |\n| Bun | ✓ | ✓ | ✓ | ✓ | - |\n| Deno | ✓ | ✓ | ✓ | - | - |\n| Workers | ✓ | ✓ | ✓ | - | - |\n\n## API Reference\n\nThe server is self-documenting:\n\n```bash\ncurl http://localhost:6274/help\n```\n\n### Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `POST /events` | Ingest events (any JSON) |\n| `GET /recent` | Query recent events (supports compound filters, see below) |\n| `GET /search?q=term` | Full-text search |\n| `GET /stream` | Server-Sent Events stream of new events (`?pattern=regex` or `?cwd=/path`) |\n| `GET /stats` | Event count and time span |\n| `GET /help` | API documentation |\n| `POST /commands` | Submit a command for a registered client to run (see Commands Backplane) |\n| `GET /commands/pending` | Pending commands (clients poll this) |\n| `GET /commands/:id` | Command status and result |\n\n### Filtering\n\n`/recent` supports compound AND filters with three operators — chain as many as you like with `&`:\n\n```bash\n# Exact match (default)\ncurl \"http://localhost:6274/recent?_type=console.error\"\ncurl \"http://localhost:6274/recent?_runtime=bun\"\ncurl \"http://localhost:6274/recent?status=500\"\n\n# Negation — field differs from value, or is absent\ncurl \"http://localhost:6274/recent?_type!=sidetrack.heartbeat\"\n\n# Substring — field contains value\ncurl \"http://localhost:6274/recent?url~=/api/\"\n\n# Combine — all filters are AND'd\ncurl \"http://localhost:6274/recent?_type=fetch.response&status=404&limit=10\"\ncurl \"http://localhost:6274/recent?url~=/api/&_type!=sidetrack.heartbeat\"\n```\n\n## Checkpoints\n\nEmit custom timing checkpoints for performance analysis and correlation:\n\n```typescript\nimport { init } from '@6digit/sidetrack-client'\n\nconst sidetrack = init()\nconst sessionId = crypto.randomUUID()\n\nsidetrack.checkpoint(sessionId, 'app_start')\nsidetrack.checkpoint(sessionId, 'queries_subscribed', { count: 14 })\n// ... time passes ...\nsidetrack.checkpoint(sessionId, 'all_queries_ready')\nsidetrack.checkpoint(sessionId, 'render_complete')\n```\n\nQuery checkpoints by correlation ID:\n```bash\ncurl \"http://localhost:6274/recent?_type=checkpoint&id=abc-123\"\n```\n\nThe timestamps let you compute duration between any two checkpoints. Use the correlation ID to track a request, session, or app instance across its lifecycle.\n\n## Heartbeats\n\nEvery client emits a `sidetrack.heartbeat` event every 10 seconds. This is a liveness signal for the subject itself, independent of whether it's doing anything interesting — so you can tell **idle** from **hung** from **queue-backed-up** at a glance.\n\nEach heartbeat carries:\n\n```json\n{\n  \"_type\": \"sidetrack.heartbeat\",\n  \"queueDepth\": 0,\n  \"lastFlushAt\": 1730000000000,\n  \"eventsSinceLastHeartbeat\": 42,\n  \"cwd\": \"/Users/you/src/your-app\"\n}\n```\n\n- `queueDepth` — events buffered but not yet flushed\n- `lastFlushAt` — ms timestamp of the last successful flush (`0` if never)\n- `eventsSinceLastHeartbeat` — non-heartbeat events captured since the previous tick (heartbeats don't count themselves)\n\nInterpret the three cases:\n\n| What you see | Subject state |\n|---|---|\n| Heartbeats arriving, `queueDepth=0`, `eventsSinceLastHeartbeat=0` | **Idle** — alive, nothing to report |\n| Heartbeats stopped arriving | **Hung** — crashed, frozen, or process died |\n| Heartbeats arriving, `queueDepth` climbing, `lastFlushAt` not advancing | **Backed up** — alive but can't flush (server unreachable, network stalled) |\n\nTune or disable via the `heartbeatInterval` client option (ms, default `10000`, set to `0` to disable):\n\n```typescript\ninit({ heartbeatInterval: 5000 })\n```\n\nFilter heartbeats out of routine queries with the negation operator:\n\n```bash\ncurl \"http://localhost:6274/recent?_type!=sidetrack.heartbeat\"\n```\n\n## Commands Backplane\n\nClients can register handlers that other processes — CLIs, scripts, AI agents — invoke over HTTP. Useful for a loosely-coupled bus where one process exposes capabilities and another consumes them.\n\nRegister on the client:\n\n```typescript\nconst sidetrack = init()\nsidetrack.register('hello', (name: string) => `Hi, ${name}`)\n```\n\nInvoke from anywhere:\n\n```bash\n# Submit a command\ncurl -X POST http://localhost:6274/commands \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"hello\",\"args\":[\"world\"]}'\n# → {\"ok\":true,\"id\":\"cmd_...\"}\n\n# Poll for the result\ncurl http://localhost:6274/commands/cmd_...\n# → {\"id\":\"cmd_...\",\"status\":\"completed\",\"result\":\"Hi, world\", ...}\n```\n\nUnder the hood: the client polls `/commands/pending`, runs the handler, and POSTs the result. Pending/completed/failed state is queryable for the retention window.\n\n## Client Configuration\n\nSidetrack captures aggressively by default. You can dial it back if needed:\n\n```typescript\ninit({\n  endpoint: 'http://localhost:6274/events',  // Where to send events\n  flushInterval: 500,                         // ms between flushes\n  heartbeatInterval: 10000,                   // ms between heartbeats (0 disables)\n\n  capture: {\n    console: true,   // Console methods\n    errors: true,    // Uncaught errors\n    network: true,   // fetch/XHR/http\n    async: true,     // Async hooks (Node/Bun)\n    dom: true,       // DOM events (browser)\n  },\n\n  tags: {            // Added to every event\n    app: 'my-app',\n    env: 'development',\n  },\n})\n```\n\n## Server Configuration\n\nThe server reads config from, in order of precedence:\n\n1. Environment variables\n2. `.sidetrack/config.json` discovered by walking up from the cwd\n3. Built-in defaults\n\n| Env var | Default | Description |\n|---|---|---|\n| `PORT` | `6274` | Server port (also settable via `.sidetrack/config.json`) |\n| `SIDETRACK_MAX_AGE_MS` | `3600000` (1 hour) | Retention window in milliseconds. Events older than this are pruned every 30 seconds. |\n\n## For AI Assistants\n\nIf you're an AI assistant and the developer has sidetrack running:\n\n```bash\n# Learn the API\ncurl http://localhost:6274/help\n\n# See recent activity (exclude heartbeat noise)\ncurl \"http://localhost:6274/recent?_type!=sidetrack.heartbeat&limit=20\"\n\n# Find errors\ncurl \"http://localhost:6274/recent?_type=console.error\"\ncurl \"http://localhost:6274/recent?_type=error.uncaught\"\n\n# See network failures — or anything touching a URL path\ncurl \"http://localhost:6274/recent?_type=fetch.error\"\ncurl \"http://localhost:6274/recent?url~=/api/\"\ncurl \"http://localhost:6274/search?q=500\"\n\n# Check if a specific subject is alive\ncurl \"http://localhost:6274/recent?_type=sidetrack.heartbeat&cwd=/path/to/app&limit=3\"\n\n# Check if the server itself is running\ncurl http://localhost:6274/stats\n```\n\nYou now have direct visibility into runtime state. No more asking the human to copy-paste from DevTools.\n\n## Design Philosophy\n\n**Capture aggressively, query smartly.** \n\nThe developer's machine is powerful enough to handle a firehose of events. We capture everything and let the query layer (and AI assistants) filter down to what matters. This is not a production logging system - it's a development tool that maximizes observability while minimizing setup.\n\n- **Zero config** - Works immediately with sensible defaults\n- **1-hour retention** - Recent events only (configurable via `SIDETRACK_MAX_AGE_MS`), keeps it fast\n- **No schema** - Any JSON goes in, query by any field\n- **Development only** - Not for production, not for metrics - for traceability and visibility into running code\n\n## Architecture\n\n```\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   Browser   │     │   Node.js   │     │     Bun     │\n│             │     │             │     │             │\n│ @6digit/    │     │ @6digit/    │     │ @6digit/    │\n│ sidetrack   │     │ sidetrack   │     │ sidetrack   │\n└──────┬──────┘     └──────┬──────┘     └──────┬──────┘\n       │                   │                   │\n       └───────────────────┼───────────────────┘\n                           │\n                           ▼\n                 POST http://localhost:6274/events\n                           │\n                           ▼\n               ┌───────────────────────┐\n               │   Sidetrack Server    │\n               │                       │\n               │  SQLite (in-memory)   │\n               │  1-hour retention     │\n               └───────────┬───────────┘\n                           │\n                           ▼\n               GET /recent, /search, /stats\n                           │\n                           ▼\n               ┌───────────────────────┐\n               │    AI Assistant or    │\n               │    Developer Query    │\n               └───────────────────────┘\n```\n\n## Installation\n\n### Requirements\n\n**The server and CLI require [Bun](https://bun.sh/).** The server uses `bun:sqlite` and `Bun.serve()` for performance. Node.js is not supported for the server.\n\nThe client library (`@6digit/sidetrack-client`) works with any runtime (browser, Node.js, Bun, Deno).\n\n### Global Install (Recommended)\n\n```bash\n# Install globally with Bun\nbun add -g @6digit/sidetrack\n\n# Start the server\nsidetrack server\n\n# Install the Claude skill (enables /sidetrack in Claude Code)\nsidetrack install skill\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/6digit-studio/sidetrack.git\ncd sidetrack\nbun run start\n```\n\n### Client Library (for your app)\n\nThe client works with any package manager and runtime:\n\n```bash\nnpm install @6digit/sidetrack-client\n# or: bun add @6digit/sidetrack-client\n```\n\nThen in your app:\n```typescript\nimport { init } from '@6digit/sidetrack-client'\ninit()\n```\n\n## CLI Commands\n\n```bash\n# Project setup\nsidetrack init [--port=N]     # Initialize project config\nsidetrack server              # Start the server manually\nsidetrack install skill       # Install Claude skill to ~/.claude/skills/\n\n# Querying\nsidetrack recent [limit]      # Show recent events\nsidetrack search <term>       # Search events\nsidetrack stats               # Show statistics\nsidetrack tail [pattern]      # Stream events in real-time\nsidetrack await <pattern>     # Block until pattern matches\n\n# Feedback\nsidetrack feedback            # List open feedback\nsidetrack resolve <id>        # Mark feedback resolved\nsidetrack wontfix <id>        # Mark feedback as wontfix\n\nsidetrack help                # Show active config and all commands\n```\n\nThe CLI automatically discovers `.sidetrack/config.json` by walking up from your current directory.\n\n## Claude Skill\n\nAfter running `sidetrack install skill`, any Claude Code session can query sidetrack directly. The skill teaches Claude:\n- How to check recent events\n- How to search for errors\n- How to read and manage feedback\n- When to proactively check sidetrack\n\n## Browser Script Tag (Alternative)\n\nIf you can't use the npm package:\n\n```html\n<script src=\"http://localhost:6274/inject.js\"></script>\n```\n\nThis is a simpler inline script that captures console and errors only.\n\n## Contributing\n\nThis project exists because AI coding assistants need better observability into running applications. If you have ideas for:\n\n- Additional capture sources (databases, state management, etc.)\n- Better query capabilities\n- Integrations with specific frameworks\n- Performance improvements\n\nPlease open an issue or PR at [github.com/6digit-studio/sidetrack](https://github.com/6digit-studio/sidetrack).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}