choobi

docs that follow your work!

Choobi is a docs agent for Git repositories. After you commit a code change - new features, architectures changes -, choobi helps you make sure the .md files are up to date without you worrying: choobi diligently tracks your code diffs and decides whether the change belongs in your docs and where and writes a small docs-only follow-up commit in a background.

You can also summon and chat with choobi from Claude Code or Codex, or you can run commands directly from the CLI.

Choobi's body lives in a UI window launched by typing choobi in your CLI.

Install

git clone https://github.com/ilovehhhyn/choobi.git
cd choobi
python3 -m pip install -e .
choobi help

If your shell cannot find choobi after installation, add Python's user scripts directory to your PATH. From the source checkout, you can also run commands as python3 -m choobi.

Then, set up Choobi once:

choobi auth claude        # or: choobi auth codex
choobi install

Choobi uses exactly one active runtime. Authenticating another runtime switches to it only after the new login succeeds; a cancelled or failed login leaves the previous runtime active. Having one authenticated runtime is enough.

Install per repo:

Initialize each repository you want Choobi to follow:

cd ~/code/my-project
choobi init
choobi                     # to view ui window 

Now commit code as usual! Choobi follows and works meticulously.

Highlights

• Works with your Git workflow. Initialize choobi in a repository once and you are good to go! work and commit normally.
• Finds the right document. Choobi considers the complete change and the repository's Markdown documentation before choosing an owner.
• Keeps edits focused. It updates the smallest relevant part of one document and rejects changes that cross its write boundary.
• Protects future direction or PRDs. It treats plans as intent, not shipped behavior, and leaves them unchanged while surfacing an LLM-written owner-review message when code contradicts them.
• Fits your coding setup. Use the automatic hook, a coding-agent command, or the CLI.
• Leaves an audit trail. Every update, flag, no-op, and failure is available in the CLI and UI changelog.

There are three ways to ask Choobi to work:

1. Commit normally. The post-commit hook reviews the change automatically.
2. Ask your coding agent. In Claude Code or Codex, say something like: “choobi update the API docs based on what we decided.”
3. Run the CLI. For example, choobi update --commit HEAD reviews the latest commit.

Commands

Command	What it does
choobi	Open the native desktop window. Alias: choobi ui.
choobi init	Install the post-commit hook and project skill in the current repository.
choobi install	Install the Choobi skill for Claude Code and Codex.
choobi auth [claude|codex]	Show runtime status, or authenticate and select one active runtime.
choobi update [DOC] SCOPE [--chat] [-- TEXT]	Run a documentation review, optionally pinned to one document.
choobi status	Show pending, flagged, failed, and no-op work plus the repository checkpoint.
choobi docs	List the documents Choobi can update in the current repository.
choobi changelog [-n N] [--all] [--status S]	Browse recent Choobi activity.
choobi show <id>	Show one activity record and its exact patch.
choobi style	Print the resolved documentation style guide.
choobi pr create	Create a pull request with gh and annotate it when Choobi updated docs.
choobi help [COMMAND]	Show the full command reference or help for one command.

Manual update examples

Let Choobi choose the document for the latest commit:

choobi update --commit HEAD

Pin the review to a document or review a larger scope:

choobi update docs/api.md --commit HEAD
choobi update --range main..HEAD
choobi update --pr 42

Review staged or working-tree changes without associating them with a commit:

choobi update --detached --staged
choobi update --detached --working
choobi update docs/api.md --detached -- "clarify the retry backoff"

A manual update must have one commit-based scope (--commit, --range, or --pr) or use --detached. Run choobi help update for the complete grammar.

Use the desktop window

Launch the window from any terminal:

choobi

On first launch, enter your name, choose Claude or Codex, and select the sign-in button. Choobi opens the chosen runtime's browser login when needed and returns to the app when authentication succeeds.

The window is for configuration and inspection:

• instructions — choose a repository that has run choobi init, edit its SOP, or view and regenerate Choobi's read-only knowledge base for that repository.
• style — edit the complete default style.md as your personal style guide, or use return to default to discard your copy and reload the bundled version.
• changelog — watch Choobi's work, open individual runs, and inspect summaries, reasons, commit hashes, and patches.
• book icon — open the command reference.
• terminal icon — hover to see the current runtime and readiness. Click it to authenticate and switch to Claude or Codex. The current runtime changes only after the new runtime is ready.

Updates themselves run through commits, the CLI, or the coding-agent skill; the window does not start an update.

Choose what Choobi can edit

By default, Choobi can update README.md, HOW_CHOOBI_WORKS.md, Markdown files under docs/, and *-plan.md files. Use the repository SOP in the instructions tab to describe what should be documented and where. New-document creation is enabled by default: when a change ships a genuinely new feature that no existing document owns, Choobi proposes a new page under the SOP's create_roots (defaulting to docs/public/features/, docs/public/reference/, and docs/internal/features/). Every proposed new document must first pass a dedicated model review that approves or rejects the creation; a rejected proposal writes nothing. Set allow_create: false in the SOP to turn creation off entirely (a change that then needs a new document is reported as a documentation gap), or narrow create_roots to restrict where new pages may live.

Use the style tab for preferences that should apply across repositories, such as voice, terminology, structure, and verbosity.

Let Choobi read the repo (optional)

By default Choobi decides from a single bounded prompt and the model only emits text. You can opt into letting the runtime pull additional tracked repository files on demand before it decides, which helps on large repositories where the bounded context is not enough. Enable it by setting "tools": true in ~/.choobi/config.json, or per run with CHOOBI_TOOLS=1.

The read boundary is the same for every runtime — Claude and Codex share one Choobi-owned read loop, so neither CLI runs its own agent: the model can read only files already committed to this repository, never anything outside the repository and never untracked or gitignored files such as a local .env. Any secret that is already committed is still blocked from the written document by the output scanner.

Prerequisites

• Python 3.9 or newer
• Git
• At least one supported runtime CLI installed and available on PATH: claude or codex
• Optional: the GitHub CLI (gh) for choobi pr create

Learn more

• How Choobi works — runtime vs. harness, document ownership, safety boundaries, local storage, current limits, and development.
• Build plan — the full product and implementation contract.