{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.png\" width=\"120\" alt=\"brg logo\">\n</p>\n\n<h1 align=\"center\">brg</h1>\n\n<p align=\"center\"><b>Never explain yourself twice.</b></p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/brg-cli\"><img src=\"https://img.shields.io/npm/v/brg-cli.svg\" alt=\"npm version\"></a>\n  <a href=\"https://www.npmjs.com/package/brg-cli\"><img src=\"https://img.shields.io/npm/dm/brg-cli.svg\" alt=\"npm downloads\"></a>\n  <a href=\"https://github.com/brghq/brg/actions/workflows/ci.yml\"><img src=\"https://github.com/brghq/brg/actions/workflows/ci.yml/badge.svg\" alt=\"CI status\"></a>\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/npm/l/brg-cli.svg\" alt=\"MIT license\"></a>\n  <a href=\"./CONTRIBUTING.md\"><img src=\"https://img.shields.io/badge/PRs-welcome-C9762F.svg\" alt=\"PRs welcome\"></a>\n</p>\n\n`brg` is a git-style CLI orchestrator that switches you between AI coding\nCLIs — Claude Code and Codex today — without losing the context of what\nyou were doing.\n\n## Why brg\n\nEvery multi-tool AI workflow runs into the same problem: you re-explain\nthe project, the decisions, the open threads, every time you switch\ntools. `brg` carries that context with you instead, the way `git`\ncarries your repo's history instead of making you retype it.\n\n## Demo\n\nReal output from the CLI — `brg init` → `brg checkpoint` → `brg log` →\n`brg status` in a fresh project:\n\n```console\n$ brg tools list\nclaude     Claude Code    installed, authenticated\ncodex      Codex          not installed\n\n$ brg init\n✓ Initialized .brg/ in /path/to/your-project\n\n$ brg checkpoint \"wired up the auth middleware\" --tool claude\n✓ Checkpoint saved.\n\n$ brg log\n2026-08-10T11:26:57.784Z  claude  wired up the auth middleware\n\n$ brg status\nactive branch:     main\nactive tool:       (not set)\nlast checkpoint:   just now\nsummary size:      153 bytes\ncheckpoints today: 1\n```\n\n## Installation\n\n```bash\nnpm install -g brg-cli\n```\n\nRequires **Node.js 18+**. The npm package is named `brg-cli` — npm's\nregistry blocks the bare name `brg` as too similar to existing packages —\nbut the command it installs is just `brg`.\n\n## Quickstart\n\n```bash\nbrg setup           # install/authenticate the AI CLIs you want to use\nbrg init             # create a .brg/ directory in your project\nbrg switch claude    # hand off to Claude Code with your project context loaded\n```\n\n- `brg setup` walks you through installing and logging into each AI CLI —\n  idempotent, so re-running it skips anything already set up.\n- `brg init` creates `.brg/` in the current directory and activates a\n  default branch (see \"How it works\" below).\n- `brg switch claude` reads the active branch's rolling summary, hands\n  off full terminal control to `claude` with that context loaded, then\n  exits.\n\nFor the full command reference and detailed guides — every flag, how\ncontext/checkpoints/sessions work, common workflows, troubleshooting, and\nuninstall instructions — see [docs/USER_GUIDE.md](./docs/USER_GUIDE.md).\n\n## Command reference\n\n| Command | Description | Example |\n|---|---|---|\n| `brg setup` | Interactive wizard to install/authenticate supported AI CLIs | `brg setup` |\n| `brg tools list` | List which AI CLIs are registered, installed, and authenticated | `brg tools list` |\n| `brg init` | Create a `.brg/` directory in the current project | `brg init` |\n| `brg switch <tool>` | Hand off to an AI CLI, carrying project context with you | `brg switch claude` |\n| `brg switch <tool> -f, --fresh` | Same, but skip context — start a completely clean session | `brg switch codex --fresh` |\n| `brg checkpoint <message>` | Snapshot current state with a message, like `git commit` | `brg checkpoint \"fixed the auth bug\" --tool claude` |\n| `brg checkpoint <message> --tool <name>` | Attribute the checkpoint to a specific tool | `brg checkpoint \"...\" --tool codex` |\n| `brg log` | Print a timeline of checkpoints for the active branch | `brg log` |\n| `brg log --all` | Every branch's checkpoints, flat, tagged by branch | `brg log --all` |\n| `brg log --graph` | Render the active branch's checkpoint graph (`--all` for every branch) | `brg log --graph --all` |\n| `brg status` | Show active context branch, actual git branch (with a mismatch warning if they diverge), last checkpoint, summary size, today's checkpoint count | `brg status` |\n| `brg context show` | Print the active branch's rolling summary to stdout | `brg context show` |\n| `brg checkout <name>` | Create (if new) and switch to a brg context branch — see below | `brg checkout feature-payments` |\n| `brg diff <name>` / `brg diff <a> <b>` | Fact differences: active branch vs `<name>`, or two explicit branches | `brg diff main feature-payments` |\n| `brg merge <source>` | Merge a branch's context into the currently active branch | `brg merge feature-payments` |\n| `brg mcp` | Start brg's MCP server over stdio | `brg mcp` |\n| `brg --version` | Print the installed version | `brg --version` |\n| `brg --help` | Show all commands | `brg --help` |\n\nRun `brg <command> --help` for any command's exact flags, or see\n[docs/USER_GUIDE.md](./docs/USER_GUIDE.md) for a full breakdown of every\nflag with examples.\n\n`brg checkout <name>` is the single command for both creating and\nswitching context branches — there's no separate `brg branch`, and it\nnever errors on an existing name. A brg branch's linked git branch is\noptional: **the active brg branch is always the source of truth for\ncontext**, never the currently checked-out git branch. See\n[docs/USER_GUIDE.md](./docs/USER_GUIDE.md#brg-checkout-name) for the full\nflag reference and examples.\n\n## How it works\n\n`brg` keeps everything in plain, local files — no database, no server.\nContext is organized into **branches** — you can fork a separate thread\nof context to explore an angle without polluting the one you're already\non, optionally linked to a real git branch, optionally not.\n\n```\n.brg/\n├── objects/            Immutable, content-addressed checkpoint objects.\n├── branches/<name>/\n│   ├── intent.md         Restated goal for this branch, set at creation.\n│   ├── summary.md         Rolling summary, regenerated on every\n│   │                       checkpoint. This is what gets injected on\n│   │                       `brg switch` and shown by `brg context show`.\n│   └── facts.json         Structured facts (used by `brg diff`/`brg merge`).\n├── refs/\n│   ├── active           Which branch is currently active.\n│   └── git-map.json      Branch -> linked git branch, if any.\n└── config.yaml          Project-level settings (default tool, context\n                           strategy).\n```\n\nA **checkpoint** is a snapshot of where the project stands — a message\nyou write (git-commit style), recorded on the active branch. It's\ngenerated via a tiered fallback: trying the active tool's own session\nsummary first, falling back to reading its transcript straight off disk\nif that's unavailable (e.g. it just hit a quota limit), and falling back\nto a plain message as a last resort. A **switch** first auto-checkpoints\nagainst whatever tool you were last using, then hands the active\nbranch's freshly regenerated summary to the target tool as its starting\ncontext — so you don't have to re-explain what you were doing, even if\nthe previous session ended abruptly.\n\nEverything is plain, git-diffable JSON/Markdown — open any branch's\n`summary.md` in a text editor and read its history without running `brg`\nat all. See [docs/CONTEXT_VERSIONING.md](./docs/CONTEXT_VERSIONING.md)\nfor the full data model and design.\n\n## Supported AI CLIs\n\n- [Claude Code](https://claude.com/claude-code)\n- Codex\n\nSupport for more CLIs is community-extensible — adding one means adding a\nsingle adapter file under `src/tools/` that implements the `ToolAdapter`\ninterface, no changes needed elsewhere in the codebase. Gemini CLI and\nOpenCode are natural candidates for a community-contributed adapter. See\n[CONTRIBUTING.md](./CONTRIBUTING.md).\n\nA [Claude Code plugin](./plugin/) is also available — `SessionStart`/\n`PreCompact` hooks plus `brg mcp` bundled together. Install it with\n`/plugin marketplace add https://github.com/brghq/brg` inside Claude\nCode, then install `brg` from that marketplace — see\n[plugin/README.md](./plugin/README.md) for details. Codex has no\nequivalent plugin system today.\n\n## Roadmap\n\nPhase 1 (auto-checkpoint on `brg switch`, tiered context summarization)\nand all of Phase 2 (context branching via `brg checkout`, `diff`/`merge`/\n`log --graph`, structured fact extraction, an MCP server, a Claude Code\nplugin, `brg dashboard`, and `brg export`) are shipped. Cloud sync is a\nfuture paid tier, further out; the CLI itself stays free and\nopen-source forever. Full detail in [ROADMAP.md](./ROADMAP.md).\n\n## Contributing\n\nContributions are welcome — bug reports, feature ideas, docs fixes, and\ncode all help. See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup,\nthe PR flow, and code style, and\n[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for how we work together.\n\n## License\n\n[MIT](./LICENSE)\n\n## Author\n\nCreated and maintained by [Shivam Shukla](https://github.com/brghq).\n",
  "bytes": 9056,
  "sha": "a69f6c0896c7524528ec85d3ba81eb3c4713aba0785550ff7ffd066cb649832a",
  "repo_slug": "brghq/brg",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_brghq_brg_706ca3ec/readme"
}