claudetracer 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# Tracer — Agent Replay & Diff Memory
+
+Tracer is a missing infrastructure layer for AI coding agents.
+
+Agents repeat the same mistakes across sessions because they have no memory 
+of what they tried, what failed, and what the correct action was.
+Tracer closes that loop.
+
+## How it works
+
+1. **Records** every action an agent takes during a session (reads, writes, commands)
+2. **Diffs** what the agent wrote against what the developer actually committed to git
+3. **Surfaces** deviations in a dashboard where developers annotate corrections
+4. **Injects** those corrections as context before the next session starts
+
+The agent never makes the same mistake twice.
+
+## Stack
+
+- MCP server (Node.js + TypeScript) — intercepts Claude Code tool calls
+- Supabase — stores sessions, diffs, corrections
+- Next.js dashboard — view deviations, publish corrections
+
+## Setup
+
+### 1. Install dependencies
+cd agent-tracer && npm install
+
+### 2. Add Supabase credentials to .env
+SUPABASE_URL=your_url
+SUPABASE_ANON_KEY=your_key
+
+### 3. Register as MCP server in ~/.claude.json
+Add tracer to your mcpServers config pointing to src/server/index.ts
+
+### 4. Run the dashboard
+cd tracer-dashboard && npm run dev
+
+## MCP Tools
+
+| Tool | What it does |
+|------|-------------|
+| `get_context` | Returns past corrections before a session starts |
+| `read_file` | Reads a file and logs the action |
+| `write_file` | Writes a file and logs the action |
+| `run_command` | Runs a shell command and logs the action |
+| `close_session` | Computes git diff and saves deviations to Supabase |
+
+## Dashboard
+
+Open http://localhost:3000 to:
+- See all recorded sessions
+- View deviations (what the agent wrote vs what was committed)
+- Publish corrections that get injected into the next session
+
+## Why this matters
+
+Nia by Nozomio solves external context — giving agents the right docs to read.
+Tracer solves execution memory — giving agents the right corrections from past runs.
+
+They are complementary layers. Nia tells agents what to read.
+Tracer tells agents what not to do.
+
+## Built by
+
+Nursultan Orynbassar

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+require('child_process').spawnSync(
+  'npx', ['tsx', __dirname + '/cli.ts', ...process.argv.slice(2)],
+  { stdio: 'inherit' }
+);

package/bin/cli.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+const command = process.argv[2];
+
+if (command === "init") {
+  require("./init");
+} else if (command === "dashboard") {
+  require("./dashboard");
+} else {
+  console.log("\nUsage:");
+  console.log("  npx tracerit init       — Set up Tracerit with Claude Code");
+  console.log("  npx tracerit dashboard  — Open the Tracerit dashboard\n");
+}

package/bin/dashboard.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import * as path from "path";
+
+const dashboardPath = path.join(__dirname, "../tracer-dashboard");
+
+console.log("\n🚀 Starting Tracerit Dashboard...\n");
+
+try {
+  execSync("npm run dev", {
+    cwd: dashboardPath,
+    stdio: "inherit",
+  });
+} catch (e) {
+  console.error("Dashboard failed to start. Make sure tracer-dashboard is set up.");
+}

