A Claude Code plugin

Every session starts knowing where to look

Globu registers the knowledge bases on your machine and tells Claude Code which to read and where to write back.

What Claude reads when a session startsglobu hook session-start

# Globu knowledge shards

These knowledge sources are registered on this machine. When a task touches a shard's area, read its entry file first and follow links from there.

- product (okf, writable)
  - What: Decision records, feature specs, the roadmap and the API contract.
  - Use when: Why something was decided, what a feature should do, or checking a decision before changing behaviour in a code repo.
  - Entry: ~/Projects/product/docs/index.md
- backend (okf, ask first)
  - What: The API's request pipeline, data model, sessions and migrations.
  - Use when: Changing or calling an endpoint, the data model or a migration.
  - Entry: ~/Projects/backend/docs/index.md
- infrastructure (okf, read-only)
  - What: Terraform for the environments, Cloud Run services and backups.
  - Use when: Anything about environments, deployment, secrets or restore.
  - Entry: ~/.globu/clones/infrastructure/docs/index.md

## Writing
Only edit shards marked writable. For a shard marked ask first, get the user's agreement in this session before editing it. To record what a session learned, use the globu:update-knowledge skill.

Nothing in a repo has to change

A knowledge base is a docs/ directory of Markdown. Globu reads it as it is and keeps everything about your set of repos in ~/.globu.

Basedocs/index.md: A docs/ directory whose index.md carries the authoring guide, plus a dated log and concept docs with frontmatter. Any editor works and globu base validate checks the shape. A repo can hold many bases, one per package, and knowledge about a piece of code belongs in the nearest one above it.
Shard~/.globu/manifest.yaml: One registered repo, with two lines of routing text: what it holds and when to consult it. Every shard has a mode. A read-only shard is never edited, an ask shard makes Claude Code prompt before an edit from another repo and a writable one is open.
Contextglobu use work: A named selection of shards, such as work or personal. The active context decides which shards a new session sees. The manifest is portable: keep it in your dotfiles or let a team share one.

From an empty repo to a session that knows

Three skills and one hook. Each step is a command in Claude Code and nothing is left to remember by hand.

/globu:setup-knowledge-base

Give a repo a base

Creates docs/index.md with the authoring guide and docs/log.md, or upgrades a base that is already there.

/globu:update-knowledge

Record what a session learned

Routes each decision, root cause or gotcha to the doc that owns it, adds a log entry and validates. The edits ship in the same commit as the code.

/globu:register-knowledge-base

Register the repo

Adopts it as a shard and drafts its routing text. A repo given by URL is cloned read-only under ~/.globu.

claude

Work from any other repo

The session begins with the shard index. When a task touches a shard's area, Claude reads its entry file, and writes back within that shard's mode.

Built to stay out of the way

Plain Markdown, any editor

Bases follow OKF: frontmatter, an index and a log. People and agents edit the same files, and the structure is checked, not the prose.

docs/architecture.md
---
type: "Architecture"
title: "Request pipeline"
description: "How a request moves from nginx to Firestore."
---

Three modes

Not every repo may be edited from everywhere. A hook enforces the mode for the file tools and, best effort, for shell commands.

readNever edited. Clones made from a URL start here.
askSessions in the repo edit freely, every other session prompts first.
writeOpen from anywhere.

One manifest for the team

Keep a manifest.yaml in a shared repo. A new machine or a CI job merges it and clones what is missing.

globu import git@github.com:acme/team.git
globu sync

Hooks do the enforcing

The plugin wires three Claude Code hooks, so the rules hold whether or not anyone remembers them.

Session startPrints the shard index for the directory the session runs in.
GuardBlocks edits to read-only shards and asks before edits to shards in ask mode.
ValidateChecks a base right after an edit and hands the errors back in the same session.

Install

The plugin runs its CLI from an npm package that Claude Code installs with it, so node 22 or newer and npm must be on the PATH.

Latest release 0.3.3, 9 October 2026. MIT licence. Source on GitHub, the CLI on npm.

In Claude Code

claude plugin marketplace add Mercastra/globu
claude plugin install globu@globu

In a terminal, on its own

npm install -g @mercastra/globu
globu base --help