gc-tree

              __                          
             /\ \__                       
   __     ___\ \ ,_\  _ __    __     __   
 /'_ `\  /'___\ \ \/ /\`'__\/'__`\ /'__`\ 
/\ \L\ \/\ \__/\ \ \_\ \ \//\  __//\  __/ 
\ \____ \ \____\\ \__\\ \_\\ \____\ \____\
 \/___L\ \/____/ \/__/ \/_/ \/____/\/____/
   /\____/                                
   \_/__/                                 

Global context beyond CLAUDE.md and AGENTS.md.

Attach durable, reusable context to your existing AI tools.
Manage multiple contexts like Git branches.

English | 한국어 | 简体中文 | 日本語 | Español

The problem

AI does not know you.

It does not know how you work, which terms your team uses, how one repo connects to another, or which routines you repeat without thinking. If you do not explain those things precisely, you rarely get the result you actually wanted.

So you end up doing this every session:

• Re-introduce who you are and how you work
• Re-explain the domain language your team uses
• 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

That's not because AI is stupid. It's because this kind of context is hard to keep alive inside one workspace, especially when real work moves across multiple repos and projects.

CLAUDE.md and AGENTS.md help a lot inside one repo. But once work crosses repo boundaries, shared background knowledge gets duplicated, repo relationships are hard to express, and every new session starts from too little.

gc-tree exists to remove that repetition.

Who this is for

You'll get the most out of gc-tree if you:

• Work across multiple repos (monorepo teams, platform repos, backend + frontend stacks)
• Move between multiple products, projects, or workstreams
• Find yourself re-explaining the same context at the start of every AI session
• Want AI tools to understand your working style, team terminology, architecture, and domain knowledge — not just the current file

If you only ever work in one repo and one product, you probably don't need this. CLAUDE.md or AGENTS.md is enough.

Install & quick start

npm install -g @handsupmin/gc-tree
gctree init

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

After that, your AI tool gets real SessionStart/UserPromptSubmit hook integration, so it auto-checks gc-tree before work and caches empty/no-match results for the session. Hook output injects matched document summaries directly into context — so the AI sees actual patterns and commands, not just titles. Full docs are always available on demand via gctree resolve --id <id>.

• CLI: gctree
• Requires: Node.js 20+

What gc-tree does

gc-tree sits above the repo level. It stores your working style, team terminology, repo relationships, and shared background knowledge as durable global context. Your AI tools then pull only what's relevant before each session, automatically.

gctree resolve is the compact index layer in a progressive-disclosure workflow:

• gctree resolve --query "..." → compact matches with stable IDs
• gctree related --id <match-id> → supporting docs around one match
• gctree show-doc --id <match-id> → full markdown for that doc

When no docs exist, a repo is excluded, or a query has no hits, gc-tree returns an explicit status instead of failing ambiguously.

gctree resolve --query "auth token rotation policy"

[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
[Auth & Session Conventions] JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL
[Auth & Session Conventions] show full doc: gctree show-doc --id "auth" --branch "main"

Your AI tool gets the right context. Not the whole knowledge base — just the relevant slice.

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.

Why not just use CLAUDE.md or AGENTS.md?

CLAUDE.md and AGENTS.md are great — for one repo.

The moment you have multiple repos, projects, or workstreams:

Validated performance

Two-fixture eval — DEV is visible to the tuning loop, HOLDOUT is reserved for honest reporting (different domains, hard negatives, paraphrase, mixed Korean+English queries). 38 labeled cases across 8 categories: exact-keyword, paraphrase, glossary, mixed-language, same-domain distractor, same-domain negative, cross-branch negative.

Generalization gap (DEV − HOLDOUT) = 10.0 pts. The HOLDOUT fixture is reserved for reporting only — the autoresearch loop never tunes against it. Reproduce with npm run eval:ranked; see tests/eval/RUBRIC.md for the scoring rules.

Works with Claude Code and Codex — both verified

gctree init                         # sets up ~/.gctree and global activation for your chosen provider(s)
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

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.

Codex — uses $gc-resolve-context, $gc-onboard, $gc-update-global-context skills. Verified with codex exec:

gctree status → gc_branch: main, doc_count: 2
gctree resolve --query 'NestJS DTO plainToInstance'
[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
[Backend Coding Conventions] DTO: class-transformer plainToInstance, class-validator required. Error handling: HttpException-based custom exceptions, no raw Error throws.
[Backend Coding Conventions] show full doc: gctree show-doc --id "backend-conventions" --branch "main"

Common moves

Separate contexts for separate workstreams

gctree checkout -b project-b
gctree onboard

Each gc-branch is a fully independent context lane. Switch between them like Git branches.

Pull relevant context on demand

gctree resolve --query "billing retry policy"

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

gctree update-global-context   # or: gctree update-gc / gctree ugc

Guided update flow — your AI tool asks what changed and writes the new context back to the gc-branch.

Keep gc-tree itself current

gctree update

Updates @handsupmin/gc-tree to the latest npm version, then re-scaffolds every provider you previously installed. Use it when gc-tree ships better hooks, commands, skills, or integration snippets and you want your existing setup refreshed in one move.

Scope a context to specific repos

gctree set-repo-scope --branch project-b --include   # include current repo
gctree set-repo-scope --branch project-b --exclude   # exclude current repo

gc-tree won't inject a context into repos where it doesn't belong.

How context is stored

~/.gctree/
  branches/
    main/
      index.md          ← compact index, loaded first
      docs/
        auth.md         ← full doc, read only when needed
        architecture.md
    project-b/
      index.md
      docs/
        ...
  branch-repo-map.json  ← which repos belong to which gc-branch
  settings.json         ← preferred provider, language

Context lives outside your repos — no .gitignore rules needed, no accidental commits, reusable across every project that uses the same gc-branch.

Core commands

Documentation

• Concept — docs/concept.md
• Principles — docs/principles.md
• Usage — docs/usage.md
• Local development — docs/local-development.md

Contribution

Contributions are welcome. See CONTRIBUTING.md for the development workflow and pull request checklist.

License

MIT. See LICENSE.