| 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 on them (MLX LoRA on Apple Silicon, torch+PEFT elsewhere),
and serves it as an OpenAI-compatible API for OpenCode/Cursor/Codex.
Code layout: footprint.py (entry shim) -> footprint_core/ (cli, config,
transcripts, service, backends/{mlx,torch}_backend.py).
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
setup — venv + mlx-lm + skill symlink.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).- Chat with Claude Code normally — sessions land in
~/.claude/projects automatically.
collect — parses ~/.claude/projects/<project>/*.jsonl into data/train.jsonl + data/valid.jsonl (chat format, tool calls encoded as <tool name="...">{args}</tool>).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.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.
