@superbased/observer 1.3.0

package/README.md

@@ -0,0 +1,82 @@
+# @superbased/observer
+
+[![npm](https://img.shields.io/npm/v/@superbased/observer.svg)](https://www.npmjs.com/package/@superbased/observer)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+SuperBased Observer — capture, normalize, compress, and analyze AI
+coding tool activity across **Claude Code**, **Codex**, **Cursor**,
+**Cline/Roo Code**, and **GitHub Copilot**.
+
+Single binary. Local-only (no network calls from the observer
+itself). Pure-Go, no CGO.
+
+## Install
+
+```bash
+npm install -g @superbased/observer
+observer --version
+```
+
+The package ships pre-built binaries for:
+
+| Platform              | Architecture |
+| --------------------- | ------------ |
+| Linux                 | x64, arm64   |
+| macOS (Intel)         | x64          |
+| macOS (Apple Silicon) | arm64        |
+| Windows               | x64          |
+
+If you're on a platform that isn't listed, file an issue or build the
+binary from source — see the
+[main repo](https://github.com/marmutapp/superbased-observer).
+
+## Quick start
+
+```bash
+# 1. Install the package + register hooks with the AI clients you use.
+npm install -g @superbased/observer
+observer init
+
+# 2. Start the long-running watcher + dashboard + proxy in one process.
+observer start &
+
+# 3. Engage the proxy by pointing your AI client at the local URL.
+#    Claude Code / Cursor (Anthropic mode):
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8820
+#    Codex / Cursor (OpenAI mode):
+export OPENAI_BASE_URL=http://127.0.0.1:8820/v1
+
+# 4. Open the dashboard.
+open http://127.0.0.1:8081/
+```
+
+## What you get
+
+- **Real-time dashboard** at `http://127.0.0.1:8081/` — cost over
+  time, tool activity, compression savings, stale rereads, patterns,
+  per-tool action breakdowns, and full-workbook Excel export.
+- **Conversation compression** — pre-forward trimming of API request
+  bodies. Per-mechanism breakdown (json / code / logs / text / diff /
+  html / drop) so you can see exactly what saved how many tokens.
+- **MCP server** with 12 tools every connected AI client can use to
+  query each other's recorded work — `get_last_test_result`,
+  `check_file_freshness`, `get_failure_context`, etc.
+- **Patterns engine** — `observer patterns` derives repeatable
+  behaviours from session history; `observer suggest` writes them
+  into `CLAUDE.md` / `AGENTS.md` / `.cursorrules` so new sessions
+  inherit them.
+
+Full feature reference + walkthrough:
+[main repo README](https://github.com/marmutapp/superbased-observer).
+
+## How the npm package works
+
+This package is a thin Node.js shim that locates the right pre-built
+binary (shipped via `optionalDependencies`) and spawns it. Same shape
+as `esbuild` / `swc` / `@biomejs/biome`. No postinstall network calls,
+no compile step at install time.
+
+## License
+
+Apache 2.0 — see
+[LICENSE](https://github.com/marmutapp/superbased-observer/blob/main/LICENSE).

package/bin/observer.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// @superbased/observer — Node shim that locates the platform-specific
+// binary shipped via an optional dependency and spawns it with
+// arguments, stdio, and exit code forwarded.
+//
+// Why this shape: each per-platform binary is published as its own
+// optional npm package (`@superbased/observer-<platform>-<arch>`) tagged
+// with `os` and `cpu` in its package.json. npm only installs the one
+// that matches the user's machine, so installs are fast and small.
+// Same pattern used by esbuild, swc, biome.
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+const PLATFORM_PACKAGES = {
+  'linux-x64': '@superbased/observer-linux-x64',
+  'linux-arm64': '@superbased/observer-linux-arm64',
+  'darwin-x64': '@superbased/observer-darwin-x64',
+  'darwin-arm64': '@superbased/observer-darwin-arm64',
+  'win32-x64': '@superbased/observer-win32-x64',
+};
+
+function reportUnsupported(key) {
+  process.stderr.write(
+    '@superbased/observer: no prebuilt binary for ' + key + '.\n' +
+    'Supported: ' + Object.keys(PLATFORM_PACKAGES).join(', ') + '.\n' +
+    'If you need a different platform, file an issue at\n' +
+    '  https://github.com/marmutapp/superbased-observer/issues\n'
+  );
+  process.exit(1);
+}
+
+function reportMissingPackage(pkg) {
+  process.stderr.write(
+    '@superbased/observer: optional dependency ' + pkg + ' is not installed.\n' +
+    'This usually means npm skipped optional dependencies during install.\n' +
+    'Retry with:\n' +
+    '  npm install --include=optional @superbased/observer\n' +
+    'or, if installed globally:\n' +
+    '  npm install -g --include=optional @superbased/observer\n'
+  );
+  process.exit(1);
+}
+
+function resolveBinary() {
+  const key = process.platform + '-' + process.arch;
+  const pkg = PLATFORM_PACKAGES[key];
+  if (!pkg) reportUnsupported(key);
+
+  // Node's resolver looks in node_modules of the calling package +
+  // ancestors. Both the global-install and local-install layouts work
+  // because the optional dep lives next to (or one level up from) this
+  // shim's containing package.
+  const exe = process.platform === 'win32' ? 'observer.exe' : 'observer';
+  let resolved;
+  try {
+    resolved = require.resolve(pkg + '/bin/' + exe);
+  } catch (err) {
+    reportMissingPackage(pkg);
+  }
+  return resolved;
+}
+
+function main() {
+  const binary = resolveBinary();
+  const child = spawn(binary, process.argv.slice(2), {
+    stdio: 'inherit',
+    windowsHide: true,
+  });
+  child.on('error', (err) => {
+    process.stderr.write('@superbased/observer: failed to spawn ' + binary + '\n' + err.message + '\n');
+    process.exit(127);
+  });
+  // Forward signals so Ctrl-C / SIGTERM reach the underlying observer
+  // (long-running daemons rely on graceful shutdown).
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(sig, () => {
+      if (!child.killed) child.kill(sig);
+    });
+  }
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      // Re-raise the same signal on this process so the parent shell
+      // sees the standard exit-by-signal status.
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code === null ? 0 : code);
+    }
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@superbased/observer",
+  "version": "1.3.0",
+  "description": "SuperBased Observer — capture, normalize, compress, and analyze AI coding tool activity across Claude Code, Codex, Cursor, Cline/Roo, and Copilot.",
+  "keywords": [
+    "ai",
+    "observability",
+    "anthropic",
+    "openai",
+    "claude-code",
+    "codex",
+    "cursor",
+    "mcp",
+    "tokens",
+    "cost"
+  ],
+  "homepage": "https://github.com/marmutapp/superbased-observer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marmutapp/superbased-observer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marmutapp/superbased-observer/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Santosh Kathira <contact@marmut.app>",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "observer": "bin/observer.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "optionalDependencies": {
+    "@superbased/observer-linux-x64": "1.3.0",
+    "@superbased/observer-linux-arm64": "1.3.0",
+    "@superbased/observer-darwin-x64": "1.3.0",
+    "@superbased/observer-darwin-arm64": "1.3.0",
+    "@superbased/observer-win32-x64": "1.3.0"
+  },
+  "scripts": {
+    "test": "node bin/observer.js --version"
+  }
+}