@traz-dev/traz 0.1.0

package/.gitignore

@@ -0,0 +1,2 @@
+/node_modules
+

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to `traz` will be documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [Unreleased]
+
+### Added
+- `traz recap` command: Summarize recent events from a given timeframe for morning standups and AI context syncing.
+- Interactive guided onboarding: First-time users get a friendly setup wizard with `dialoguer` menus.
+- Antigravity (agy) MCP integration: `traz setup agy` and documented in `MCP_INTEGRATION.md`.
+
+### Changed
+- `traz init` now automatically creates a `.traz/` local directory and adds it to `.gitignore` without needing the `--local` flag.
+- Interactive REPL mode: Returning users see a clean prompt instead of a large ASCII banner.
+- MCP server command simplified from `traz mcp serve` to `traz mcp` across all docs.
+
+### Fixed
+- CI: Fixed `cargo fmt` formatting failures.
+- CI: Fixed flaky semantic search snapshot tests in CI environments where embedding generation fails.
+- Documentation: Corrected `traz mcp serve` → `traz mcp` references across `README.md` and `MCP_INTEGRATION.md`.
+
+---
+
+## [0.1.0] — 2026-06-06
+
+### Added
+- Local-first engineering memory layer backed by SQLite.
+- `traz recent`, `traz search`, `traz timeline`, `traz context` — core read commands.
+- `traz add`, `traz log`, `traz capture` — event ingestion commands.
+- `traz mcp` — MCP stdio server for Claude Code, Cursor, Gemini CLI, Aider, Warp, and Antigravity.
+- `traz init` — project setup with optional git hook integration.
+- `traz tui` — ratatui-based terminal UI dashboard.
+- `traz doctor` — installation diagnostic tool.
+- `traz status` — system health overview.
+- `traz setup <tool>` — step-by-step integration guides for popular AI tools.
+- Semantic search with local ONNX embeddings (all-MiniLM-L6-v2 via fastembed-rs).
+- Dense AI-optimized output format (`--dense` flag) reducing MCP token payloads by 60–75%.
+- Session checkpointing via `traz checkpoint` for safe context-window resets.
+- Git hook integration for automatic event capture on commit/push/checkout.
+- Shell failure tracking hooks for zsh and bash.
+- Cross-platform release binaries: Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mithilgirish
+
+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

