getting started

Up and running in a few commands.

install once. trace. collect. train. keep coding offline.

Install

Requires Claude Code (used at least once), Python 3.9+, and Node 18+ if installing via npm. The backend is picked automatically — MLX on Apple Silicon, PyTorch elsewhere.

npm — macOS / Linux / Windows

npm install -g footprint-trace

from source

$ git clone https://github.com/Amanlabh/footprint.git
$ cd footprint
$ python3 footprint.py setup

Quickstart

1. Arm tracing — before you start Claude.
Trains only on sessions from this point on. Skip it to use your whole history.
```
footprint trace
```
2. Use Claude Code normally.
Every session is captured automatically.
```
claude
```
3. Collect and train.
Transcripts become training data, then a LoRA fine-tune (~10 min; downloads ~1 GB base model the first time).
```
$ footprint collect
$ footprint train
```
4. Install the always-on server.
Registers with launchd / systemd / Task Scheduler and wires up OpenCode with a /footprint command.
```
footprint install
```
5. Quota over? Keep going.
In OpenCode, or any OpenAI-compatible tool pointed at http://127.0.0.1:8399/v1.
OpenCode
```
/footprint fix the failing test in auth.py
```

Commands

footprint	banner + status
footprint trace	arm tracing (run before starting Claude)
footprint collect [dir]	parse a project's transcripts (unknown dir = all projects)
footprint train	LoRA fine-tune on collected data
footprint install	auto-start server + OpenCode integration
footprint serve	run the server manually (fallback)
footprint status	model, example count, adapter, tracing, server state
footprint login	GitHub device-flow sign in (personal environment)
footprint key new [label]	generate an API key — hash stored in your footprint-vault repo
footprint sync push\|pull	sync training data + adapters across devices via your vault

Configuration

Env var	Default	Notes
FOOTPRINT_MODEL	Qwen2.5-Coder-1.5B (MLX 4-bit on mac)	any chat model of the backend
FOOTPRINT_ITERS	300	training iterations
FOOTPRINT_PORT	8399	server port

Personal environment

One trained model, one set of API keys, every device — without footprint ever holding your data.

What the API key is

A footprint API key (fp_…) is your personal-environment credential. Generate it once — on the account page or with footprint key new — and use the same key on every machine. It identifies your environment, so any device carrying it pulls the same context: your training data, your trained adapter, your setup. The plaintext key is shown exactly once; only its SHA-256 hash is stored. Lose it, revoke it, make a new one.

How connecting with GitHub works

“Continue with GitHub” runs the standard OAuth flow (the CLI uses GitHub’s device flow — type a code, no secret on your machine). On first sign-in footprint creates a private footprint-vault repo in your GitHub account. Your GitHub identity is your footprint account — there is no separate signup, password, or profile stored anywhere.

No database — your repo is the database

footprint runs no server-side storage at all. Everything an account needs lives as files in your private vault repo: keys.json holds the hashed API keys, and data/ + adapters/ hold your synced context after footprint sync push. Git history is the audit log. Delete the repo and your account is gone — nothing remains with us, because nothing was ever with us. On the website your GitHub token lives only in an encrypted cookie in your browser.

Same environment on a new device

new machine

$ footprint login
$ footprint sync pull
# same keys, same data, same trained model

Privacy

Everything stays on your machine. Your transcripts (data/) and the weights trained on them (adapters/) are gitignored — never committed, never published. MIT licensed.