ContextCache: Local Ephemeral Context Server for AI Pair Programmers

ContextCache is a local-first, ephemeral context server designed to bridge the gap between AI coding assistants and your actual development environment. Instead of manually pasting code or describing what you just changed, ContextCache watches your file system, listens to git diffs, and even captures terminal output—all without sending a single byte to the cloud.

Built entirely in a single weekend, ContextCache runs as a lightweight daemon (Node.js + Express + chokidar) and exposes a simple REST/SSE API. The core idea is that AI assistants shouldn't need full project history or remote servers to understand what you're doing. They just need the last few seconds of deltas. So ContextCache keeps only an in-memory ring buffer of recent activity: last 50 file changes, last 10 git diffs, and last 30 lines of terminal output.

I wanted it to feel magical: run npx contextcache in any project, and immediately any AI tool that speaks HTTP can subscribe to /context and get a live stream of what's happening. No configuration files, no database, no dependencies beyond Node.js. The whole thing is about 300 lines of JavaScript, with a promise of plugins for Copilot, Continue, and Tabby.

The project is opinionated: it deliberately does NOT store anything to disk, does NOT authenticate (localhost-only), and does NOT try to understand your code—it just surfaces recent events. It's a context pipe, not a context store.

AI coding assistants like GitHub Copilot, Cursor, and Continue are powerful, but they suffer from a lack of real-time, local context. You constantly have to tell them which file you're editing, what you just changed, or even paste recent code snippets. Privacy concerns also arise when using cloud-based context providers. Developers want the assistant to just 'know' without explicit sharing, but existing solutions either require heavy setup (like indexing entire projects) or send data to third parties. ContextCache fills this gap with a zero-config, privacy-preserving context source that lives entirely on your machine.

• Enable AI assistants to query recent file changes via a local REST API
• Stream terminal output in real-time using Server-Sent Events (SSE)
• Zero external dependencies beyond Node.js (no build step, no binary downloads)
• Start with one command: npx contextcache
• Include a plugin system so popular assistants (Copilot, Continue, Tabby) can subscribe easily
• Stay memory-only: no persistence, no logs written to disk
• Handle 10+ file watchers without noticeable lag (tested on a monorepo with 20000 files)

• Not a general-purpose logging or monitoring tool
• No authentication (only intended for localhost, trust-based)
• No support for remote machines or SSH tunneling
• Not a replacement for full project context (doesn't index code, just recent deltas)
• No editor integration out of the box (rely on file system watcher)

Node.js (v18+) runtime, chokidar for filesystem watching, tiny-git (lightweight wrapper for git diff), pty.js (for capturing terminal output in a subshell), Express + Server-Sent Events for the API, yargs for CLI parsing, and ws (WebSocket) as a fallback for older assistants. No TypeScript—keep it simple for a weekend hack.

ContextCache is a single-process daemon with three main modules: 1) FileWatcher – uses chokidar to monitor file changes in the current directory (respecting .gitignore). Emits events for add/change/delete. 2) GitWatcher – on each relevant file event, runs git diff --no-color -- <file> and stores the diff in an in-memory ring buffer (max 10 diffs). 3) TerminalCapture – launches a child process running a shell with a custom PS1 that prepends a timestamp. Pipes stdout/stderr to a buffer. All three modules feed into a shared EventBus that publishes to SSE subscribers.

The REST API has three endpoints:

• GET /context – SSE stream that emits {type, data} events for file changes, git diffs, and terminal lines
• GET /current-file – returns the file path of the currently focused editor window (via OS-level window detection, e.g., xdotool or osascript)
• GET /recent-diffs – returns a JSON array of the last 10 diffs

Plugins are simple JavaScript files that subscribe to the event bus and forward events to assistant-specific endpoints (e.g., Copilot's local LSP).

• File watcher performance: chokidar on very large projects (>50k files) can cause CPU spikes. Mitigation: default depth 3, configurable ignore patterns.
• Terminal capture flakiness: pty.js works differently on macOS (script), Linux (expect), Windows (winpty). Cross-platform testing was incomplete.
• SSE connection management: with multiple assistants connected, memory and event queue could grow. Need to cap connections and use backpressure.
• Security: a malicious local process could query the API. Since it's local-only, it's acceptable risk, but some may want a simple auth token.

• Should we add first-class editor extensions (VSCode, Neovim) to push active file path instead of relying on OS window detection?
• How to handle binary files in diffs? (omit them? show a placeholder?)
• Should we support multiple workspaces/sessions via a simple session ID query parameter?
• Is SSE better than WebSocket for this use case? SSE is simpler but lacks bidirectional communication (not needed here).

The weekend came and went; I got distracted by a more polished existing tool (Continue.dev) that already integrates with local context, and I realized the market for a standalone context server might be too niche. Also, I never settled on a clean terminal capture strategy that worked across macOS, Linux, and Windows—pty.js had too many quirks. So the plan stayed a plan.

The initial proof-of-concept took about 4 hours. The SSE approach worked nicely for a demo. I abandoned it because I felt the cross-platform terminal capture would take another weekend to get right, and by then the excitement had faded. Still think it's a neat idea.