DEV Community

Rohit Madas
Rohit Madas

Posted on

I built an open source context layer for AI coding tools — here's how it works

#opensource #typescript #ai #devtools

## The problem

Every AI coding session starts blank.

You open Cursor or Claude Code and before you can ask anything
useful, you spend five minutes re-explaining your project. Same
stack. Same goals. Same conventions. Every time.

I built ctxpilot to fix this permanently.

What it is

ctxpilot is a CLI tool and MCP server that:

  1. Scans your codebase with AI and builds a Living Context Document
  2. Injects that document into Cursor, Claude Code, Codex, and Windsurf via MCP
  3. Auto-updates the document after every git commit via a background daemon

The demo that convinced me

Fresh Codex session. Private React Native project. Zero context pasted.

Asked: "What is this project and what am I working on?"

Codex answered with exact file paths, line numbers, and identified
a specific bug in the cart validation logic — minimum quantity
hardcoded in multiple places, silently coerced with
Math.max(quantity, 6) in cart.ts#L40.

That answer came from the LCD. Not from Codex exploring files.

Three commands

\`bash
npm install -g @ctxpilot/ctxpilot

ctx init # scan codebase, generate LCD
ctx setup # configure all AI clients
ctx watch # start auto-update daemon
`\

How the auto-update works

ctx watch starts a background daemon that watches
.git/refs/heads/ via Chokidar. When a new commit is detected,
it waits 30 seconds then runs ctx update.

ctx update:

  1. Reads git diff since last update
  2. Extracts signals (decisions, completed work, new patterns)
  3. Calls Claude to rewrite the LCD incorporating new signals
  4. Archives any removed content
  5. Writes the updated LCD

The result: every session starts with fresh context. Zero manual work.

How ctx setup works

Running ctx setup inside a project:

  • Writes MCP server config to ~/.claude/claude_desktop_config.json
  • Writes MCP server config to ~/.codex/config.toml
  • Writes MCP server config to ~/.cursor/mcp.json
  • Writes MCP server config to ~/.windsurf/mcp.json
  • Creates CLAUDE.md with "read LCD first" instructions
  • Creates .cursor/rules/ctxpilot.mdc with alwaysApply: true
  • Creates .windsurf/rules/ctxpilot.md
  • Creates .agents/skills/ctxpilot/SKILL.md for Codex

All upsert-safe — existing configs are never overwritten, only
the ctxpilot entry is added or updated.

The LCD structure

\`markdown

Living Context Document

Project Identity

GiftExpress - React Native mobile e-commerce app...

Active Goal

Cart validation refactoring...

Technology Stack

  • React Native 0.80.0 with TypeScript 5.0.4
  • Zustand 5.0.6 for state management ...

Architecture Patterns

...

In Progress

  • Cart validation constants extraction

Recently Completed

  • Secure session management ...

Code Conventions

  • Strict TypeScript
  • Named exports ... `\

Technical stack

  • TypeScript, Node.js 20, ESM
  • Commander.js for CLI
  • Chokidar for file watching
  • simple-git for git integration
  • @modelcontextprotocol/sdk for MCP server
  • Anthropic SDK + OpenAI SDK (user's choice of provider)
  • @iarna/toml for safe TOML merging

Try it

\bash
npm install -g @ctxpilot/ctxpilot
\\

GitHub: github.com/fewknowme/ctxpilot
Website: fewknowme.github.io/ctxpilot

Open source, MIT license. Issues and PRs welcome.

Top comments (0)