context-bridge

Persistent memory and replanning for Claude Code.

[context-bridge] Session context restored:
  Summary:  JWT auth ~60% done. /register works. /login is the blocker.
  Next:     Implement /login: verify bcrypt hash, sign HS256 token with
            SECRET_KEY from env, return {access_token, token_type: "bearer"}.
  Priority: SECRET_KEY must come from env — it was hardcoded in auth.py:34
  Hotspots: auth.py (5x), main.py (3x)

That block appears before Claude reads your first message. No re-explaining, no re-orientation.

The problem

Claude Code starts every session blind. It forgets what was in progress, what blocked the work, and which decisions were already made — so you re-explain it, every time. context-bridge checkpoints every task automatically and restores the right context at the start of the next session.

Install

Python 3.11+ required.

curl -fsSL https://raw.githubusercontent.com/pushkalkumar/context-bridge/main/install.sh | bash

Or manually:

pip install claude-context-bridge   # or: pip install "git+https://github.com/pushkalkumar/context-bridge.git@v0.4.0"
context-bridge install              # wires SessionStart + PostToolUse + Stop hooks
context-bridge                      # start the backend (separate terminal)

The PyPI package is claude-context-bridge; the command it installs is context-bridge. (pip install context-bridge is an unrelated package — don't use it.)

How it works

Claude Code task completes
        |
        v
PostToolUse hook
  capture git diff + task summary
  POST /sync ──> local backend (port 7723)
                   stagnation check
                   planner: next_instruction + priority_focus
        |
        v
Session ends ──> Stop hook ──> end-of-session snapshot
        |
Next session starts
        |
        v
SessionStart hook
  known project: restore summary, next step, constraint, hotspots
  new project:   inject cross-project developer profile
        |
        v
Claude receives context before your first message

Everything is local: a SQLite database in ~/.context-bridge/ and a FastAPI server on 127.0.0.1. The planner picks the best available tier:

Features

Commands

context-bridge             # start the backend server
context-bridge install     # (re)install hooks and skill
context-bridge uninstall   # remove hooks and skill (keeps the database)
context-bridge list        # all projects with checkpoint counts and type breakdown
context-bridge status      # backend health, planner tier, velocity and embedding status
context-bridge diff [pid]  # before/after of the last two task checkpoints
context-bridge export      # write a CLAUDE.md-compatible Markdown snapshot

context-bridge list:

  my-api/main              12 checkpoints   2h ago
  my-api/feature-auth       4 checkpoints  14h ago   ⚠ stagnant (3x)
  data-pipeline/main        8 checkpoints   3d ago

Configuration

All variables can go in ~/.context-bridge/.env.

To enable semantic search, install the extra and set either key:

pip install "claude-context-bridge[semantic]"
export VOYAGE_API_KEY=...   # or ANTHROPIC_API_KEY

Why not just use CLAUDE.md?

• CLAUDE.md is static — context-bridge updates after every task.
• CLAUDE.md is manual — context-bridge is automatic; you never write the summary yourself.
• CLAUDE.md can't detect stagnation, surface recurring blockers, or learn across projects.

They compose: CLAUDE.md holds your conventions, context-bridge holds your state.

Manual usage

The hooks are optional. The API works with plain HTTP — see docs/manual-sync.md for project ID derivation, manual checkpointing, and structured event examples.

Contributing

git clone https://github.com/pushkalkumar/context-bridge
cd context-bridge
pip install -e ".[dev]"
pytest

97 tests cover every endpoint and feature. The active package is server/ (hooks in server/hook.py, planner tiers in server/planner.py). Issues and PRs welcome: open issues.

License

MIT