aibridge-context

aibridge-context is a zero-config CLI and Node.js library that turns a project into an AI-readable workspace. It maintains a live .ai-context/ folder, serves it locally, and can optionally sync context updates through git.

Think of it as Git for AI context.

⚠️ Public AI Access Warning

When GitHub sync is enabled, your project context becomes publicly accessible via a URL.

Do NOT use this tool with sensitive data.

Quick Start

npx aibridge-context init
npx aibridge-context link-github
npx aibridge-context start

How It Works

1. Tracks project changes
2. Generates structured AI context
3. Syncs to GitHub (optional)
4. Creates a public URL
5. AI tools read this URL for context

Usage

This package exposes a CLI command:

aibridge

When using npx, always use the package name:

npx aibridge-context init

After installing globally, you can use:

aibridge init
aibridge link-github

Features

• Zero-config startup for Node.js projects
• Debounced file watching powered by chokidar
• Atomic writes to avoid corrupted JSON files
• Local Express server for AI-friendly endpoints
• Optional git auto-sync for .ai-context/*
• Library exports for embedding in other tooling

Install

npm install

To use the local CLI in this repository:

npx aibridge-context init
npx aibridge-context link-github
npx aibridge-context start

If published to npm, the package exposes the aibridge binary.

ai-context is supported as a legacy alias.

Using With AI

After enabling GitHub sync, use:

https://raw.githubusercontent.com/<user>/<repo>/main/.ai-context/state.json

This URL always returns the latest project state.

Paste this into any AI:

Use this as source of truth:
https://raw.githubusercontent.com/<user>/<repo>/main/.ai-context/state.json

You can also share:

https://raw.githubusercontent.com/<user>/<repo>/main/.ai-context/brain.txt

Typical flow:

npx aibridge-context init
aibridge link-github
npx aibridge-context start

Commands

aibridge init

Creates .ai-context/ and writes:

• state.json
• brain.txt
• context.md
• changelog.json
• config.json

aibridge start

Starts:

• A debounced file watcher
• A local Express server
• Automatic state updates on add/change/delete events

Default server port: 3333

aibridge update

Triggers a manual context refresh and optional git sync.

aibridge link-github

Prompts for a GitHub repository URL, links origin, pushes main, saves the repo URL to .ai-context/config.json, and enables public AI sync output.

Generated files

.ai-context/state.json

Tracks:

• project name
• version
• last update time
• change statistics
• recent updates
• project features
• next steps

.ai-context/brain.txt

Provides instructions any AI assistant should follow before responding.

.ai-context/context.md

Stores a human-readable summary including:

• project purpose
• detected stack
• AI usage guidance

.ai-context/changelog.json

Stores historical change entries captured by the watcher.

.ai-context/config.json

Default configuration:

{
  "port": 3333,
  "debounceMs": 600,
  "gitSync": {
    "enabled": false,
    "push": true,
    "commitMessage": "auto: update AI context",
    "remote": "origin",
    "branch": "main",
    "repoUrl": ""
  }
}

HTTP endpoints

When aibridge start is running:

• GET /state.json
• GET /brain.txt
• GET /context.md
• GET /changelog.json

Example usage

npx aibridge-context init
npx aibridge-context start

Then point your AI tool to:

• http://localhost:3333/state.json
• http://localhost:3333/context.md
• http://localhost:3333/changelog.json
• http://localhost:3333/brain.txt

Git sync

Git sync is optional and controlled by .ai-context/config.json.

Enable it like this:

{
  "gitSync": {
    "enabled": true,
    "push": true,
    "commitMessage": "auto: update AI context"
  }
}

On every successful update, the tool will attempt to:

git add .ai-context
git commit -m "auto: update AI context"
git push

Failures are handled gracefully and will not stop the watcher or server.

Library usage

const {
  initProject,
  startWatcher,
  updateProjectState,
  startServer,
  syncContextToGit
} = require('aibridge-context');

Development notes

• CommonJS is used for simplicity and broad compatibility.
• The watcher ignores node_modules, .git, and .ai-context.
• Writes are atomic via temporary-file rename.
• Updates are debounced to reduce noisy file churn.