Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
61 lines (46 loc) · 2.32 KB

CONTRIBUTING.md

File metadata and controls

61 lines (46 loc) · 2.32 KB
Raw

Contributing

Thanks for your interest in context-tracker. This is a small, deliberately minimal project — the bar for changes is "does it keep the tool sharp and simple."

Development

Requires Node.js >= 18 (see .nvmrc for the recommended version).

git clone https://github.com/conrad621/context-tracker.git
cd context-tracker
node --test        # run the whole test suite

There is nothing to build — the code is plain ES modules with no bundler.

Running locally

node src/viewer.js                 # viewer at http://localhost:39877
node src/proxy.js anthropic        # proxy using a profile from config/profiles.json

Project layout

bin/context-tracker.js   CLI entry (dispatches proxy/viewer subcommands)
src/proxy.js             forwarding proxy + request/response mirroring
src/viewer.js            viewer server + injected single-page web UI
src/protocols.js         protocol detection, request extraction, SSE response parsing
src/diff.js              turn-over-turn request diff
src/config.js            profile loading + config resolution
config/profiles.json     provider presets
test/                    node:test unit + e2e tests

protocols.js and diff.js are written dependency-free and ES5-friendly so the viewer can inject their source into the browser and reuse the exact same logic. Keep them that way — no Node built-ins, no syntax that won't run in a browser.

Ground rules

  • Zero runtime dependencies. The project ships with none; keep it that way. Heavy or optional features should degrade gracefully when absent.
  • Never touch the live path. Capture and analysis are fire-and-forget side channels; the agent's request/response must never be blocked or altered.
  • Local-first. No telemetry; data leaves the machine only on explicit export.
  • Tests with changes. New modules ship with unit tests; behavior-changing work adds or updates an e2e test. Run node --test before opening a PR.
  • Docs in sync. User-facing changes update both README.md and README.zh.md.

Pull requests

  • Branch from main, keep the diff focused.
  • Make sure node --test passes (CI runs it on Node 18/20/22).
  • Describe what changed and how you verified it.

See the roadmap and implementation plan for where the project is headed.