branch-context

Overview • Features • Motivation • Quick Start • Commands • Configuration • Contributing • License

🎺 Overview

Git branch context manager that automatically syncs context folders across branches. Each branch gets an isolated context directory containing notes, metadata, and files that follow the branch lifecycle.

How it works

  git checkout feature/login
              │
              ▼
      ┌────────────────┐
      │  post-checkout │
      │    git hook    │
      └───────┬────────┘
              │
              ▼
    context exists? ──NO──▶ copy template (by prefix rules)
              │                     │
             YES                    │
              │◀────────────────────┘
              ▼
    ┌───────────────────────────────────────────┐
    │ _branch/ → .bctx/branches/feature-login   │
    └───────────────────────────────────────────┘
              │
              ▼
    ┌─────────────────────────────────┐
    │ • update meta.json (commits)    │
    │ • update <bctx:*> tags          │
    │ • play sound (if enabled)       │
    └─────────────────────────────────┘

⭐ Features

• Isolated contexts - per-branch folder, _branch/ symlink to current
• Auto-sync - git hook triggers on checkout
• Templates - per-prefix rules (feature/, bugfix/, etc.)
• Meta tracking - commits, changed files, timestamps
• Context tags - <bctx:commits> and <bctx:files> auto-updated

❓ Motivation

When working on multiple branches, it's easy to lose track of what you were doing. This tool helps you:

• Keep notes, TODOs, and context organized per branch
• Provide context to AI coding assistants (Claude Code, Codex, Cursor, etc.) via _branch/context.md
• Track commits and changed files automatically with <bctx:*> tags

The _branch/ symlink gives AI tools a stable path to read your current branch context, helping them understand what you're working on.

🚀 Quick Start

Install:

brew install pipx         # if not installed (macOS/linux)
pipx install branch-ctx   # or: pip install branch-ctx

Setup in your repo:

cd your-repo
bctx init                        # creates .bctx/ + installs hook

git checkout -b feature/new      # auto-creates context from template
cat _branch/context.md

📖 Commands

bctx init                          # initialize + install hook
bctx sync                          # sync context + update meta/tags
bctx status                        # show status and health
bctx branches list                 # list all branch contexts
bctx branches prune                # archive orphan contexts
bctx template                      # select template interactively
bctx template feature              # apply feature template
bctx completion zsh                # generate shell completion
bctx uninstall                     # remove hook

Alias: branch-ctx works too.

⚙️ Configuration

Structure

.bctx/
├── config.json
├── templates/
│   ├── _default/            # fallback template
│   │   └── context.md
│   └── feature/             # template for feature/* branches
│       └── context.md
└── branches/                # gitignored
    ├── meta.json            # branch metadata (commits, files, timestamps)
    ├── main/
    │   └── context.md
    └── feature-login/
        ├── context.md
        └── base_branch      # optional per-branch base override

_branch -> .bctx/branches/main/   # symlink to current

Config file

.bctx/config.json:

{
  "default_base_branch": "origin/main",
  "sound": true,
  "sound_file": "/path/to/custom.wav",
  "template_rules": [
    {"prefix": "feature/", "template": "feature"},
    {"prefix": "bugfix/", "template": "bugfix"}
  ]
}

Key	Description
default_base_branch	base branch for diff/commits (default: origin/main)
sound	play sound on sync (default: false)
sound_file	custom sound file (default: bundled sound)
template_rules	per-prefix template mapping (fallback: _default)

Per-branch base override: create _branch/base_branch with branch name.

Shell Completion

# zsh - add to ~/.zshrc
eval "$(bctx completion zsh)"

# bash - add to ~/.bashrc
eval "$(bctx completion bash)"

# fish
bctx completion fish | source

🤝 Contributing

make install    # venv + deps + pre-commit
make test       # run tests
make format     # ruff fix + format
make check      # validate ruff rules
make build      # build package
make clean      # remove venv + dist

Dev alias:

ln -sf $(pwd)/.venv/bin/bctx ~/.local/bin/bctxd   # install
rm ~/.local/bin/bctxd                             # remove

📜 License

This project is licensed under the MIT License.