footprint-trace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 footprint contributors
+
+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,165 @@
+# footprint
+
+**Your Claude, learned locally.**
+
+Footprint watches your Claude Code sessions, fine-tunes a small local model
+(LoRA) on how *you and Claude* work in your projects, and serves it as an
+OpenAI-compatible API. When your Claude quota runs out, OpenCode (or Cursor,
+or Codex CLI) keeps working in the same style — fully offline, on your machine.
+
+```
+trace → chat with claude → collect → train → install → /footprint in OpenCode
+```
+
+## How it works
+
+1. Claude Code already logs every session (prompts, replies, tool calls) to `~/.claude/projects`.
+2. `footprint trace` arms a marker so only sessions from that point on become training data.
+3. `footprint collect` parses those transcripts into chat-format training examples.
+4. `footprint train` LoRA fine-tunes a small model (default: Qwen2.5-Coder-1.5B, 4-bit MLX) on them.
+5. `footprint install` registers a launchd agent — the server runs itself at
+   `http://127.0.0.1:8399/v1`, starts at login, restarts on crash. You never run it by hand.
+6. Any OpenAI-compatible tool points at that URL and behaves like your Claude.
+
+## Requirements
+
+| | trace / collect | train / serve |
+|---|---|---|
+| **macOS (Apple Silicon)** | ✅ | ✅ (MLX) |
+| **macOS (Intel)** | ✅ | ❌ |
+| **Linux** | ✅ | ❌ (for now) |
+| **Windows** | ✅ | ❌ (for now) |
+
+- [Claude Code](https://claude.com/claude-code) installed and used at least once
+- Python 3.9+
+- Node.js 18+ (only if installing via npm)
+
+Training and serving use [MLX](https://github.com/ml-explore/mlx), which is
+Apple-Silicon-only today. On Linux/Windows you can still trace and collect —
+your `data/` folder is portable; train it on any Apple Silicon Mac. Other
+backends (llama.cpp / unsloth) are welcome contributions.
+
+## Install
+
+### macOS
+
+```sh
+npm install -g footprint-trace
+```
+
+or from source:
+
+```sh
+git clone https://github.com/Amanlabh/footprint.git
+cd footprint
+python3 footprint.py setup
+```
+
+### Linux
+
+```sh
+npm install -g footprint-trace      # or the git clone above
+```
+
+`setup` skips MLX automatically. `trace` and `collect` work; copy `data/` to a Mac to train.
+
+### Windows
+
+Use PowerShell (Python 3 from python.org or the Microsoft Store):
+
+```powershell
+npm install -g footprint-trace
+```
+
+Same scope as Linux: trace + collect. WSL2 works the same way.
+
+## Getting started
+
+**1. Arm tracing — before you start Claude.**
+
+```sh
+footprint trace
+```
+
+Claude Code already logs every session; the trace marker makes footprint train
+only on sessions from this point on. (Skip this step — or delete
+`~/.claude/footprint-trace` — to train on your entire history instead.)
+
+**2. Use Claude Code normally.**
+
+```sh
+claude
+```
+
+Every session (your prompts, Claude's replies, tool calls) is captured automatically.
+
+**3. Collect and train.**
+
+```sh
+footprint collect     # transcripts -> data/train.jsonl + data/valid.jsonl
+footprint train       # LoRA fine-tune (~10 min, downloads ~1 GB base model first time)
+```
+
+**4. Install the always-on server (macOS).**
+
+```sh
+footprint install
+```
+
+This registers a launchd agent — the server starts at login, restarts if it
+crashes, and you never run it by hand. It also wires up OpenCode:
+
+- provider `footprint` at `http://127.0.0.1:8399/v1`
+- a `/footprint <task>` command inside OpenCode
+
+**5. Claude quota over? Keep going.**
+
+Open OpenCode and type:
+
+```
+/footprint fix the failing test in auth.py
+```
+
+Or point any OpenAI-compatible tool at the server:
+
+| Tool | Setting |
+|---|---|
+| **Cursor** | Settings → Models → OpenAI base URL `http://127.0.0.1:8399/v1`, any API key, add model `footprint` |
+| **Codex CLI** | custom provider with that base URL in `~/.codex/config.toml` |
+| **anything else** | base URL `http://127.0.0.1:8399/v1`, API key: none |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `footprint` | banner + status |
+| `footprint trace` | arm tracing (run before starting Claude) |
+| `footprint collect [dir]` | parse transcripts of a project (default: current dir; unknown dir = all projects) |
+| `footprint train` | LoRA fine-tune on collected data |
+| `footprint install` | launchd auto-server + OpenCode integration (macOS) |
+| `footprint serve` | run the server manually (fallback; `install` makes this unnecessary) |
+| `footprint status` | model, example count, adapter, tracing, server state |
+
+## Configuration
+
+| Env var | Default | |
+|---|---|---|
+| `FOOTPRINT_MODEL` | `mlx-community/Qwen2.5-Coder-1.5B-Instruct-4bit` | any MLX chat model |
+| `FOOTPRINT_ITERS` | `300` | training iterations |
+| `FOOTPRINT_PORT` | `8399` | server port |
+
+## Troubleshooting
+
+- **`no transcripts found`** — either you haven't used Claude Code in this project, or the trace marker is newer than all sessions. Chat first, or `rm ~/.claude/footprint-trace`.
+- **server not responding** — check `/tmp/footprint-serve.log`; `launchctl kickstart -k gui/$UID/com.footprint.serve` restarts it.
+- **`mlx_lm` import fails** — re-run `footprint setup` (Apple Silicon only).
+- **quality is rough** — more data beats more iterations: keep tracing, re-collect, re-train. 1.5B is small; try `FOOTPRINT_MODEL=mlx-community/Qwen2.5-Coder-7B-Instruct-4bit` if you have ≥16 GB RAM.
+
+## Privacy
+
+Everything stays on your machine. `data/` (your transcripts) and `adapters/`
+(weights trained on them) are gitignored — never commit or publish them.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/banner.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+console.log(`
+\x1b[36m███████╗ ██████╗  ██████╗ ████████╗██████╗ ██████╗ ██╗███╗   ██╗████████╗
+██╔════╝██╔═══██╗██╔═══██╗╚══██╔══╝██╔══██╗██╔══██╗██║████╗  ██║╚══██╔══╝
+█████╗  ██║   ██║██║   ██║   ██║   ██████╔╝██████╔╝██║██╔██╗ ██║   ██║
+██╔══╝  ██║   ██║██║   ██║   ██║   ██╔═══╝ ██╔══██╗██║██║╚██╗██║   ██║
+██║     ╚██████╔╝╚██████╔╝   ██║   ██║     ██║  ██║██║██║ ╚████║   ██║
+╚═╝      ╚═════╝  ╚═════╝    ╚═╝   ╚═╝     ╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝   ╚═╝\x1b[0m
+
+  your Claude, learned locally.
+
+  1. footprint trace      arm tracing — do this BEFORE starting claude
+  2. claude               chat as usual; every session is traced automatically
+  3. footprint collect    turn traced sessions into training data
+  4. footprint train      fine-tune the local model
+  5. footprint install    always-on server + /footprint command in OpenCode
+
+  Claude quota over? open OpenCode, type /footprint <task> — works like Claude.
+`);

package/bin/footprint.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const root = path.join(__dirname, "..");
+const script = path.join(root, "footprint.py");
+const venvPy = path.join(root, ".venv", "bin", "python");
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  require("./banner");
+}
+
+if (!fs.existsSync(venvPy)) {
+  console.log("first run — setting up (venv + mlx-lm, takes a minute)…");
+  const s = spawnSync("python3", [script, "setup"], { stdio: "inherit" });
+  if (s.status) process.exit(s.status);
+}
+
+const r = spawnSync(venvPy, [script, ...(args.length ? args : ["status"])], {
+  stdio: "inherit",
+});
+process.exit(r.status === null ? 1 : r.status);

package/footprint.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""footprint — learn a local SLM from your Claude Code transcripts.
+
+Commands:
+  setup                 create .venv, install mlx-lm, link /footprint skill
+  trace                 arm tracing: sessions from now on become training data (run before chatting)
+  collect [project]     parse ~/.claude/projects transcripts -> data/{train,valid}.jsonl
+  train                 LoRA fine-tune base model on collected data
+  serve                 OpenAI-compatible API at localhost:8399 (launchd runs this; users don't)
+  install               launchd agent (server always on) + OpenCode /footprint command
+  status                what's collected/trained
+"""
+import json, os, re, subprocess, sys, glob, random, time, plistlib
+
+ROOT = os.path.dirname(os.path.abspath(__file__))
+DATA = os.path.join(ROOT, "data")
+ADAPTERS = os.path.join(ROOT, "adapters")
+PROJECTS = os.path.expanduser("~/.claude/projects")
+TRACE_MARK = os.path.expanduser("~/.claude/footprint-trace")
+LAUNCHD = os.path.expanduser("~/Library/LaunchAgents/com.footprint.serve.plist")
+OPENCODE = os.path.expanduser("~/.config/opencode")
+MODEL = os.environ.get("FOOTPRINT_MODEL", "mlx-community/Qwen2.5-Coder-1.5B-Instruct-4bit")
+CTX_BUDGET = 6000      # chars of history per training example
+RESULT_CAP = 1500      # chars kept per tool result
+
+SYSTEM = ("You are footprint, a local coding agent trained on Claude Code sessions. "
+          "To act, emit tool calls as <tool name=\"NAME\">{json args}</tool>. "
+          "Say DONE when the task is complete.")
+
+
+def _text(content, cap=None):
+    """Flatten a Claude message content (str or block list) to training text."""
+    if isinstance(content, str):
+        out = content
+    else:
+        parts = []
+        for b in content or []:
+            t = b.get("type")
+            if t == "text":
+                parts.append(b["text"])
+            elif t == "tool_use":
+                parts.append(f'<tool name="{b["name"]}">{json.dumps(b.get("input", {}))}</tool>')
+            elif t == "tool_result":
+                c = b.get("content")
+                c = "".join(x.get("text", "") for x in c) if isinstance(c, list) else str(c or "")
+                parts.append(f"<tool_result>{c[:RESULT_CAP]}</tool_result>")
+        out = "\n".join(p for p in parts if p.strip())
+    out = re.sub(r"<system-reminder>.*?</system-reminder>", "", out, flags=re.S)
+    out = re.sub(r"<local-command-caveat>.*?</local-command-caveat>", "", out, flags=re.S)
+    return (out[:cap] if cap else out).strip()
+
+
+def parse_session(path):
+    """One transcript file -> list of alternating {role, content} messages."""
+    msgs = []
+    for line in open(path, errors="replace"):
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if rec.get("type") not in ("user", "assistant") or rec.get("isSidechain") or rec.get("isMeta"):
+            continue
+        m = rec.get("message") or {}
+        role = m.get("role")
+        txt = _text(m.get("content"))
+        if not role or not txt:
+            continue
+        if msgs and msgs[-1]["role"] == role:
+            msgs[-1]["content"] += "\n" + txt
+        else:
+            msgs.append({"role": role, "content": txt})
+    return msgs
+
+
+def trace():
+    """Arm tracing. Claude Code already logs every session to ~/.claude/projects;
+    the marker makes collect use only sessions started after this moment."""
+    os.makedirs(os.path.dirname(TRACE_MARK), exist_ok=True)
+    with open(TRACE_MARK, "w") as f:
+        f.write(str(time.time()))
+    print("tracing armed. chat with Claude Code as usual — those sessions become training data.\n"
+          "then: footprint.py collect && footprint.py train\n"
+          "(delete ~/.claude/footprint-trace to collect ALL history again)")
+
+
+def collect(project=None):
+    since = float(open(TRACE_MARK).read()) if os.path.exists(TRACE_MARK) else 0.0
+    slug = "-" + os.path.abspath(project or os.getcwd()).strip("/").replace("/", "-").replace(".", "-")
+    dirs = [os.path.join(PROJECTS, slug)] if os.path.isdir(os.path.join(PROJECTS, slug)) \
+        else glob.glob(os.path.join(PROJECTS, "*"))
+    examples = []
+    for d in dirs:
+        for f in glob.glob(os.path.join(d, "*.jsonl")):
+            if os.path.getmtime(f) < since:
+                continue
+            msgs = parse_session(f)
+            # one example per assistant turn, with preceding context under budget
+            for i, m in enumerate(msgs):
+                if m["role"] != "assistant":
+                    continue
+                ctx, size = [], 0
+                for prev in reversed(msgs[:i]):
+                    size += len(prev["content"])
+                    if size > CTX_BUDGET:
+                        break
+                    ctx.insert(0, prev)
+                if not ctx or ctx[0]["role"] != "user":
+                    continue
+                examples.append({"messages": [{"role": "system", "content": SYSTEM}, *ctx, m]})
+    if not examples:
+        hint = " (trace marker active — only sessions after `trace` count; delete ~/.claude/footprint-trace for all history)" if since else ""
+        sys.exit(f"no transcripts found under {PROJECTS}{hint}")
+    random.seed(0)
+    random.shuffle(examples)
+    n_valid = max(1, len(examples) // 10)
+    os.makedirs(DATA, exist_ok=True)
+    for name, chunk in [("valid", examples[:n_valid]), ("train", examples[n_valid:])]:
+        with open(os.path.join(DATA, f"{name}.jsonl"), "w") as fh:
+            for e in chunk:
+                fh.write(json.dumps(e) + "\n")
+    print(f"collected {len(examples)} examples ({len(examples)-n_valid} train / {n_valid} valid) -> {DATA}")
+
+
+def train():
+    if not os.path.exists(os.path.join(DATA, "train.jsonl")):
+        sys.exit("no data. run: footprint.py collect")
+    subprocess.run([sys.executable, "-m", "mlx_lm", "lora", "--model", MODEL, "--train",
+                    "--data", DATA, "--adapter-path", ADAPTERS,
+                    "--iters", os.environ.get("FOOTPRINT_ITERS", "300"),
+                    "--max-seq-length", "4096", "--batch-size", "1"], check=True)
+    print(f"adapter saved -> {ADAPTERS}")
+
+
+def serve():
+    port = os.environ.get("FOOTPRINT_PORT", "8399")
+    args = [sys.executable, "-m", "mlx_lm", "server", "--model", MODEL,
+            "--host", "127.0.0.1", "--port", port]
+    if os.path.exists(os.path.join(ADAPTERS, "adapters.safetensors")):
+        args += ["--adapter-path", ADAPTERS]
+    else:
+        print("(no adapter yet — serving base model; run train first for footprint behavior)")
+    print(f"OpenAI-compatible API: http://127.0.0.1:{port}/v1  (model name: footprint)\n"
+          "point Cursor / OpenCode / Codex / any OpenAI-compatible client here, api key: none")
+    subprocess.run(args, check=True)
+
+
+def install():
+    """Server runs itself (launchd, KeepAlive) + OpenCode /footprint command. User never runs serve."""
+    if sys.platform != "darwin":
+        sys.exit("install is macOS-only (launchd + MLX). on Linux/Windows run serve manually once MLX alternatives land.")
+    py = os.path.join(ROOT, ".venv", "bin", "python")
+    if not os.path.exists(py):
+        sys.exit("no .venv. run: python3 footprint.py setup")
+    port = os.environ.get("FOOTPRINT_PORT", "8399")
+    os.makedirs(os.path.dirname(LAUNCHD), exist_ok=True)
+    with open(LAUNCHD, "wb") as f:
+        plistlib.dump({"Label": "com.footprint.serve",
+                       "ProgramArguments": [py, os.path.join(ROOT, "footprint.py"), "serve"],
+                       "RunAtLoad": True, "KeepAlive": True,
+                       "StandardOutPath": "/tmp/footprint-serve.log",
+                       "StandardErrorPath": "/tmp/footprint-serve.log"}, f)
+    subprocess.run(["launchctl", "unload", LAUNCHD], capture_output=True)
+    subprocess.run(["launchctl", "load", "-w", LAUNCHD], check=True)
+
+    cfg_path = os.path.join(OPENCODE, "opencode.json")
+    cfg = json.load(open(cfg_path)) if os.path.exists(cfg_path) else {"$schema": "https://opencode.ai/config.json"}
+    cfg.setdefault("provider", {})["footprint"] = {
+        "npm": "@ai-sdk/openai-compatible", "name": "footprint",
+        "options": {"baseURL": f"http://127.0.0.1:{port}/v1"},
+        "models": {"footprint": {"name": "footprint"}}}
+    os.makedirs(os.path.join(OPENCODE, "command"), exist_ok=True)
+    with open(cfg_path, "w") as f:
+        json.dump(cfg, f, indent=2)
+    with open(os.path.join(OPENCODE, "command", "footprint.md"), "w") as f:
+        f.write("---\ndescription: do task with footprint — local model trained on your Claude sessions\n"
+                "model: footprint/footprint\n---\n$ARGUMENTS\n")
+    print(f"installed:\n"
+          f"  server: launchd keeps http://127.0.0.1:{port}/v1 running (log: /tmp/footprint-serve.log)\n"
+          f"  opencode: /footprint <task> uses it; or pick model 'footprint' via /models\n"
+          f"  cursor/codex: base URL http://127.0.0.1:{port}/v1, any api key")
+
+
+def status():
+    tr = os.path.join(DATA, "train.jsonl")
+    n = sum(1 for _ in open(tr)) if os.path.exists(tr) else 0
+    print(f"model: {MODEL}\nexamples: {n}\nadapter: "
+          f"{'yes' if os.path.exists(os.path.join(ADAPTERS, 'adapters.safetensors')) else 'no'}\n"
+          f"tracing: {'armed since ' + time.ctime(float(open(TRACE_MARK).read())) if os.path.exists(TRACE_MARK) else 'off (collect uses all history)'}\n"
+          f"server: {'launchd-managed' if os.path.exists(LAUNCHD) else 'not installed (run install)'}")
+
+
+def setup():
+    venv = os.path.join(ROOT, ".venv")
+    if not os.path.exists(venv):
+        subprocess.run([sys.executable, "-m", "venv", venv], check=True)
+    if sys.platform == "darwin":
+        subprocess.run([os.path.join(venv, "bin", "pip"), "install", "-q", "mlx-lm"], check=True)
+    else:
+        print("mlx-lm skipped (Apple Silicon only). trace/collect work here; "
+              "copy data/ to a Mac for train/serve.")
+    link = os.path.expanduser("~/.claude/skills/footprint")
+    os.makedirs(os.path.dirname(link), exist_ok=True)
+    if not os.path.exists(link):
+        os.symlink(os.path.join(ROOT, "skills", "footprint"), link)
+    print(f"ready. /footprint skill linked -> {link}\nuse: {venv}/bin/python footprint.py collect|train|run")
+
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "status"
+    {"collect": lambda: collect(sys.argv[2] if len(sys.argv) > 2 else None),
+     "trace": trace,
+     "train": train,
+     "serve": serve,
+     "install": install,
+     "status": status,
+     "setup": setup}.get(cmd, lambda: sys.exit(__doc__))()

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "footprint-trace",
+  "version": "0.1.0",
+  "description": "Local SLM trained on your Claude Code sessions. When Claude quota runs out, OpenCode keeps working like Claude.",
+  "bin": {
+    "footprint": "bin/footprint.js"
+  },
+  "scripts": {
+    "postinstall": "node bin/banner.js"
+  },
+  "files": [
+    "bin",
+    "footprint.py",
+    "skills"
+  ],
+  "license": "MIT"
+}

package/skills/footprint/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: footprint
+description: Local SLM that learns from Claude Code transcripts ("footprint") and replays the project's working style. Trigger on /footprint, "take footprint", "train footprint", "footprint status", "footprint run <task>".
+---
+
+# Footprint
+
+Footprint collects this machine's Claude Code session transcripts, fine-tunes a
+small local model (MLX LoRA, Apple Silicon) on them, and can then execute tasks
+locally with a tiny bash-tool agent loop — no API needed.
+
+Repo: `/Users/aman/Developer/footprint`. Python: `/Users/aman/Developer/footprint/.venv/bin/python`
+(if `.venv` missing, run `setup` first with system `python3`).
+
+## Commands
+
+Map the user's `/footprint <arg>` to one Bash call:
+
+| Invocation | Run |
+|---|---|
+| `/footprint` or `/footprint status` | `.venv/bin/python footprint.py status` |
+| `/footprint setup` | `python3 footprint.py setup` |
+| `/footprint trace` | `.venv/bin/python footprint.py trace` (arm BEFORE chatting; only sessions after this become training data) |
+| `/footprint collect` | `.venv/bin/python footprint.py collect <current project dir>` |
+| `/footprint collect all` | `.venv/bin/python footprint.py collect --all-projects-nonexistent-dir` (falls back to all projects) |
+| `/footprint train` | `.venv/bin/python footprint.py train` (long; run in background) |
+| `/footprint install` | `.venv/bin/python footprint.py install` (launchd auto-server + OpenCode `/footprint` command — user never runs serve) |
+| `/footprint serve` | `.venv/bin/python footprint.py serve` (manual fallback only; install makes this unnecessary) |
+
+Always run commands from `/Users/aman/Developer/footprint`.
+
+## Flow for a fresh user
+
+1. `setup` — venv + mlx-lm + skill symlink.
+2. `trace` — arm tracing FIRST, before chatting with Claude. Writes `~/.claude/footprint-trace`; collect then only uses sessions newer than the marker (delete marker to use all history).
+3. Chat with Claude Code normally — sessions land in `~/.claude/projects` automatically.
+4. `collect` — parses `~/.claude/projects/<project>/*.jsonl` into `data/train.jsonl` + `data/valid.jsonl` (chat format, tool calls encoded as `<tool name="...">{args}</tool>`).
+5. `train` — LoRA on `mlx-community/Qwen2.5-Coder-1.5B-Instruct-4bit` (override with `FOOTPRINT_MODEL`, iterations with `FOOTPRINT_ITERS`, default 300). Downloads ~1 GB first time. Run in background, report loss when done.
+6. `install` — the user never runs the server. launchd (`com.footprint.serve`, KeepAlive) keeps the OpenAI-compatible API at `http://127.0.0.1:8399/v1` running across reboots/crashes. Also installs into OpenCode: provider `footprint` + `/footprint <task>` command (`~/.config/opencode/command/footprint.md`) so typing `/footprint` there makes OpenCode work like Claude.
+   Other tools point at the always-on server:
+   - **Cursor**: Settings → Models → OpenAI base URL `http://127.0.0.1:8399/v1`, any API key, add model `footprint`.
+   - **Codex CLI**: set a custom provider with that base URL in `~/.codex/config.toml`.
+
+Report command output tersely. If mlx-lm import fails, rerun `setup`.