Rules

What it does

The rules integration detects your project’s rule file and appends a GitWhy instructions block. This tells the agent what GitWhy is, when to save context, and how to call git why save or the gitwhy_save MCP tool. Rules are the universal fallback — every agent that reads project rule files will receive GitWhy instructions.

Setup

Run git why setup and select Rules from the menu, or append the block below to your preferred rule file manually. GitWhy detects the rule file in this order and appends to the first one found:

CLAUDE.md
AGENTS.md
.cursorrules
.windsurfrules
.clinerules
.github/copilot-instructions.md

If none exist, it creates AGENTS.md.

Which agents read which file

Rule file	Read by
`CLAUDE.md`	Claude Code
`AGENTS.md`	Codex CLI, Cursor, Gemini CLI, Antigravity, Kilo Code, Android Studio (Gemini)
`.cursor/rules/*.mdc`	Cursor (project rules directory)
`.cursorrules`	Cursor (legacy format)
`.windsurfrules`	Windsurf
`.windsurf/rules/*.md`	Windsurf (rules directory)
`.clinerules`	Cline
`.kiro/rules/*.md`	Kiro (rules directory)
`.github/copilot-instructions.md`	GitHub Copilot

AGENTS.md is the most widely supported format — it’s the OpenAI-proposed standard adopted by Codex CLI, Cursor, Gemini CLI, Antigravity, Kilo Code, and more. If you want maximum compatibility across agents, use AGENTS.md.

OpenCode uses a rules config key instead of a file in the project root. See the OpenCode docs for details.

What gets added

The following block is appended to your rule file:

## GitWhy — Context Management

GitWhy saves the reasoning behind code changes to the local context tree at `.git/gitwhy/contexts/`.

**Save context after meaningful work:**
When the user says "save with GitWhy" (or similar), generate a structured markdown context using the GitWhy format and run:
- Via MCP: `gitwhy_save(markdown, domain?, topic?)`
- Via CLI: pipe the markdown to `git why save`

**Retrieve context:**
- Via MCP: `gitwhy_get(id)` where id is like `ctx_a1b2c3d4`
- Via CLI: `git why get ctx_a1b2c3d4`

**Search contexts:**
- Via MCP: `gitwhy_search(query, cloud?)`
- Via CLI: `git why search <query>`

**Browse, sync, and share:**
- Via MCP: `gitwhy_list(domain?, topic?)`, `gitwhy_status()`, `gitwhy_sync(ids?)`, `gitwhy_publish(ids)`, `gitwhy_post_pr(ids?, pr_number?)`
- Via CLI: `git why tree`, `git why log`, `git why push`

See the full context format at `.claude/skills/gitwhy/SKILL.md` if skill files are installed.

Token cost

The rules block is loaded once per agent session as part of reading the project rule file. It is not re-injected on every turn. Token cost is approximately 150-200 tokens per session.

Combine with other methods

Rules work well as a fallback alongside MCP:

MCP provides the actual tools
Rules ensures the agent knows to use them, even in sessions where skill files aren’t triggered

If you have skill files installed, the rules block’s last line points the agent to .claude/skills/gitwhy/SKILL.md for the full format reference.

Getting Started

Core Features

Sharing & Collaboration

Interfaces

Integration Guide

CLI Reference

Context Format

Plans & Pricing

What it does

Setup

Which agents read which file

What gets added

Token cost

Combine with other methods

See also

​What it does

​Setup

​Which agents read which file

​What gets added

​Token cost

​Combine with other methods

​See also

What it does

Setup

Which agents read which file

What gets added

Token cost

Combine with other methods

See also