package/bin/init.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import * as readline from "readline";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const ask = (question: string): Promise<string> =>
+  new Promise((resolve) => rl.question(question, resolve));
+
+async function main() {
+  console.log("\n🔍 Tracerit — Agent Memory for Claude Code\n");
+
+  const supabaseUrl = await ask("Enter your Supabase URL: ");
+  const supabaseKey = await ask("Enter your Supabase Anon Key: ");
+
+  // Write .env file
+  const envPath = path.join(__dirname, "../.env");
+  fs.writeFileSync(envPath, `SUPABASE_URL=${supabaseUrl}\nSUPABASE_ANON_KEY=${supabaseKey}\n`);
+  console.log("✅ .env file created");
+
+  // Update ~/.claude.json
+  const claudeConfigPath = path.join(os.homedir(), ".claude.json");
+  let claudeConfig: any = {};
+
+  if (fs.existsSync(claudeConfigPath)) {
+    claudeConfig = JSON.parse(fs.readFileSync(claudeConfigPath, "utf-8"));
+  }
+
+  if (!claudeConfig.mcpServers) claudeConfig.mcpServers = {};
+
+  const serverPath = path.join(__dirname, "../src/server/index.ts");
+
+  claudeConfig.mcpServers.tracer = {
+    command: "npx",
+    args: ["tsx", serverPath],
+    env: {
+      SUPABASE_URL: supabaseUrl,
+      SUPABASE_ANON_KEY: supabaseKey,
+    },
+  };
+
+  fs.writeFileSync(claudeConfigPath, JSON.stringify(claudeConfig, null, 2));
+  console.log("✅ Claude Code configured");
+
+  console.log("\n✅ Tracerit is ready! Open Claude Code and start coding.");
+  console.log("👉 Run 'npx tracerit dashboard' to view your sessions.\n");
+
+  rl.close();
+}
+
+main();

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "claudetracer",
+  "version": "1.0.0",
+  "description": "Agent replay and memory for Claude Code",
+  "bin": {
+    "tracerit": "./bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx src/server/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@supabase/supabase-js": "^2.0.0",
+    "dotenv": "^16.0.0",
+    "uuid": "^9.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/app/page.tsx

@@ -0,0 +1,263 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { supabase } from "@/lib/supabase";
+
+// ── TYPES ──
+interface Session {
+  id: string;
+  project_path: string;
+  ended_at: string;
+  created_at: string;
+  deviation_count?: number;
+}
+
+interface Diff {
+  id: number;
+  session_id: string;
+  file_path: string;
+  agent_wrote: string;
+  final_version: string;
+  was_reverted: boolean;
+  lines_added: number;
+  lines_removed: number;
+  computed_at: string;
+}
+
+interface Correction {
+  id: number;
+  session_id: string;
+  file_path: string;
+  note: string;
+  agent_wrote: string;
+  correct_version: string;
+}
+
+export default function Home() {
+  const [sessions, setSessions] = useState<Session[]>([]);
+  const [selectedSession, setSelectedSession] = useState<Session | null>(null);
+  const [diffs, setDiffs] = useState<Diff[]>([]);
+  const [selectedDiff, setSelectedDiff] = useState<Diff | null>(null);
+  const [note, setNote] = useState("");
+  const [correctVersion, setCorrectVersion] = useState("");
+  const [saving, setSaving] = useState(false);
+  const [saved, setSaved] = useState(false);
+  const [loading, setLoading] = useState(true);
+
+  // ── LOAD SESSIONS ──
+  useEffect(() => {
+    async function loadSessions() {
+      const { data } = await supabase
+        .from("sessions")
+        .select("*")
+        .order("created_at", { ascending: false })
+        .limit(20);
+      setSessions(data ?? []);
+      setLoading(false);
+    }
+    loadSessions();
+  }, []);
+
+  // ── LOAD DIFFS FOR SELECTED SESSION ──
+  useEffect(() => {
+    if (!selectedSession) return;
+    async function loadDiffs() {
+      const { data } = await supabase
+        .from("diffs")
+        .select("*")
+        .eq("session_id", selectedSession!.id)
+        .order("computed_at", { ascending: false });
+      setDiffs(data ?? []);
+      setSelectedDiff(null);
+    }
+    loadDiffs();
+  }, [selectedSession]);
+
+  // ── PUBLISH CORRECTION ──
+  async function publishCorrection() {
+    if (!selectedDiff || !note) return;
+    setSaving(true);
+
+    await supabase.from("corrections").insert({
+      session_id: selectedDiff.session_id,
+      action_id: null,
+      file_path: selectedDiff.file_path,
+      agent_wrote: selectedDiff.agent_wrote,
+      correct_version: correctVersion || selectedDiff.final_version,
+      note,
+    });
+
+    setSaving(false);
+    setSaved(true);
+    setNote("");
+    setCorrectVersion("");
+    setTimeout(() => setSaved(false), 2000);
+  }
+
+  return (
+    <div className="min-h-screen bg-gray-50 text-gray-900 font-sans">
+      {/* Header */}
+      <div className="border-b border-gray-200 bg-white px-6 py-4 flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <div className="w-7 h-7 rounded-md bg-teal-500 flex items-center justify-center">
+            <span className="text-white text-xs font-bold">T</span>
+          </div>
+          <span className="font-semibold text-lg">Tracer</span>
+          <span className="text-gray-400 text-sm">Agent Replay & Diff Memory</span>
+        </div>
+        <span className="text-xs text-gray-400">{sessions.length} sessions recorded</span>
+      </div>
+
+      <div className="flex h-[calc(100vh-57px)]">
+
+        {/* ── LEFT: Sessions list ── */}
+        <div className="w-64 border-r border-gray-200 bg-white overflow-y-auto">
+          <div className="px-4 py-3 border-b border-gray-100">
+            <p className="text-xs font-medium text-gray-500 uppercase tracking-wide">Sessions</p>
+          </div>
+          {loading && (
+            <div className="px-4 py-8 text-sm text-gray-400 text-center">Loading...</div>
+          )}
+          {!loading && sessions.length === 0 && (
+            <div className="px-4 py-8 text-sm text-gray-400 text-center">
+              No sessions yet. Run the MCP server and start coding.
+            </div>
+          )}
+          {sessions.map((s) => (
+            <button
+              key={s.id}
+              onClick={() => setSelectedSession(s)}
+              className={`w-full text-left px-4 py-3 border-b border-gray-100 hover:bg-gray-50 transition-colors ${
+                selectedSession?.id === s.id ? "bg-teal-50 border-l-2 border-l-teal-500" : ""
+              }`}
+            >
+              <p className="text-xs font-mono text-gray-500 truncate">{s.id.slice(0, 8)}...</p>
+              <p className="text-xs text-gray-400 mt-0.5 truncate">
+                {s.project_path?.split("/").pop() ?? "unknown project"}
+              </p>
+              <p className="text-xs text-gray-300 mt-0.5">
+                {new Date(s.created_at).toLocaleDateString()}
+              </p>
+            </button>
+          ))}
+        </div>
+
+        {/* ── MIDDLE: Diffs list ── */}
+        <div className="w-72 border-r border-gray-200 bg-white overflow-y-auto">
+          <div className="px-4 py-3 border-b border-gray-100">
+            <p className="text-xs font-medium text-gray-500 uppercase tracking-wide">
+              {selectedSession ? `Deviations (${diffs.length})` : "Select a session"}
+            </p>
+          </div>
+          {selectedSession && diffs.length === 0 && (
+            <div className="px-4 py-8 text-sm text-gray-400 text-center">
+              No deviations found. Agent matched final code.
+            </div>
+          )}
+          {diffs.map((d) => (
+            <button
+              key={d.id}
+              onClick={() => setSelectedDiff(d)}
+              className={`w-full text-left px-4 py-3 border-b border-gray-100 hover:bg-gray-50 transition-colors ${
+                selectedDiff?.id === d.id ? "bg-teal-50 border-l-2 border-l-teal-500" : ""
+              }`}
+            >
+              <div className="flex items-center gap-2 mb-1">
+                {d.was_reverted ? (
+                  <span className="text-xs bg-red-100 text-red-600 px-1.5 py-0.5 rounded">reverted</span>
+                ) : (
+                  <span className="text-xs bg-yellow-100 text-yellow-600 px-1.5 py-0.5 rounded">modified</span>
+                )}
+              </div>
+              <p className="text-xs font-mono text-gray-600 truncate">{d.file_path.split("/").pop()}</p>
+              <p className="text-xs text-gray-400 mt-0.5 truncate">{d.file_path}</p>
+              <p className="text-xs text-gray-300 mt-1">
+                +{d.lines_added} / -{d.lines_removed} lines
+              </p>
+            </button>
+          ))}
+        </div>
+
+        {/* ── RIGHT: Diff detail + correction form ── */}
+        <div className="flex-1 overflow-y-auto bg-gray-50">
+          {!selectedDiff && (
+            <div className="flex items-center justify-center h-full text-sm text-gray-400">
+              Select a deviation to annotate it
+            </div>
+          )}
+          {selectedDiff && (
+            <div className="p-6 space-y-6">
+              {/* File path */}
+              <div>
+                <p className="text-xs text-gray-400 mb-1">File</p>
+                <p className="font-mono text-sm text-gray-700">{selectedDiff.file_path}</p>
+              </div>
+
+              {/* Side by side diff */}
+              <div className="grid grid-cols-2 gap-4">
+                <div>
+                  <p className="text-xs text-gray-400 mb-2">Agent wrote</p>
+                  <pre className="bg-red-50 border border-red-100 rounded-lg p-3 text-xs font-mono text-red-800 overflow-x-auto whitespace-pre-wrap">
+                    {selectedDiff.agent_wrote?.slice(0, 800) ?? "—"}
+                  </pre>
+                </div>
+                <div>
+                  <p className="text-xs text-gray-400 mb-2">Final committed version</p>
+                  <pre className="bg-green-50 border border-green-100 rounded-lg p-3 text-xs font-mono text-green-800 overflow-x-auto whitespace-pre-wrap">
+                    {selectedDiff.final_version?.slice(0, 800) ?? "File was deleted"}
+                  </pre>
+                </div>
+              </div>
+
+              {/* Correction form */}
+              <div className="bg-white border border-gray-200 rounded-xl p-5 space-y-4">
+                <p className="text-sm font-medium text-gray-700">Publish a correction</p>
+                <p className="text-xs text-gray-400">
+                  This note will be injected into the agent's context before the next session.
+                </p>
+
+                <div>
+                  <label className="text-xs text-gray-500 mb-1 block">
+                    What should the agent know? <span className="text-red-400">*</span>
+                  </label>
+                  <textarea
+                    value={note}
+                    onChange={(e) => setNote(e.target.value)}
+                    placeholder="e.g. Don't use db.query() here — this project uses db.run() with async/await"
+                    className="w-full border border-gray-200 rounded-lg px-3 py-2 text-sm resize-none focus:outline-none focus:ring-1 focus:ring-teal-400"
+                    rows={3}
+                  />
+                </div>
+
+                <div>
+                  <label className="text-xs text-gray-500 mb-1 block">
+                    Correct version (optional — defaults to committed version)
+                  </label>
+                  <textarea
+                    value={correctVersion}
+                    onChange={(e) => setCorrectVersion(e.target.value)}
+                    placeholder="Paste the correct code snippet..."
+                    className="w-full border border-gray-200 rounded-lg px-3 py-2 text-sm font-mono resize-none focus:outline-none focus:ring-1 focus:ring-teal-400"
+                    rows={4}
+                  />
+                </div>
+
+                <button
+                  onClick={publishCorrection}
+                  disabled={!note || saving}
+                  className={`px-4 py-2 rounded-lg text-sm font-medium transition-colors ${
+                    saved
+                      ? "bg-green-500 text-white"
+                      : "bg-teal-500 text-white hover:bg-teal-600 disabled:opacity-40 disabled:cursor-not-allowed"
+                  }`}
+                >
+                  {saving ? "Saving..." : saved ? "Correction published ✓" : "Publish correction"}
+                </button>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/diff/index.ts

@@ -0,0 +1,147 @@
+import { execSync } from "child_process";
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { createClient } from "@supabase/supabase-js";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+// ── TYPES ──
+export interface FileDiff {
+  filePath: string;
+  agentWrote: string;
+  finalVersion: string;
+  wasReverted: boolean;
+  linesAdded: number;
+  linesRemoved: number;
+}
+
+export interface SessionDiff {
+  sessionId: string;
+  projectPath: string;
+  diffs: FileDiff[];
+  computedAt: string;
+}
+
+// ── HELPERS ──
+// Get the list of files the agent touched in this session
+// We read from the local .tracer/actions.jsonl file
+function getAgentTouchedFiles(sessionId: string): Map<string, string> {
+  const logFile = process.env.TRACER_LOG_DIR 
+  ? join(process.env.TRACER_LOG_DIR, "actions.jsonl")
+  : join(process.env.HOME || "", ".tracer", "actions.jsonl");
+  if (!existsSync(logFile)) return new Map();
+
+  const lines = readFileSync(logFile, "utf-8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+
+  const fileMap = new Map<string, string>();
+
+  for (const action of lines) {
+    // Only care about write_file actions from this session
+    if (action.sessionId === sessionId && action.tool === "write_file") {
+      fileMap.set(action.input.path, action.input.content ?? "");
+    }
+  }
+
+  return fileMap;
+}
+
+// Count how many lines differ between two strings
+function countLineDiff(a: string, b: string): { added: number; removed: number } {
+  const aLines = a.split("\n");
+  const bLines = b.split("\n");
+
+  const aSet = new Set(aLines);
+  const bSet = new Set(bLines);
+
+  const added = bLines.filter((l) => !aSet.has(l)).length;
+  const removed = aLines.filter((l) => !bSet.has(l)).length;
+
+  return { added, removed };
+}
+
+// ── MAIN FUNCTION ──
+// Call this after a session ends and the developer has committed their final code
+// projectPath = absolute path to the git repo being worked on
+export async function computeDiff(
+  sessionId: string,
+  projectPath: string
+): Promise<SessionDiff> {
+  const agentFiles = getAgentTouchedFiles(sessionId);
+  const diffs: FileDiff[] = [];
+
+  for (const [filePath, agentWrote] of agentFiles) {
+    let finalVersion = "";
+    let wasReverted = false;
+
+    // Try to read the current committed version of the file
+    try {
+      const relativePath = filePath.replace(projectPath + "/", "");
+      const gitContent = execSync(`git show HEAD:${relativePath}`, {
+        cwd: projectPath,
+        encoding: "utf-8",
+      });
+      finalVersion = gitContent;
+    } catch {
+      // File doesn't exist in git — agent created it but it was deleted
+      finalVersion = "";
+      wasReverted = true;
+    }
+
+    // If the agent version and final version are different — that's a deviation
+    const isDifferent = agentWrote.trim() !== finalVersion.trim();
+
+    if (isDifferent) {
+      const { added, removed } = countLineDiff(agentWrote, finalVersion);
+      diffs.push({
+        filePath,
+        agentWrote,
+        finalVersion,
+        wasReverted: finalVersion === "",
+        linesAdded: added,
+        linesRemoved: removed,
+      });
+    }
+  }
+
+  const sessionDiff: SessionDiff = {
+    sessionId,
+    projectPath,
+    diffs,
+    computedAt: new Date().toISOString(),
+  };
+
+  // Save to Supabase
+  await saveDiff(sessionDiff);
+
+  return sessionDiff;
+}
+
+// ── SAVE TO SUPABASE ──
+async function saveDiff(sessionDiff: SessionDiff): Promise<void> {
+  const url = process.env.SUPABASE_URL;
+  const key = process.env.SUPABASE_ANON_KEY;
+  if (!url || !key) return;
+
+  const client = createClient(url, key);
+
+  for (const diff of sessionDiff.diffs) {
+    const { error } = await client.from("diffs").insert({
+      session_id: sessionDiff.sessionId,
+      file_path: diff.filePath,
+      agent_wrote: diff.agentWrote,
+      final_version: diff.finalVersion,
+      was_reverted: diff.wasReverted,
+      lines_added: diff.linesAdded,
+      lines_removed: diff.linesRemoved,
+      computed_at: sessionDiff.computedAt,
+    });
+
+    if (error) {
+      console.error("[Tracer] Failed to save diff:", error.message);
+    }
+  }
+}

package/src/injector/index.ts

@@ -0,0 +1,177 @@
+import { createClient } from "@supabase/supabase-js";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+// ── TYPES ──
+interface Correction {
+  filePath: string;
+  note: string;
+  agentWrote: string;
+  correctVersion: string;
+  createdAt: string;
+}
+
+interface Deviation {
+  filePath: string;
+  wasReverted: boolean;
+  linesAdded: number;
+  linesRemoved: number;
+  computedAt: string;
+}
+
+// ── FETCH CORRECTIONS FROM SUPABASE ──
+// Gets the most recent corrections a developer published
+// These are things the developer explicitly flagged as wrong
+async function fetchCorrections(projectPath: string): Promise<Correction[]> {
+  const url = process.env.SUPABASE_URL;
+  const key = process.env.SUPABASE_ANON_KEY;
+  if (!url || !key) return [];
+
+  const client = createClient(url, key);
+
+  const { data, error } = await client
+    .from("corrections")
+    .select("file_path, note, agent_wrote, correct_version, created_at")
+    .order("created_at", { ascending: false })
+    .limit(20);
+
+  if (error) {
+    console.error("[Tracer] Failed to fetch corrections:", error.message);
+    return [];
+  }
+
+  return (data ?? []).map((r: any) => ({
+    filePath: r.file_path,
+    note: r.note,
+    agentWrote: r.agent_wrote,
+    correctVersion: r.correct_version,
+    createdAt: r.created_at,
+  }));
+}
+
+// ── FETCH RECENT DEVIATIONS FROM SUPABASE ──
+// Gets files the agent recently got wrong even without a correction note
+// Pattern: if the agent touched a file and it was reverted 2+ times, flag it
+async function fetchPatternDeviations(projectPath: string): Promise<Deviation[]> {
+  const url = process.env.SUPABASE_URL;
+  const key = process.env.SUPABASE_ANON_KEY;
+  if (!url || !key) return [];
+
+  const client = createClient(url, key);
+
+  const { data, error } = await client
+    .from("diffs")
+    .select("file_path, was_reverted, lines_added, lines_removed, computed_at")
+    .eq("was_reverted", true)
+    .order("computed_at", { ascending: false })
+    .limit(10);
+
+  if (error) {
+    console.error("[Tracer] Failed to fetch deviations:", error.message);
+    return [];
+  }
+
+  return (data ?? []).map((r: any) => ({
+    filePath: r.file_path,
+    wasReverted: r.was_reverted,
+    linesAdded: r.lines_added,
+    linesRemoved: r.lines_removed,
+    computedAt: r.computed_at,
+  }));
+}
+
+// ── LOCAL FALLBACK ──
+// If Supabase has no data yet, read from local .tracer/actions.jsonl
+function getLocalContext(): string {
+  const logFile = process.env.TRACER_LOG_DIR
+  ? join(process.env.TRACER_LOG_DIR, "actions.jsonl")
+  : join(process.env.HOME || "", ".tracer", "actions.jsonl");
+  if (!existsSync(logFile)) return "";
+
+  const lines = readFileSync(logFile, "utf-8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+
+  // Find errored actions
+  const errors = lines.filter((l) => l.error !== null);
+  if (errors.length === 0) return "";
+
+  const errorSummary = errors
+    .slice(-5) // last 5 errors
+    .map((e) => `- Tool: ${e.tool}, Input: ${JSON.stringify(e.input)}, Error: ${e.error}`)
+    .join("\n");
+
+  return `Recent local errors:\n${errorSummary}`;
+}
+
+// ── MAIN FUNCTION ──
+// This is what gets called before a new session starts
+// Returns a string that gets prepended to the agent's context
+export async function buildContextPrefix(projectPath: string): Promise<string> {
+  const corrections = await fetchCorrections(projectPath);
+  const deviations = await fetchPatternDeviations(projectPath);
+  const localContext = getLocalContext();
+
+  const lines: string[] = [];
+
+  lines.push("# Tracer: Agent Memory");
+  lines.push("The following is a record of past mistakes and corrections on this project.");
+  lines.push("Use this to avoid repeating the same errors.\n");
+
+  // Corrections section — developer annotated these explicitly
+  if (corrections.length > 0) {
+    lines.push("## Developer Corrections");
+    for (const c of corrections) {
+      lines.push(`### File: ${c.filePath}`);
+      lines.push(`Note: ${c.note}`);
+      if (c.agentWrote) {
+        lines.push(`Agent wrote:\n\`\`\`\n${c.agentWrote.slice(0, 200)}\n\`\`\``);
+      }
+      if (c.correctVersion) {
+        lines.push(`Correct version:\n\`\`\`\n${c.correctVersion.slice(0, 200)}\n\`\`\``);
+      }
+      lines.push("");
+    }
+  }
+
+  // Deviations section — automatically detected reversions
+  if (deviations.length > 0) {
+    lines.push("## Automatically Detected Reversions");
+    lines.push("These files were written by the agent but reverted by the developer:");
+    for (const d of deviations) {
+      lines.push(`- ${d.filePath} (reverted on ${d.computedAt.slice(0, 10)})`);
+    }
+    lines.push("");
+  }
+
+  // Local errors section
+  if (localContext) {
+    lines.push("## Recent Errors");
+    lines.push(localContext);
+  }
+
+  // If nothing to inject, return empty
+  if (corrections.length === 0 && deviations.length === 0 && !localContext) {
+    return "";
+  }
+
+  return lines.join("\n");
+}
+
+// ── CLI RUNNER ──
+// Run this file directly to preview what context would be injected
+// Usage: tsx src/injector/index.ts /path/to/your/project
+if (require.main === module) {
+  const projectPath = process.argv[2] || process.cwd();
+  buildContextPrefix(projectPath).then((prefix) => {
+    if (!prefix) {
+      console.log("[Tracer] No context to inject yet. Run some sessions first.");
+    } else {
+      console.log(prefix);
+    }
+  });
+}

package/src/lib/supabase.ts

@@ -0,0 +1,6 @@
+import { createClient } from "@supabase/supabase-js";
+
+const url = process.env.NEXT_PUBLIC_SUPABASE_URL!;
+const key = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!;
+
+export const supabase = createClient(url, key);

package/src/recorder/index.ts

@@ -0,0 +1,87 @@
+import { createClient } from "@supabase/supabase-js";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+// ── TYPES ──
+export interface Action {
+  sessionId: string;
+  tool: string;
+  input: Record<string, any>;
+  output: string | null;
+  error: string | null;
+  timestamp: string;
+}
+
+// ── SUPABASE CLIENT ──
+// We lazy-initialize so the server still boots even without .env set up yet
+let supabase: ReturnType<typeof createClient> | null = null;
+
+function getClient() {
+  if (supabase) return supabase;
+
+  const url = process.env.SUPABASE_URL;
+  const key = process.env.SUPABASE_ANON_KEY;
+
+  if (!url || !key) {
+    console.error("[Tracer] Warning: Supabase not configured. Logging to console only.");
+    return null;
+  }
+
+  supabase = createClient(url, key);
+  return supabase;
+}
+
+// ── LOCAL FALLBACK ──
+// If Supabase isn't configured yet, we write to a local JSON file
+// This means the server works on Day 1 even before Supabase is set up
+import { appendFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+const LOG_DIR = process.env.TRACER_LOG_DIR || join(process.env.HOME || "", ".tracer");
+const LOG_FILE = join(LOG_DIR, "actions.jsonl");
+
+function logLocally(action: Action) {
+  if (!existsSync(LOG_DIR)) mkdirSync(LOG_DIR, { recursive: true });
+  appendFileSync(LOG_FILE, JSON.stringify(action) + "\n", "utf-8");
+}
+
+// ── MAIN FUNCTION ──
+// This is what gets called from server/index.ts on every agent action
+export async function recordAction(action: Action): Promise<void> {
+  // Always log locally as backup
+  logLocally(action);
+
+  const client = getClient();
+  if (!client) return;
+
+  const { error } = await client.from("actions").insert({
+    session_id: action.sessionId,
+    tool: action.tool,
+    input: action.input,
+    output: action.output,
+    error: action.error,
+    timestamp: action.timestamp,
+  });
+
+  if (error) {
+    console.error("[Tracer] Failed to save action to Supabase:", error.message);
+  }
+}
+
+// ── SESSION CLOSER ──
+// Call this when a session ends to mark it complete in Supabase
+export async function closeSession(sessionId: string, projectPath: string): Promise<void> {
+  const client = getClient();
+  if (!client) return;
+
+  const { error } = await client.from("sessions").insert({
+    id: sessionId,
+    project_path: projectPath,
+    ended_at: new Date().toISOString(),
+  });
+
+  if (error) {
+    console.error("[Tracer] Failed to close session:", error.message);
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,229 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { v4 as uuidv4 } from "uuid";
+import { recordAction } from "../recorder/index.js";
+import { computeDiff } from "../diff/index.js";
+import { closeSession } from "../recorder/index.js";
+import { buildContextPrefix } from "../injector/index.js";
+
+// Each session gets a unique ID when the MCP server starts
+const SESSION_ID = uuidv4();
+const SESSION_START = new Date().toISOString();
+
+console.error(`[Tracer] Session started: ${SESSION_ID}`);
+
+// This is the MCP server — it's what Claude Code connects to
+const server = new McpServer({
+  name: "tracer",
+  version: "0.1.0",
+});
+
+// ── TOOL 1: read_file ──
+// Claude Code calls this when it wants to read a file
+// We intercept it, log it, then actually read the file
+server.tool(
+  "read_file",
+  "Read the contents of a file",
+  {
+    path: z.string().describe("Path to the file to read"),
+  },
+  async ({ path }) => {
+    const fs = await import("fs/promises");
+
+    let content = "";
+    let error = null;
+
+    try {
+      content = await fs.readFile(path, "utf-8");
+    } catch (e: any) {
+      error = e.message;
+    }
+
+    // Record this action regardless of success or failure
+    await recordAction({
+      sessionId: SESSION_ID,
+      tool: "read_file",
+      input: { path },
+      output: error ? null : content.slice(0, 500), // store first 500 chars
+      error,
+      timestamp: new Date().toISOString(),
+    });
+
+    if (error) {
+      return { content: [{ type: "text", text: `Error: ${error}` }] };
+    }
+
+    return { content: [{ type: "text", text: content }] };
+  }
+);
+
+// ── TOOL 2: write_file ──
+// Claude Code calls this when it wants to write or edit a file
+// This is the most important one to track — writes = agent decisions
+server.tool(
+  "write_file",
+  "Write content to a file",
+  {
+    path: z.string().describe("Path to the file to write"),
+    content: z.string().describe("Content to write to the file"),
+  },
+  async ({ path, content }) => {
+    const fs = await import("fs/promises");
+    const pathModule = await import("path");
+
+    let error = null;
+
+    try {
+      // Make sure the directory exists before writing
+      await fs.mkdir(pathModule.dirname(path), { recursive: true });
+      await fs.writeFile(path, content, "utf-8");
+    } catch (e: any) {
+      error = e.message;
+    }
+
+    await recordAction({
+      sessionId: SESSION_ID,
+      tool: "write_file",
+      input: { path, content: content.slice(0, 500) },
+      output: error ? null : "success",
+      error,
+      timestamp: new Date().toISOString(),
+    });
+
+    if (error) {
+      return { content: [{ type: "text", text: `Error: ${error}` }] };
+    }
+
+    return { content: [{ type: "text", text: `Written to ${path}` }] };
+  }
+);
+
+// ── TOOL 3: run_command ──
+// Claude Code calls this when it runs terminal commands
+server.tool(
+  "run_command",
+  "Run a shell command",
+  {
+    command: z.string().describe("The shell command to run"),
+  },
+  async ({ command }) => {
+    const { exec } = await import("child_process");
+    const { promisify } = await import("util");
+    const execAsync = promisify(exec);
+
+    let stdout = "";
+    let stderr = "";
+    let error = null;
+
+    try {
+      const result = await execAsync(command, { timeout: 30000 });
+      stdout = result.stdout;
+      stderr = result.stderr;
+    } catch (e: any) {
+      error = e.message;
+    }
+
+    await recordAction({
+      sessionId: SESSION_ID,
+      tool: "run_command",
+      input: { command },
+      output: stdout.slice(0, 500),
+      error: error || stderr.slice(0, 200) || null,
+      timestamp: new Date().toISOString(),
+    });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: error ? `Error: ${error}` : stdout || stderr || "Done",
+        },
+      ],
+    };
+  }
+);
+
+// ── TOOL 4: close_session ──
+// Called when the agent session ends
+// Triggers the diff engine and saves everything to Supabase
+server.tool(
+  "close_session",
+  "Close the current session and compute diffs against git",
+  {
+    projectPath: z.string().describe("Absolute path to the git repo"),
+  },
+  async ({ projectPath }) => {
+    console.error(`[Tracer] Closing session ${SESSION_ID}...`);
+
+    // Save session record to Supabase
+    await closeSession(SESSION_ID, projectPath);
+
+    // Compute what the agent did vs what was committed
+    const result = await computeDiff(SESSION_ID, projectPath);
+
+    const deviationCount = result.diffs.length;
+
+    console.error(`[Tracer] Session closed. Found ${deviationCount} deviations.`);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            sessionId: SESSION_ID,
+            deviations: deviationCount,
+            files: result.diffs.map((d) => ({
+              path: d.filePath,
+              wasReverted: d.wasReverted,
+              linesChanged: d.linesAdded + d.linesRemoved,
+            })),
+          }, null, 2),
+        },
+      ],
+    };
+  }
+);
+
+// ── TOOL 5: get_context ──
+// Called at the start of a new session
+// Returns all past corrections and deviations as a context string
+server.tool(
+  "get_context",
+  "Get past corrections and known mistakes for this project",
+  {
+    projectPath: z.string().describe("Absolute path to the project"),
+  },
+  async ({ projectPath }) => {
+    const prefix = await buildContextPrefix(projectPath);
+
+    if (!prefix) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "No past corrections found for this project. Starting fresh.",
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: prefix,
+        },
+      ],
+    };
+  }
+);
+
+// ── START SERVER ──
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`[Tracer] MCP server running. Listening for agent actions...`);
+}
+
+main().catch(console.error);

package/test.txt

@@ -0,0 +1 @@
+hello from tracer

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}