@@ -0,0 +1,354 @@
+<p align="center">
+  <img width="800" alt="traz" src="https://github.com/user-attachments/assets/f4b969a0-b23e-400b-a012-38f05e20973b" />
+</p>
+
+<p align="center">
+  <strong>Trace. Context. Continuity.</strong><br/>
+  <sub>A local-first engineering memory layer and MCP server that provides AI coding tools with a shared, persistent context architecture.</sub>
+</p>
+
+<p align="center">
+  <a href="https://github.com/mithilgirish/traz/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  
+  <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP compatible" />
+  <img src="https://img.shields.io/badge/SQLite-Local_First-purple" alt="SQLite" />
+  <a href="https://traz.mithilgirish.dev"><img src="https://img.shields.io/badge/docs-traz.mithilgirish.dev-6366f1" alt="Documentation" /></a>
+</p>
+
+---
+
+## Table of Contents
+- [Overview](#overview)
+- [The Context Fragmentation Problem](#the-context-fragmentation-problem)
+- [Core Architecture & Design](#core-architecture--design)
+- [Installation Guide](#installation-guide)
+- [Initialization & Configuration](#initialization--configuration)
+- [Command Line Interface Reference](#command-line-interface-reference)
+  - [Ingestion Commands](#ingestion-commands)
+  - [Exploration Commands](#exploration-commands)
+  - [Maintenance Commands](#maintenance-commands)
+- [Terminal User Interface (TUI)](#terminal-user-interface-tui)
+- [Agent Integration (MCP)](#agent-integration-mcp)
+  - [Supported AI Environments](#supported-ai-environments)
+  - [Manual MCP Configuration](#manual-mcp-configuration)
+- [Advanced Subsystems](#advanced-subsystems)
+  - [Semantic Vector Search](#semantic-vector-search)
+  - [Context Window Compression (Dense Format)](#context-window-compression-dense-format)
+- [Security & Privacy](#security--privacy)
+- [Troubleshooting & FAQ](#troubleshooting--faq)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Overview
+
+`traz` is a local-first engineering memory layer designed specifically for AI-augmented development. 
+
+By capturing debugging history, architectural decisions, file modifications, and workflow traces as you code, `traz` establishes a highly searchable, persistent context timeline. This timeline is securely stored in a local SQLite vector database and automatically exposed via the **Model Context Protocol (MCP)**. This enables any compatible AI agent (Claude Code, Cursor, Aider, Gemini CLI, OpenAI Codex) to instantly synchronize context without manual developer intervention or copy-pasting.
+
+## The Context Fragmentation Problem
+
+Modern software development increasingly relies on multiple, specialized AI agents. A standard workflow might involve:
+1. Triaging a stack trace in Claude Code.
+2. Refactoring a dense component within Cursor IDE.
+3. Generating unit tests via a terminal agent like Aider or Antigravity.
+
+At every tool boundary, context is lost. The AI in the IDE does not inherently know what the AI in the terminal just fixed. Every new session starts as an isolated environment, forcing developers to manually rebuild the context window.
+
+`traz` resolves this by acting as a persistent context plane. It ensures that subsequent AI sessions—regardless of the tool—inherit the context of previous decisions, mitigating context loss, reducing LLM token duplication, and preventing regression of thought.
+
+## Core Architecture & Design
+
+The `traz` architecture is built upon three primary pillars:
+
+1. **Local Timeline Engine (SQLite):** A zero-dependency, local-first storage mechanism. It tracks event schemas across sessions, ensuring that proprietary source code and architectural context never leave the local machine. There are no cloud accounts, no sync delays, and no vendor lock-in.
+2. **Hybrid Vector Search:** Leverages the `fastembed-rs` library to execute ONNX-accelerated embedding generation locally. It implements Reciprocal Rank Fusion (RRF) to intelligently merge exact keyword matches (FTS5) with semantic vector similarity, ensuring high-fidelity context retrieval even when vocabulary drifts.
+3. **MCP Server Integration:** Implements the open Model Context Protocol to serve context transparently to supported AI agents. By utilizing an engineered "Dense Output Format," it compresses context payload sizes by up to 75%, preserving valuable context window capacity for the LLM's actual reasoning process.
+
+```mermaid
+graph TD
+    A[Claude Code] -->|stdio / MCP| C(traz MCP Server)
+    B[Cursor IDE] -->|stdio / MCP| C
+    D[CLI / Shell Hooks] -->|Commands| C
+    C --> E[(SQLite Vector DB)]
+    C --> F[fastembed-rs ONNX]
+    E --> G[Timeline Engine]
+```
+
+For an in-depth review of the underlying schema, migration logic, and RRF mathematics, please refer to the [Architecture Documentation](./docs/ARCHITECTURE.md).
+
+## Installation Guide
+
+Select your preferred installation method:
+
+### 1. Via NPM (Cross-Platform)
+```bash
+npm install -g @traz-dev/traz
+```
+
+### 2. Via Homebrew (macOS & Linux)
+```bash
+brew tap mithilgirish/traz
+brew install traz
+```
+
+### 3. Standalone Installers (No dependencies required)
+* **macOS & Linux (Shell):**
+  ```bash
+  curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mithilgirish/traz/releases/latest/download/traz-installer.sh | sh
+  ```
+* **Windows (PowerShell):**
+  ```powershell
+  irm https://github.com/mithilgirish/traz/releases/latest/download/traz-installer.ps1 | iex
+  ```
+
+### 4. Via Cargo (Build from source)
+Requires the Rust toolchain (v1.75.0 or higher):
+```bash
+cargo install --git https://github.com/mithilgirish/traz.git traz
+```
+
+### Build from Source manually
+For contributors or users requiring specific branch deployments:
+```bash
+git clone https://github.com/mithilgirish/traz.git
+cd traz
+cargo build --release
+
+# Optional: Add to PATH systematically
+sudo cp target/release/traz /usr/local/bin/
+```
+
+### Verification
+Ensure the binary is correctly linked and the embedding model engine is accessible.
+```bash
+traz doctor
+```
+
+## Initialization & Configuration
+
+Initialize `traz` within your repository to establish the local timeline directory (`.traz/`). This directory acts as the nexus for your project's history.
+
+```bash
+cd your-project
+traz init
+```
+
+Running `traz init` performs the following automated steps:
+1. Creates the `.traz/` local directory.
+2. Initializes the SQLite schema (`traz.db`) and vector index.
+3. Automatically appends `.traz/` to your `.gitignore` to prevent committing the database to remote version control.
+
+## Command Line Interface Reference
+
+The CLI is designed to be highly composable, scriptable for CI/CD integration, and readable for daily workflow monitoring.
+
+### Ingestion Commands
+
+**Log Manual Context:**
+Append a manual note, architectural decision, or debugging trace directly to the timeline.
+```bash
+traz log "traced root cause of memory leak to unbounded queue growth in the worker pool"
+```
+
+**Add Structured Events:**
+Useful for shell aliases or git hooks.
+```bash
+traz add --tool cursor --event-type bug_fix --title "Fixed auth race condition"
+```
+
+### Exploration Commands
+
+**View Recent Activity:**
+Fetch a chronological list of the most recent events across all tools.
+```bash
+$ traz recent --limit 5
+
+[claude-code · 2h ago] fixed websocket reconnect issue
+[cursor · 5h ago] updated auth middleware
+[warp · 1d ago] traced memory leak in queue worker
+[aider · 2d ago] reverted broken cache optimization
+```
+
+**Search Engineering History:**
+Perform keyword searches against the timeline.
+```bash
+$ traz search auth
+
+[2d ago] claude-code
+Fixed JWT refresh race condition
+
+[5h ago] cursor
+Updated auth middleware retry logic
+```
+
+**View Workflow Timeline:**
+Render a bulleted workflow trace of operations, useful for generating PR descriptions or commit summaries.
+```bash
+$ traz timeline
+
+• created websocket handler
+• debugged reconnect issue
+• added retry backoff
+• verified with local tests
+```
+
+**Time-Bounded AI Recap:**
+Generate a time-bounded summary, commonly used for daily standups or morning synchronization.
+```bash
+$ traz recap --hours 24
+```
+
+### Maintenance Commands
+
+**Context Checkpointing:**
+Save a named snapshot of the current state. Useful when switching branches or finalizing a massive refactor.
+```bash
+traz checkpoint --message "completed auth migration"
+```
+
+**Backfill Embeddings:**
+Generate missing vector embeddings for older events ingested prior to vector support or during offline periods.
+```bash
+traz backfill-embeddings
+```
+
+## Terminal User Interface (TUI)
+
+For an interactive, visually structured view of the repository's history and AI traces, `traz` ships with a native TUI.
+
+```bash
+traz tui
+```
+
+The TUI provides:
+- Split-pane navigation of historical checkpoints.
+- Interactive filtering by AI tool, event type, or timestamp.
+- Detailed inspection of specific debug logs or diffs associated with an event.
+
+## Agent Integration (MCP)
+
+`traz` acts as an MCP stdio server. It features auto-detecting setup workflows to register itself across major AI tools effortlessly.
+
+### Supported AI Environments
+
+Run the setup command corresponding to your primary tool. The wizard will automatically locate the tool's configuration file and inject the necessary MCP routing logic.
+
+```bash
+traz setup claude   # Configures Claude Code
+traz setup cursor   # Modifies ~/.cursor/mcp.json
+traz setup opencode # Configures OpenCode
+traz setup codex    # Configures OpenAI Codex CLI
+traz setup gemini   # Configures Gemini CLI
+traz setup agy      # Configures Antigravity CLI
+```
+
+### Manual MCP Configuration
+
+For tools not supported by the interactive wizard (such as Aider or custom agents), configure your agent to execute `traz` with the `mcp` subcommand.
+
+**Example `mcp.json` structure:**
+```json
+{
+  "mcpServers": {
+    "traz": {
+      "command": "traz",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Once configured, the AI tool will automatically query the `traz` server on initialization, retrieve the latest checkpoints, and restore context natively. For further details, refer to the [Agent Integration Guide](./docs/AGENT_INTEGRATION.md).
+
+## Advanced Subsystems
+
+### Semantic Vector Search
+
+By default, `traz` generates local embeddings for all ingested events using an ONNX-accelerated MiniLM model (`fastembed-rs`). This enables semantic retrieval, allowing you to find contextually relevant history even when exact keywords are omitted.
+
+```bash
+$ traz search "database connection pooling"
+
+[semantic search] Search: "database connection pooling" (2 results)
+─────────────────────────────────────────────
+ 1. Added pg_bouncer for connections (72%)
+    Tool: cursor       Type: commit     Age: 3d ago     Tags: #db
+
+ 2. Re-architected connection lifecycle (64%)
+    Tool: gemini       Type: refactor   Age: 1w ago     Tags: #db #performance
+```
+
+### Context Window Compression (Dense Format)
+
+Long-running projects accumulate extensive, verbose timelines. Standard JSON serialization of this data rapidly depletes an LLM's context window.
+
+`traz` implements a `--dense` formatting protocol over MCP. Instead of passing nested JSON arrays to the agent, the server parses the historical data into an ultra-compact plaintext format, stripping redundant schema keys and whitespace. This methodology consistently compresses context payload sizes by **60% to 75%**.
+
+## Security & Privacy
+
+Security is foundational to `traz`. 
+- **Zero Telemetry:** The CLI binary contains no telemetry, analytics, or remote tracking systems.
+- **Local Isolation:** The SQLite database is stored locally in your project folder (`.traz/traz.db`) and is strictly `.gitignore`d. No data is transmitted to an external server.
+- **Embedding Generation:** Semantic vector generation runs completely on-device using ONNX execution providers. Your proprietary commit messages and architecture plans are never sent to external embedding APIs.
+
+## Troubleshooting & FAQ
+
+**Q: `traz setup cursor` fails to detect my configuration.**
+A: Ensure you have initialized Cursor at least once so the `~/.cursor` configuration directory exists. You can manually append the JSON block defined in the Manual MCP Configuration section.
+
+**Q: Semantic search is returning errors or panicking in CI environments.**
+A: In headless CI environments missing certain runtime libraries, `fastembed-rs` may fail to generate embeddings. Set the `TRAZ_DISABLE_EMBEDDINGS=1` environment variable during automated testing to bypass vector generation.
+
+**Q: How do I clear my context timeline?**
+A: You can purge the local memory by simply deleting the database file: `rm -rf .traz/`. Re-run `traz init` to start fresh.
+
+## Roadmap
+
+**v0.1 (Current)**
+- [x] Local timeline storage (SQLite)
+- [x] CLI commands (recent, search, timeline, log, recap)
+- [x] Context and history retrieval system
+- [x] Native MCP server implementation
+- [x] Automatic git hook integrations
+- [x] Interactive Tool Setup Adapters
+- [x] Semantic search via local ONNX embeddings
+- [x] Terminal UI (TUI) Dashboard
+- [x] Token-optimized Dense output formats
+- [x] Workflow Checkpoints
+
+**Future Proposals**
+- [ ] VSCode and JetBrains native extensions
+- [ ] Network-level team synchronization (Opt-in)
+- [ ] Advanced Graph visualizations
+
+## Contributing
+
+We welcome contributions from the community. If you plan to introduce significant architectural changes or core database migrations, please open an issue first to discuss the proposed design.
+
+### Development Workflow
+```bash
+# Clone the repository
+git clone https://github.com/mithilgirish/traz.git
+cd traz
+
+# Run test suite
+cargo test
+
+# Ensure formatting and linting pass
+cargo fmt --all -- --check
+cargo clippy -- -D warnings
+```
+
+Please review the [CONTRIBUTING.md](./CONTRIBUTING.md) for strict code style guidelines and testing protocols prior to submitting Pull Requests.
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE). All contributions are subject to these licensing terms.
+
+---
+<p align="center">
+  <sub>Built for developers who switch tools, not context.</sub>
+</p>

package/binary-install.js

@@ -0,0 +1,348 @@
+const {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  mkdtemp,
+  rmSync,
+} = require("fs");
+const { join, sep } = require("path");
+const { spawnSync } = require("child_process");
+const { tmpdir } = require("os");
+
+const https = require("node:https");
+const http = require("node:http");
+
+const tmpDir = tmpdir();
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+function getProxyForUrl(urlString) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy || "";
+  if (noProxy === "*") return null;
+  if (noProxy) {
+    const hostname = url.hostname.toLowerCase();
+    const noProxyList = noProxy.split(",").map((s) => s.trim().toLowerCase());
+    for (const entry of noProxyList) {
+      if (hostname === entry || hostname.endsWith("." + entry)) {
+        return null;
+      }
+    }
+  }
+
+  const proxyEnv = isHttps
+    ? process.env.HTTPS_PROXY || process.env.https_proxy
+    : process.env.HTTP_PROXY || process.env.http_proxy;
+
+  if (!proxyEnv) return null;
+
+  const proxyUrl = new URL(proxyEnv);
+
+  let auth = null;
+  if (proxyUrl.username || proxyUrl.password) {
+    auth = `${proxyUrl.username}:${proxyUrl.password}`;
+  }
+
+  return {
+    hostname: proxyUrl.hostname,
+    port: proxyUrl.port || (proxyUrl.protocol === "https:" ? 443 : 80),
+    auth: auth,
+  };
+}
+
+function connectThroughProxy(proxy, target) {
+  return new Promise((resolve, reject) => {
+    const headers = {};
+    if (proxy.auth) {
+      headers["Proxy-Authorization"] =
+        "Basic " + Buffer.from(proxy.auth).toString("base64");
+    }
+
+    const connectReq = http.request({
+      hostname: proxy.hostname,
+      port: proxy.port,
+      method: "CONNECT",
+      path: `${target.hostname}:${target.port || 443}`,
+      headers,
+    });
+    connectReq.on("connect", (res, socket) => {
+      if (res.statusCode === 200) {
+        resolve(socket);
+      } else {
+        reject(new Error(`Proxy CONNECT failed with status ${res.statusCode}`));
+      }
+    });
+    connectReq.on("error", reject);
+    connectReq.end();
+  });
+}
+
+function download(urlString, maxRedirects) {
+  if (maxRedirects === undefined) maxRedirects = 5;
+  return new Promise((resolve, reject) => {
+    if (maxRedirects < 0) {
+      return reject(new Error("Too many redirects"));
+    }
+
+    const parsed = new URL(urlString);
+    const isHttps = parsed.protocol === "https:";
+    const mod = isHttps ? https : http;
+    const proxy = getProxyForUrl(urlString);
+
+    const doRequest = (extraOptions) => {
+      const options = Object.assign(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || (isHttps ? 443 : 80),
+          path: parsed.pathname + parsed.search,
+          method: "GET",
+          headers: { "User-Agent": "cargo-dist-npm-installer" },
+        },
+        extraOptions || {},
+      );
+
+      if (proxy && !isHttps) {
+        // HTTP through HTTP proxy: request the full URL via the proxy
+        options.hostname = proxy.hostname;
+        options.port = proxy.port;
+        options.path = urlString;
+        if (proxy.auth) {
+          options.headers["Proxy-Authorization"] =
+            "Basic " + Buffer.from(proxy.auth).toString("base64");
+        }
+      }
+
+      const req = mod.request(options, (res) => {
+        if (
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          res.resume();
+          const nextUrl = new URL(res.headers.location, urlString).toString();
+          return download(nextUrl, maxRedirects - 1).then(resolve, reject);
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} from ${urlString}`));
+        }
+        resolve(res);
+      });
+      req.on("error", reject);
+      req.end();
+    };
+
+    if (proxy && isHttps) {
+      connectThroughProxy(proxy, parsed).then(
+        (socket) => doRequest({ socket, agent: false }),
+        reject,
+      );
+    } else {
+      doRequest();
+    }
+  });
+}
+
+class Package {
+  constructor(platform, name, url, filename, zipExt, binaries) {
+    let errors = [];
+    if (typeof url !== "string") {
+      errors.push("url must be a string");
+    } else {
+      try {
+        new URL(url);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    if (name && typeof name !== "string") {
+      errors.push("package name must be a string");
+    }
+    if (!name) {
+      errors.push("You must specify the name of your package");
+    }
+    if (binaries && typeof binaries !== "object") {
+      errors.push("binaries must be a string => string map");
+    }
+    if (!binaries) {
+      errors.push("You must specify the binaries in the package");
+    }
+
+    if (errors.length > 0) {
+      let errorMsg =
+        "One or more of the parameters you passed to the Binary constructor are invalid:\n";
+      errors.forEach((error) => {
+        errorMsg += error;
+      });
+      errorMsg +=
+        '\n\nCorrect usage: new Package("my-binary", "https://example.com/binary/download.tar.gz", {"my-binary": "my-binary"})';
+      error(errorMsg);
+    }
+
+    this.platform = platform;
+    this.url = url;
+    this.name = name;
+    this.filename = filename;
+    this.zipExt = zipExt;
+    this.installDirectory = join(__dirname, "node_modules", ".bin_real");
+    this.binaries = binaries;
+
+    if (!existsSync(this.installDirectory)) {
+      mkdirSync(this.installDirectory, { recursive: true });
+    }
+  }
+
+  exists() {
+    for (const binaryName in this.binaries) {
+      const binRelPath = this.binaries[binaryName];
+      const binPath = join(this.installDirectory, binRelPath);
+      if (!existsSync(binPath)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  install(suppressLogs = false) {
+    if (this.exists()) {
+      if (!suppressLogs) {
+        console.error(
+          `${this.name} is already installed, skipping installation.`,
+        );
+      }
+      return Promise.resolve();
+    }
+
+    try {
+      rmSync(this.installDirectory, { recursive: true, force: true });
+    } catch {
+      // ignore - directory may not exist
+    }
+
+    mkdirSync(this.installDirectory, { recursive: true });
+
+    if (!suppressLogs) {
+      console.error(`Downloading release from ${this.url}`);
+    }
+
+    return download(this.url)
+      .then((res) => {
+        return new Promise((resolve, reject) => {
+          mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
+            if (err) return reject(err);
+            let tempFile = join(directory, this.filename);
+            const sink = res.pipe(createWriteStream(tempFile));
+            sink.on("error", (err) => reject(err));
+            sink.on("close", () => {
+              if (/\.tar\.*/.test(this.zipExt)) {
+                const result = spawnSync("tar", [
+                  "xf",
+                  tempFile,
+                  // The tarballs are stored with a leading directory
+                  // component; we strip one component in the
+                  // shell installers too.
+                  "--strip-components",
+                  "1",
+                  "-C",
+                  this.installDirectory,
+                ]);
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred untarring the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else if (this.zipExt == ".zip") {
+                let result;
+                if (this.platform.artifactName.includes("windows")) {
+                  // Windows does not have "unzip" by default on many installations, instead
+                  // we use Expand-Archive from powershell
+                  result = spawnSync("powershell.exe", [
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-Command",
+                    `& {
+                        param([string]$LiteralPath, [string]$DestinationPath)
+                        Expand-Archive -LiteralPath $LiteralPath -DestinationPath $DestinationPath -Force
+                    }`,
+                    tempFile,
+                    this.installDirectory,
+                  ]);
+                } else {
+                  result = spawnSync("unzip", [
+                    "-q",
+                    tempFile,
+                    "-d",
+                    this.installDirectory,
+                  ]);
+                }
+
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred unzipping the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else {
+                reject(
+                  new Error(`Unrecognized file extension: ${this.zipExt}`),
+                );
+              }
+            });
+          });
+        });
+      })
+      .then(() => {
+        if (!suppressLogs) {
+          console.error(`${this.name} has been installed!`);
+        }
+      })
+      .catch((e) => {
+        error(`Error fetching release: ${e.message}`);
+      });
+  }
+
+  run(binaryName) {
+    const promise = !this.exists() ? this.install(true) : Promise.resolve();
+
+    promise
+      .then(() => {
+        const [, , ...args] = process.argv;
+
+        const options = { cwd: process.cwd(), stdio: "inherit" };
+
+        const binRelPath = this.binaries[binaryName];
+        if (!binRelPath) {
+          error(`${binaryName} is not a known binary in ${this.name}`);
+        }
+        const binPath = join(this.installDirectory, binRelPath);
+        const result = spawnSync(binPath, args, options);
+
+        if (result.error) {
+          error(result.error);
+        }
+
+        process.exit(result.status);
+      })
+      .catch((e) => {
+        error(e.message);
+      });
+  }
+}
+
+module.exports.Package = Package;

package/binary.js

@@ -0,0 +1,124 @@
+const { Package } = require("./binary-install");
+const os = require("os");
+const libc = require("detect-libc");
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+const {
+  name,
+  artifactDownloadUrls,
+  supportedPlatforms,
+  glibcMinimum,
+} = require("./package.json");
+
+// FIXME: implement NPM installer handling of fallback download URLs
+const artifactDownloadUrl = artifactDownloadUrls[0];
+const builderGlibcMajorVersion = glibcMinimum.major;
+const builderGlibcMinorVersion = glibcMinimum.series;
+
+const getPlatform = () => {
+  const rawOsType = os.type();
+  const rawArchitecture = os.arch();
+
+  // We want to use rust-style target triples as the canonical key
+  // for a platform, so translate the "os" library's concepts into rust ones
+  let osType = "";
+  switch (rawOsType) {
+    case "Windows_NT":
+      osType = "pc-windows-msvc";
+      break;
+    case "Darwin":
+      osType = "apple-darwin";
+      break;
+    case "Linux":
+      osType = "unknown-linux-gnu";
+      break;
+  }
+
+  let arch = "";
+  switch (rawArchitecture) {
+    case "x64":
+      arch = "x86_64";
+      break;
+    case "arm64":
+      arch = "aarch64";
+      break;
+  }
+
+  if (rawOsType === "Linux") {
+    if (libc.familySync() == "musl") {
+      osType = "unknown-linux-musl-dynamic";
+    } else if (libc.isNonGlibcLinuxSync()) {
+      console.warn(
+        "Your libc is neither glibc nor musl; trying static musl binary instead",
+      );
+      osType = "unknown-linux-musl-static";
+    } else {
+      let libcVersion = libc.versionSync();
+      let splitLibcVersion = libcVersion.split(".");
+      let libcMajorVersion = splitLibcVersion[0];
+      let libcMinorVersion = splitLibcVersion[1];
+      if (
+        libcMajorVersion != builderGlibcMajorVersion ||
+        libcMinorVersion < builderGlibcMinorVersion
+      ) {
+        // We can't run the glibc binaries, but we can run the static musl ones
+        // if they exist
+        console.warn(
+          "Your glibc isn't compatible; trying static musl binary instead",
+        );
+        osType = "unknown-linux-musl-static";
+      }
+    }
+  }
+
+  // Assume the above succeeded and build a target triple to look things up with.
+  // If any of it failed, this lookup will fail and we'll handle it like normal.
+  let targetTriple = `${arch}-${osType}`;
+  let platform = supportedPlatforms[targetTriple];
+
+  if (!platform) {
+    error(
+      `Platform with type "${rawOsType}" and architecture "${rawArchitecture}" is not supported by ${name}.\nYour system must be one of the following:\n\n${Object.keys(
+        supportedPlatforms,
+      ).join(",")}`,
+    );
+  }
+
+  return platform;
+};
+
+const getPackage = () => {
+  const platform = getPlatform();
+  const url = `${artifactDownloadUrl}/${platform.artifactName}`;
+  let filename = platform.artifactName;
+  let ext = platform.zipExt;
+  let binary = new Package(platform, name, url, filename, ext, platform.bins);
+
+  return binary;
+};
+
+const install = (suppressLogs) => {
+  if (!artifactDownloadUrl || artifactDownloadUrl.length === 0) {
+    console.warn("in demo mode, not installing binaries");
+    return;
+  }
+  const pkg = getPackage();
+
+  return pkg.install(suppressLogs);
+};
+
+const run = (binaryName) => {
+  const pkg = getPackage();
+
+  pkg.run(binaryName);
+};
+
+module.exports = {
+  install,
+  run,
+  getPackage,
+};

package/install.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { install } = require("./binary");
+install(false);

package/npm-shrinkwrap.json

@@ -0,0 +1,52 @@
+{
+  "lockfileVersion": 3,
+  "name": "@traz-dev/traz",
+  "packages": {
+    "": {
+      "bin": {
+        "traz": "run-traz.js"
+      },
+      "dependencies": {
+        "detect-libc": "^2.1.2"
+      },
+      "devDependencies": {
+        "prettier": "^3.8.3"
+      },
+      "engines": {
+        "node": ">=14.14",
+        "npm": ">=6"
+      },
+      "hasInstallScript": true,
+      "license": "MIT",
+      "name": "@traz-dev/traz",
+      "version": "0.1.0"
+    },
+    "node_modules/detect-libc": {
+      "engines": {
+        "node": ">=8"
+      },
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "version": "2.1.2"
+    },
+    "node_modules/prettier": {
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "dev": true,
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      },
+      "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==",
+      "license": "MIT",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz",
+      "version": "3.8.3"
+    }
+  },
+  "requires": true,
+  "version": "0.1.0"
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "artifactDownloadUrls": [
+    "https://github.com/mithilgirish/traz/releases/download/v0.1.0"
+  ],
+  "author": "Mithil Girish",
+  "bin": {
+    "traz": "run-traz.js"
+  },
+  "dependencies": {
+    "detect-libc": "^2.1.2"
+  },
+  "description": "A local-first engineering memory layer and MCP server for AI coding tools",
+  "devDependencies": {
+    "prettier": "^3.8.3"
+  },
+  "engines": {
+    "node": ">=14.14",
+    "npm": ">=6"
+  },
+  "glibcMinimum": {
+    "major": 2,
+    "series": 39
+  },
+  "homepage": "https://traz.mithilgirish.dev",
+  "keywords": [
+    "development-tools",
+    "command-line-utilities",
+    "mcp",
+    "ai",
+    "claude",
+    "llm",
+    "context"
+  ],
+  "license": "MIT",
+  "name": "@traz-dev/traz",
+  "preferUnplugged": true,
+  "repository": "https://github.com/mithilgirish/traz",
+  "scripts": {
+    "fmt": "prettier --write **/*.js",
+    "fmt:check": "prettier --check **/*.js",
+    "postinstall": "node ./install.js"
+  },
+  "supportedPlatforms": {
+    "aarch64-apple-darwin": {
+      "artifactName": "traz-aarch64-apple-darwin.tar.xz",
+      "bins": {
+        "traz": "traz"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-pc-windows-msvc": {
+      "artifactName": "traz-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "traz": "traz.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "aarch64-unknown-linux-gnu": {
+      "artifactName": "traz-aarch64-unknown-linux-gnu.tar.xz",
+      "bins": {
+        "traz": "traz"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-pc-windows-gnu": {
+      "artifactName": "traz-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "traz": "traz.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "x86_64-pc-windows-msvc": {
+      "artifactName": "traz-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "traz": "traz.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "x86_64-unknown-linux-gnu": {
+      "artifactName": "traz-x86_64-unknown-linux-gnu.tar.xz",
+      "bins": {
+        "traz": "traz"
+      },
+      "zipExt": ".tar.xz"
+    }
+  },
+  "version": "0.1.0",
+  "volta": {
+    "node": "18.14.1",
+    "npm": "9.5.0"
+  }
+}

package/run-traz.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { run } = require("./binary");
+run("traz");