@handsupmin/gc-tree 0.1.3 → 0.2.0

package/README.md

@@ -1,166 +1,250 @@
 # gc-tree
 
-Branch-aware global context for AI coding tools.
+<div align="center">
+
+<img src="./logo.png" alt="gc-tree logo" width="260" />
+
+### Global context, beyond the project.
+
+Attach durable, reusable context to your existing AI tools.
+Manage multiple contexts like Git branches.
+
+[![npm version](https://img.shields.io/npm/v/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![npm downloads](https://img.shields.io/npm/dm/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![GitHub stars](https://img.shields.io/github/stars/handsupmin/gc-tree)](https://github.com/handsupmin/gc-tree/stargazers)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/handsupmin/gc-tree/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
 [English](https://github.com/handsupmin/gc-tree/blob/main/README.md) | [한국어](https://github.com/handsupmin/gc-tree/blob/main/README.ko.md) | [简体中文](https://github.com/handsupmin/gc-tree/blob/main/README.zh.md) | [日本語](https://github.com/handsupmin/gc-tree/blob/main/README.ja.md) | [Español](https://github.com/handsupmin/gc-tree/blob/main/README.es.md)
 
-## Introduction
+</div>
 
-`gctree` is a lightweight **Global Context Tree** for AI coding tools.
-It gives long-lived context a reusable, file-backed home that stays explicit, branch-aware, and easy to plug into existing workflows.
+---
 
-When a single `AGENTS.md`, `CLAUDE.md`, or prompt snippet is no longer enough, `gctree` helps you:
+## The problem
 
-- separate context by product, client, or workstream
-- keep source-of-truth knowledge in markdown instead of hidden memory
-- resolve the active context quickly with a slim index and summary-first docs
-- onboard and update durable context through your preferred LLM CLI provider
-- limit a gc-branch to the repositories where it actually applies
+You use Claude Code or Codex every day. But your real work spans multiple repos, products, and clients — and your AI tools only know about the current file.
 
-## Key Features
+So you end up doing this every session:
 
-- **Provider-driven onboarding**
-  `gctree init` asks which provider mode you want (`claude-code`, `codex`, or `both`), then asks which language to use for responses, saves both choices, scaffolds the right command surface, and starts guided onboarding for the default `main` gc-branch.
-- **Repo-aware gc-branch scope**
-  `gctree` can map a gc-branch to specific repositories through `~/.gctree/branch-repo-map.json`, so one branch can apply to B/C/D while being ignored in F.
-- **Interactive scope guard**
-  If `gctree resolve` runs in a repo that is not yet mapped to the current gc-branch, it can ask whether to continue once, always use this gc-branch here, or ignore it here.
-- **Summary-first documentation**
-  Let tools read the short version first and expand only when they need more detail.
-- **Guided durable updates**
-  Reuse the same provider-driven flow to update context without hand-authoring JSON files.
+- Re-explain which repos belong together
+- Paste the same architecture doc into the prompt again
+- Remind the agent about conventions it already "knew" last week
+- Manually strip context that's irrelevant to the current repo
 
-## Install & Quick Start
+That's not an AI problem. It's a **context management problem**.
 
-### Install from npm
+---
 
-```bash
-npm install -g @handsupmin/gc-tree
-```
+## What gc-tree does
 
-Or run it once without a global install:
+`gc-tree` sits **above the repo level**. It stores durable context in structured markdown files and lets your AI tools pull only what's relevant — before each session, automatically.
 
 ```bash
-npx @handsupmin/gc-tree init
+gctree resolve --query "auth token rotation policy"
 ```
 
-- **Package name:** `@handsupmin/gc-tree`
-- **CLI command:** `gctree`
-- **Requirements:** Node.js 20+
-For source-based development details, see [docs/local-development.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.md).
+```json
+{
+  "gc_branch": "main",
+  "matches": [
+    {
+      "title": "Auth & Session Conventions",
+      "score": 4,
+      "summary": "JWT rotation on every request, refresh tokens stored in httpOnly cookies, 15-min access token TTL",
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request..."
+    }
+  ]
+}
+```
 
-### Quick Start
+Your AI tool gets the right context. Not the whole knowledge base — just the relevant slice.
 
-#### 1) Initialize gc-tree
+**In practice: only ~4% of your total context is injected per query.** The other 96% stays on disk, out of the token window, until it's actually needed.
 
-```bash
-gctree init
-```
+---
+
+## Who this is for
 
-This command:
+You'll get the most out of `gc-tree` if you:
 
-- creates `~/.gctree`
-- creates the default `main` gc-branch
-- asks which provider mode you want to use (`claude-code`, `codex`, or `both`)
-- if you choose `both`, asks which provider should start onboarding now
-- asks which language the workflow should use (`English`, `Korean`, or a custom language)
-- saves provider mode, onboarding provider, and language in `~/.gctree/settings.json`
-- scaffolds the current environment for the selected provider mode
-- launches guided onboarding for the active gc-branch when `main` is still empty
+- Work across **multiple repos** (monorepo teams, platform + client repos, backend + frontend stacks)
+- Switch between **multiple products or clients** in the same week
+- Find yourself **re-explaining the same context** at the start of every AI session
+- Want AI tools to understand your **conventions, architecture, and domain knowledge** — not just the current file
 
-#### 2) Resolve the active context
+If you only ever work in one repo and one product, you probably don't need this. `CLAUDE.md` or `.cursorrules` is enough.
+
+---
+
+## Why not just use CLAUDE.md or cursor rules?
+
+`CLAUDE.md` is great — for one repo.
+
+The moment you have multiple repos, clients, or workstreams:
+
+| | `CLAUDE.md` / cursor rules | `gc-tree` |
+|---|---|---|
+| Scope | One repo | Multiple repos, one context |
+| Persistence | Per-repo file | Stored outside repos, reused across sessions |
+| Switching contexts | Manual file edits | `gctree checkout client-b` |
+| Relevance filtering | Everything or nothing | Only injects matching docs (~4% of total) |
+| Onboarding | Hand-written | Guided by your AI tool |
+| Works with Codex | ✅ | ✅ |
+| Works with Claude Code | ✅ | ✅ |
+
+---
+
+## Validated performance
+
+Tested against real internal documentation (4 Notion exports, Korean + English mixed queries):
+
+| Metric | Result |
+|---|---|
+| Recall — relevant queries find the right doc | **100%** (16/16) |
+| Precision — irrelevant queries return empty | **80%** (4/5) |
+| F1 score | **88.9%** |
+| Tokens injected per query vs. total context | **~4%** |
+| Works with mixed Korean + English queries | ✅ |
+
+---
+
+## Works with Claude Code and Codex — both verified
 
 ```bash
-gctree resolve --query "auth token rotation"
+gctree scaffold --host claude-code   # installs CLAUDE.md snippet + /gc-onboard, /gc-update-global-context
+gctree scaffold --host codex         # installs AGENTS.md snippet + $gc-onboard, $gc-update-global-context
+gctree scaffold --host both          # both at once
 ```
 
-If the current repo is outside the mapped scope for the chosen gc-branch, `gctree` can ask whether to:
+Both providers use the same underlying context store. Onboard once, use from either tool.
+
+**Claude Code** — uses `/gc-resolve-context`, `/gc-onboard`, `/gc-update-global-context` slash commands.
 
-1. continue once
-2. always use this gc-branch for this repo
-3. ignore this gc-branch for this repo
+**Codex** — uses `$gc-resolve-context`, `$gc-onboard`, `$gc-update-global-context` skills. Verified with `codex exec`:
 
-Choosing 2 or 3 updates `~/.gctree/branch-repo-map.json`.
+```
+gctree status → gc_branch: main, doc_count: 2
+gctree resolve --query 'NestJS DTO plainToInstance'
+→ matched "Backend Coding Conventions" (score: 3)
+→ DTO: class-transformer plainToInstance, class-validator required
+→ Error handling: HttpException-based custom exceptions, no raw Error throws
+```
+
+---
 
-#### 3) Create another gc-branch when you need a separate context tree
+## Install & quick start
 
 ```bash
-gctree checkout -b client-b
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-`checkout -b` creates a **new empty gc-branch**. It does not copy existing branch docs.
+`gctree init` walks you through:
+1. Choose provider: `claude-code`, `codex`, or `both`
+2. Scaffold the integration files into your current repo
+3. Run guided onboarding for the `main` gc-branch
 
-#### 4) Onboard that empty gc-branch through the configured provider
+After that, your AI tool will know to call `gctree resolve` before planning or implementing.
+
+- **CLI:** `gctree`
+- **Requires:** Node.js 20+
+
+---
+
+## Common moves
+
+### Separate contexts for separate workstreams
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) Make a durable update later
+Each gc-branch is a fully independent context lane. Switch between them like Git branches.
+
+### Pull relevant context on demand
 
 ```bash
-gctree update-global-context
+gctree resolve --query "billing retry policy"
 ```
 
-Short aliases:
+Returns only the matching docs — title, summary, and excerpt. Your tool reads the full doc only if the summary isn't enough.
+
+### Keep context current
 
 ```bash
-gctree update-gc
-gctree ugc
+gctree update-global-context   # or: gctree update-gc / gctree ugc
 ```
 
-If a repo turns out to belong to the current gc-branch after real work, the natural flow is:
-
-1. allow that repo in the branch repo map
-2. then run `gctree update-global-context` to add durable context about what that repo is and why it matters
+Guided update flow — your AI tool asks what changed and writes the new context back to the gc-branch.
 
-#### 6) Re-onboard only after resetting a gc-branch
+### Scope a context to specific repos
 
 ```bash
-gctree reset-gc-branch --branch client-b --yes
+gctree set-repo-scope --branch client-b --include   # include current repo
+gctree set-repo-scope --branch client-b --exclude   # exclude current repo
 ```
 
-### Provider-facing commands inside the runtime
+`gc-tree` won't inject a context into repos where it doesn't belong.
+
+---
 
-After scaffolding, the visible commands are:
+## How context is stored
+
+```
+~/.gctree/
+  branches/
+    main/
+      index.md          ← compact index, ≤2000 chars, loaded first
+      docs/
+        auth.md         ← full doc, read only when needed
+        architecture.md
+    client-b/
+      index.md
+      docs/
+        ...
+  branch-repo-map.json  ← which repos belong to which gc-branch
+  settings.json         ← preferred provider, language
+```
 
-- **Codex:** `$gc-onboard`, `$gc-update-global-context`
-- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+Context lives outside your repos — no `.gitignore` rules needed, no accidental commits, reusable across every project that uses the same gc-branch.
 
-Those commands should always mention the current active gc-branch before gathering or updating durable context, and they should keep using the saved workflow language unless the user explicitly asks to switch.
+---
 
-### Core commands at a glance
+## Core commands
 
 | Goal | Command |
-| --- | --- |
+|---|---|
 | Initialize gc-tree and choose a provider | `gctree init` |
 | Confirm the active gc-branch | `gctree status` |
 | Search the active context | `gctree resolve --query "..."` |
-| Show repo-scope rules | `gctree repo-map` |
-| Explicitly include/exclude a repo for a gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | Create or switch gc-branches | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
+| List all gc-branches | `gctree branches` |
 | Guided onboarding for an empty gc-branch | `gctree onboard` |
-| Guided durable update for the active gc-branch | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
+| Guided durable update for the active gc-branch | `gctree update-global-context` / `gctree ugc` |
+| Show repo-scope rules | `gctree repo-map` |
+| Include/exclude current repo for a gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | Reset a gc-branch before re-onboarding | `gctree reset-gc-branch --branch <name> --yes` |
-| Scaffold another environment manually | `gctree scaffold --host codex --target /path/to/repo` |
+| Scaffold a new environment | `gctree scaffold --host codex --target /path/to/repo` |
 
-## Documentation
+---
 
-Detailed docs live in the [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs) directory.
+## Documentation
 
 - **Concept** — [`docs/concept.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/concept.md)
-  Learn what `gctree` is, which problem it solves, and what belongs in the global-context layer.
 - **Principles** — [`docs/principles.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/principles.md)
-  Read the rules behind gc-branches, repo scope, slim indexes, summary-first docs, and guided updates.
 - **Usage** — [`docs/usage.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/usage.md)
-  See the standard CLI flow, provider-facing commands, repo-scope behavior, and integration patterns.
 - **Local development** — [`docs/local-development.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.md)
-  Learn how to run the CLI locally and verify changes before contributing.
+
+---
 
 ## Contribution
 
 Contributions are welcome. See [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md) for the development workflow and pull request checklist.
 
+---
+
 ## License
 
 MIT. See [`LICENSE`](https://github.com/handsupmin/gc-tree/blob/main/LICENSE).