GUM — Globally Unified Modules

npx get-gum@latest

Every time you start a new project or open a new chat, your AI agent forgets how you like to work:

• Commit messages in the wrong format — again
• No linting after edits — again
• Agent jumps into code without discussing the approach — again

You end up copy-pasting the same rules into CLAUDE.md, .cursorrules, GEMINI.md across every repo. Update one — manually update the rest. Switch from Claude to Gemini — rewrite everything.

GUM fixes this. Define your rules once as modules. They auto-load in every project, every chat, every runtime.

npx get-gum@latest

The wizard asks which runtimes you use and where to store modules.

In any AI chat session:

/gum-create

Tell the agent what behavior you want. It creates the module files for you.

Or create one manually — a module is just a folder with up to 3 files:

clean-commits/
  module.yaml    # metadata
  rules.md       # what the agent should do
  hooks.json     # automated enforcement (optional)

module.yaml — who is this module:

name: clean-commits
description: "Conventional commits, English, max 72 chars"
version: 1.0.0
enabled: true

rules.md — instructions for the agent (natural language):

## Commit rules

- Use conventional commits format: feat:, fix:, chore:, refactor:, docs:, test:
- Write commit messages in English
- Keep commit subject line under 72 characters
- Commit body maximum 3 lines

hooks.json — system-level automation that the agent can't skip (optional):

{
  "claude": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE\" 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}

Open any project, start any chat — your modules are already active. No setup, no copy-pasting.

npx get-gum list          # see what's enabled
npx get-gum toggle        # turn modules on/off
npx get-gum doctor        # health check

GUM modules can contain rules, hooks, or both.

Rule-to-hook promotion: During /gum-create, GUM detects mechanical rules and suggests converting them to hooks. "Always run lint before commit" shouldn't be a rule the agent might forget — it should be a hook that runs every time.

Not every module belongs in every project. You can override enabled/disabled state per project:

// .gum.json — commit to git, whole team gets these overrides
{
  "overrides": {
    "clean-commits": true,
    "code-quality": false
  }
}

// .gum.local.json — gitignored, just for you
{
  "overrides": {
    "my-experimental-module": true
  }
}

Priority: .gum.local.json > .gum.json > module.yaml default.

npx get-gum toggle --local       # edit team overrides
npx get-gum toggle --personal    # edit personal overrides

Use these inside your AI coding session:

GUM ships with ready-to-use modules you can enable during install:

Rules work on all runtimes. Hooks use each runtime's native format — GUM handles the conversion.

~/your-modules/                     ~/.claude/rules/gum/
  clean-commits/                      clean-commits.md  ← synced
    module.yaml        gum sync →     code-quality.md   ← synced
    rules.md           ────────→      my-module.md      ← synced
    hooks.json
  code-quality/                     ~/.claude/settings.json
    module.yaml                       hooks: { ... }    ← synced
    rules.md
    hooks.json

Modules live in any folder you choose (Obsidian vault, Dropbox, git repo — your call). gum sync copies enabled rules into runtime-specific locations where they auto-load at session start. No permission prompts, no manual setup.

Context budget: Agents reliably follow ~150 lines of instructions. gum doctor tracks your total and warns before you exceed it. /gum-optimize helps reduce bloat.

See CONTRIBUTING.md for development setup and the issue-first contribution process.

MIT