overlapdev 0.0.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Overlap Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,2 +1,169 @@
-# overlapdev
-See https://overlap.dev
+# Overlap Tracer
+
+[![CI](https://github.com/overlapcode/overlap-tracer/actions/workflows/ci.yml/badge.svg)](https://github.com/overlapcode/overlap-tracer/actions/workflows/ci.yml)
+[![Release](https://github.com/overlapcode/overlap-tracer/actions/workflows/release.yml/badge.svg)](https://github.com/overlapcode/overlap-tracer/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/overlapdev.svg)](https://www.npmjs.com/package/overlapdev)
+[![GitHub Release](https://img.shields.io/github/v/release/overlapcode/overlap-tracer)](https://github.com/overlapcode/overlap-tracer/releases/latest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A lightweight background daemon that watches coding agent sessions (Claude Code, with more agents coming) and forwards activity signals to your team's [Overlap](https://overlap.dev) instance.
+
+## What It Does
+
+```
+Developer uses Claude Code → writes JSONL session logs
+                                        ↓
+                              Overlap tracer watches files
+                                        ↓
+                              Parses signals (session lifecycle,
+                              file ops, prompts, costs)
+                                        ↓
+                              Batches & sends to your team's
+                              Overlap dashboard
+```
+
+The tracer extracts **signals, not code**. File contents, assistant responses, and thinking blocks never leave your machine. See [Privacy](#privacy) for the full breakdown.
+
+## Install
+
+```bash
+# Recommended — downloads the right binary for your OS
+curl -fsSL https://overlap.dev/install.sh | sh
+```
+
+Or via npm:
+
+```bash
+npm install -g overlapdev
+```
+
+Or download the binary directly from [GitHub Releases](https://github.com/overlapcode/overlap-tracer/releases/latest).
+
+### Supported Platforms
+
+| Platform | Architecture | Binary |
+|----------|-------------|--------|
+| macOS | Apple Silicon (arm64) | `overlap-darwin-arm64` |
+| macOS | Intel (x64) | `overlap-darwin-x64` |
+| Linux | x64 | `overlap-linux-x64` |
+| Linux | arm64 | `overlap-linux-arm64` |
+| Windows | x64 | `overlap-windows-x64.exe` |
+
+## Quick Start
+
+```bash
+# Join your team (your admin gives you the URL + token)
+overlap join
+
+# Check status
+overlap status
+
+# That's it — sessions are tracked automatically
+```
+
+## Commands
+
+```bash
+overlap join        # Join a team (prompts for instance URL + token)
+overlap check       # Check for team overlaps (used by Claude Code hook)
+overlap status      # Show tracer status, teams, and tracked repos
+overlap leave       # Leave a team
+overlap start       # Start the tracer daemon
+overlap stop        # Stop the tracer daemon
+overlap restart     # Restart the tracer daemon
+overlap debug       # Print parsed events to stdout (no sending)
+overlap uninstall   # Stop daemon, remove service, remove all config
+overlap version     # Show version
+```
+
+## How It Works
+
+1. **You run `overlap join`** — enter your team's Overlap instance URL and the token your admin gave you. The tracer verifies the token, fetches your team's repo list, starts the background daemon, and registers it as a startup service.
+
+2. **The daemon watches `~/.claude/projects/`** for JSONL session files. When you start a Claude Code session in a repo that matches your team's registered repos, the tracer starts tailing the session file.
+
+3. **Events are extracted, enriched, and batched** — session starts, file operations (with line ranges and function names), prompts, and session ends are parsed from JSONL lines, batched (every 2s or 50 events), and sent to your team's Overlap instance via `POST /api/v1/ingest`.
+
+4. **The daemon polls for team state** — every 30 seconds, the daemon fetches active sessions from your team's instance and caches them locally at `~/.overlap/team-state.json`. This powers the real-time coordination hook.
+
+5. **The daemon survives restarts** — byte offsets are persisted to `~/.overlap/state.json`. If the daemon crashes or your machine reboots, it picks up exactly where it left off. No data lost, no duplicates.
+
+## Real-Time Coordination
+
+When you run `overlap join` in a project directory, the tracer sets up Claude Code hooks and commands:
+
+- **PreToolUse hook** — before Claude Code edits a file, `overlap check` reads the local team-state cache and warns if a teammate is working on the same region. The warning includes the teammate's name, a link to their session, and their session summary.
+- **`/project:overlap-check`** — a slash command to manually check for overlaps at any point during a session.
+- **`/project:overlap-context`** — loads what your team is currently working on as context for the session.
+
+The hook is non-blocking: if overlap isn't installed or the cache is stale, it silently exits. Safe to commit `.claude/` to your repo — teammates without overlap installed are unaffected.
+
+## Multi-Team Support
+
+You can join multiple teams. The daemon matches sessions against all teams' repo lists and routes events accordingly.
+
+```bash
+overlap join   # Join first team
+overlap join   # Join second team — daemon reloads automatically
+overlap status # Shows both teams and their repos
+```
+
+## Agent Support
+
+| Agent | Status | `agent_type` |
+|-------|--------|-------------|
+| Claude Code | Supported | `claude_code` |
+| Codex CLI | Planned | `codex` |
+| Gemini CLI | Planned | `gemini_cli` |
+
+The tracer is built on an agent adapter system — each agent gets its own parser. Adding a new agent means implementing one interface, no changes to the server or existing code.
+
+## Privacy
+
+| Sent to your team's Overlap instance | Stays on your machine |
+|--------------------------------------|----------------------|
+| Session ID, timestamps | Assistant response text |
+| Agent type, version | File contents |
+| File paths (relative, stripped of home dir) | Tool outputs / results |
+| Tool names (Write, Edit, Bash, etc.) | Thinking blocks |
+| User prompts | Full absolute paths |
+| Git branch name | API keys, env vars |
+| Cost, tokens, duration | System environment variables |
+| Model name | |
+| Bash commands | |
+| Hostname | |
+
+## Configuration
+
+All tracer data lives in `~/.overlap/`:
+
+```
+~/.overlap/
+├── config.json     # Teams, tokens, tracer settings
+├── state.json      # Byte offsets per session file
+├── cache.json      # Cached repo lists + git remote lookups
+├── logs/
+│   ├── tracer.log
+│   └── tracer.error.log
+└── tracer.pid      # PID of running daemon
+```
+
+## Building from Source
+
+```bash
+# Install dependencies
+bun install
+
+# Run in dev mode
+bun run dev
+
+# Run tests
+bun test
+
+# Build binaries for all platforms
+bash scripts/build-all.sh
+```
+
+## License
+
+MIT

package/bin/run.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * npm wrapper — runs the pre-compiled overlap binary.
+ * The binary is downloaded during postinstall.
+ */
+import { execFileSync } from "child_process";
+import { join, dirname } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ext = process.platform === "win32" ? ".exe" : "";
+const binaryPath = join(__dirname, `overlap${ext}`);
+
+if (!existsSync(binaryPath)) {
+  console.error("Error: Overlap binary not found.");
+  console.error("Try reinstalling: npm install -g overlapdev");
+  console.error("Or download directly: curl -fsSL https://overlap.dev/install.sh | sh");
+  process.exit(1);
+}
+
+try {
+  execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/package.json

@@ -1 +1,30 @@
-{"name":"overlapdev","version":"0.0.1","description":"Reserved for overlap.dev","license":"MIT"}
+{
+  "name": "overlapdev",
+  "version": "1.1.0",
+  "description": "Overlap - See what your team is building with coding agents",
+  "type": "module",
+  "bin": {
+    "overlap": "./bin/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "build": "bun build src/index.ts --outdir dist --target node",
+    "build:binary": "bash scripts/build-all.sh",
+    "dev": "bun run src/index.ts",
+    "test": "bun test"
+  },
+  "keywords": ["coding-agents", "claude-code", "team", "collaboration", "activity", "overlap"],
+  "author": "overlapcode",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/overlapcode/overlap-tracer"
+  },
+  "files": [
+    "bin/",
+    "scripts/postinstall.js"
+  ],
+  "devDependencies": {
+    "bun-types": "^1.3.9"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script for the overlapdev npm package.
+ * Downloads the correct pre-compiled binary for the user's platform.
+ */
+import { existsSync, mkdirSync, chmodSync, createWriteStream } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import https from "https";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO = "overlapcode/overlap-tracer";
+const BIN_DIR = join(__dirname, "..", "bin");
+const BINARY_PATH = join(BIN_DIR, process.platform === "win32" ? "overlap.exe" : "overlap");
+
+function getPlatformTarget() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  const platformMap = { darwin: "darwin", linux: "linux", win32: "windows" };
+  const archMap = { x64: "x64", arm64: "arm64" };
+
+  const p = platformMap[platform];
+  const a = archMap[arch];
+
+  if (!p || !a) {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    process.exit(1);
+  }
+
+  const ext = platform === "win32" ? ".exe" : "";
+  return `overlap-${p}-${a}${ext}`;
+}
+
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        // Follow redirect
+        return httpsGet(res.headers.location).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        return;
+      }
+      resolve(res);
+    }).on("error", reject);
+  });
+}
+
+async function getLatestVersion() {
+  const res = await httpsGet(`https://api.github.com/repos/${REPO}/releases/latest`);
+  return new Promise((resolve, reject) => {
+    let data = "";
+    res.on("data", (chunk) => (data += chunk));
+    res.on("end", () => {
+      try {
+        const json = JSON.parse(data);
+        resolve(json.tag_name);
+      } catch (e) {
+        reject(e);
+      }
+    });
+    res.on("error", reject);
+  });
+}
+
+async function download(url, dest) {
+  const res = await httpsGet(url);
+  return new Promise((resolve, reject) => {
+    const file = createWriteStream(dest);
+    res.pipe(file);
+    file.on("finish", () => { file.close(); resolve(); });
+    file.on("error", reject);
+  });
+}
+
+async function main() {
+  // Skip if binary already exists (e.g., CI or manual install)
+  if (existsSync(BINARY_PATH)) {
+    return;
+  }
+
+  const target = getPlatformTarget();
+  console.log(`[overlap] Downloading binary for ${process.platform}-${process.arch}...`);
+
+  let version;
+  try {
+    version = await getLatestVersion();
+  } catch {
+    console.warn("[overlap] Could not determine latest version. Skipping binary download.");
+    console.warn("[overlap] You can download manually from: https://github.com/overlapcode/overlap-tracer/releases");
+    return;
+  }
+
+  const url = `https://github.com/${REPO}/releases/download/${version}/${target}`;
+
+  mkdirSync(BIN_DIR, { recursive: true });
+
+  try {
+    await download(url, BINARY_PATH);
+    if (process.platform !== "win32") {
+      chmodSync(BINARY_PATH, 0o755);
+    }
+    console.log(`[overlap] ✓ Installed ${target} (${version})`);
+  } catch (err) {
+    console.warn(`[overlap] Binary download failed: ${err.message}`);
+    console.warn(`[overlap] Download manually from: https://github.com/${REPO}/releases/tag/${version}`);
+  }
+}
+
+main();