# Codehabits — full documentation bundle

> Codehabits extracts your team's coding conventions, anti-patterns, and domain knowledge from PR history and delivers them to every AI coding agent via Agent Skills and MCP.

This file is the bundled, machine-readable version of the entire Codehabits product surface area: what it is, how to set it up, every CLI command, every MCP tool, the on-disk file schema, and per-agent configuration. Designed to be ingested by AI coding agents in a single fetch.

Canonical home: https://codehabits.dev
Short index: https://codehabits.dev/llms.txt
Source code: https://github.com/codehabits-dev/codehabits

---

## What Codehabits is

Codehabits is a tool that turns your team's PR history into structured, machine-readable intelligence that any AI coding agent can consume. It solves a specific problem: AI tools (Cursor, Claude Code, Codex, Windsurf, Copilot, Gemini CLI) generate confident-sounding code that ignores your team's conventions, your team's anti-patterns, and your team's domain knowledge.

The fix is two parts:
1. A CLI (`@codehabits/cli`) that reads your git/PR history and writes a `.codehabits/` directory at your repo root containing JSON files of conventions, anti-patterns, knowledge, and reviewer expertise.
2. An MCP server (`@codehabits/mcp`) that exposes those files as standard MCP tools so any agent can query them on demand.

Codehabits also writes Agent Skills markdown files alongside the JSON, so even agents that don't speak MCP yet can discover the intelligence through the [Agent Skills open standard](https://agentskills.io).

---

## Quickstart

Prerequisites: Node 20+, a GitHub repo with PR history, a GitHub account.

```bash
# 1. authenticate with GitHub
npx @codehabits/cli login

# 2. enable the repo (analyzes git history, writes .codehabits/)
cd your-repo
npx @codehabits/cli enable

# 3. wire up the MCP server (defaults to .cursor/mcp.json)
npx @codehabits/cli mcp-install

# 4. restart your agent. Done.
```

For org-owned repos: pass `--team <slug>` to `enable`. The `--personal` shortcut is only for repos under a personal GitHub account.

---

## CLI reference (`@codehabits/cli`)

| Command | Purpose |
| --- | --- |
| `codehabits login` | OAuth with GitHub, store token locally |
| `codehabits enable` | First-run analysis, write `.codehabits/` |
| `codehabits sync` | Refresh intelligence from new PRs |
| `codehabits status` | Show current setup state and MCP install state |
| `codehabits show <type>` | Print conventions / anti-patterns / knowledge / reviewers |
| `codehabits check <file>` | Validate a file against current conventions |
| `codehabits mcp-install` | Wire the MCP server into Cursor (`.cursor/mcp.json`); add `--global` for `~/.cursor/mcp.json` |
| `codehabits setup-action` | Generate a GitHub Actions workflow that runs `sync` on every merge |
| `codehabits token create` | Create an API token for CI/CD |

All commands accept `--path <dir>` to operate on a different repo path.

---

## MCP server (`@codehabits/mcp`)

Package: `@codehabits/mcp` · Binary: `codehabits-mcp`.

Universal MCP config (works in any agent that speaks the Model Context Protocol):

```json
{
  "mcpServers": {
    "codehabits": {
      "command": "npx",
      "args": ["-y", "@codehabits/mcp"]
    }
  }
}
```

### Tools

#### `get_team_context`
Get team coding conventions, anti-patterns, and domain knowledge in one call.
Use this before writing or reviewing code to understand how the team works.

#### `check_code`
Validate a code snippet against team conventions and anti-patterns. Returns
violations with suggestions. Pass the snippet as text; the tool returns a list
of `{ rule, violation, suggestion }` objects.

#### `get_knowledge`
Get domain-specific knowledge about a topic (e.g., "authentication", "billing",
"deployment"). Returns the curated knowledge entries that match.

#### `suggest_reviewers`
Given a list of changed files, suggest reviewers ranked by historical
expertise (commits + reviews). Useful for PR routing.

#### `record_feedback`
Record when a user overrides or corrects team intelligence, or propose a new
convention. Writes to `.codehabits/proposals.json` (gitignored). Does not
mutate tracked intelligence until `approve_proposal` is called. Agents should
call this whenever they disagree with a convention rather than silently
ignoring it.

#### `approve_proposal`
Approve a pending proposal: merge it into `conventions.json`, regenerate the
Agent Skills markdown files, and create tracked git changes ready to commit.

---

## On-disk file schema (`.codehabits/`)

After `enable` runs, the repo root contains:

```
.codehabits/
├── conventions.json      # tracked: team coding conventions
├── anti-patterns.json    # tracked: things the team rejects
├── knowledge.json        # tracked: domain-specific notes
├── reviewers.json        # tracked: contributor expertise scores
├── meta.json             # tracked: schema version, last sync, repo id
├── proposals.json        # gitignored: pending proposals from agents/users
└── README.md             # tracked: human-readable summary
```

Each `*.json` file is structured per the schemas in `@codehabits/shared`. Agents should read these files directly when the MCP server is unreachable.

---

## Agent setup

### Cursor
- Per-project: `npx @codehabits/cli mcp-install` writes `.cursor/mcp.json`.
- Global: add `--global` to write `~/.cursor/mcp.json`.
- Restart Cursor after install.

### Claude Code
```bash
claude mcp add codehabits npx -y @codehabits/mcp
```
Restart Claude Code.

### Codex CLI
Drop the universal MCP config into `~/.codex/mcp.json` and restart Codex.

### Windsurf
Drop the universal MCP config into `~/.codeium/windsurf/mcp_config.json` and
restart Windsurf (or reload settings).

### Gemini CLI
Drop the universal MCP config into `~/.gemini/settings.json` (under the
`mcpServers` key alongside other servers).

### GitHub Copilot
Codehabits writes a `.github/copilot-instructions.md` stub during `enable`.
Copilot reads this automatically. No MCP step needed.

---

## Bootstrap prompt for any agent

```
You are setting up Codehabits for this repository.

1. Read https://codehabits.dev/llms.txt to learn what Codehabits is.
2. Run `npx @codehabits/cli enable` in this repo. It will open a browser for GitHub OAuth.
3. Run `npx @codehabits/cli mcp-install` to wire the Codehabits MCP server.
4. Read every file under the `.codehabits/` directory at the repo root. Treat them as the team's authoritative ground truth.
5. From now on:
   - When you write code, follow `.codehabits/conventions.json` and avoid `.codehabits/anti-patterns.json`.
   - When you need domain context, query `get_knowledge` first.
   - When you disagree with a convention, use `record_feedback` instead of silently ignoring it.
   - When suggesting reviewers, use `suggest_reviewers`.

Report back: which files exist under `.codehabits/`, the top 5 conventions you found, and 1 anti-pattern you should avoid here.
```

---

## How Codehabits ranks conventions

Each convention has a `confidence` score between 0 and 1 derived from:
- frequency in merged PRs
- consistency across reviewers
- recency-weighted decay
- explicit reinforcement via `approve_proposal`

Agents should treat conventions with confidence ≥ 0.75 as hard rules and 0.5-0.75 as strong preferences. Below 0.5 are surfaced as soft hints only.

---

## Common questions

**Does Codehabits send my code anywhere?**
The CLI talks to the Codehabits cloud only to register the repo and store the resulting intelligence. Source code never leaves your machine. The MCP server runs entirely locally.

**Does the MCP server need network access?**
No. It reads the local `.codehabits/` files. Network is only used by the CLI for `enable` and `sync`.

**What happens if `.codehabits/` is missing?**
The MCP server returns an empty result with a hint to run `codehabits enable`. Agents should handle this gracefully by surfacing the hint to the user.

**Can multiple agents share the same `.codehabits/`?**
Yes. The directory is the single source of truth. Every agent that follows the bootstrap prompt sees the same intelligence.

---

## Writing

### Why we built Codehabits
https://codehabits.dev/blog/why-codehabits

Every team has habits: the small, repeated patterns that make code feel like yours. We built Codehabits to extract those habits and ship them to every AI tool your team uses.

### What's New: Team Workspaces, Split Intelligence, and MCP Feedback
https://codehabits.dev/blog/whats-new-april-2026

Team dashboards, .codehabits split files, merge pipeline updates, MCP tools to record feedback and approve proposals, and refreshed docs. Here’s what shipped recently.

### Introducing codehabits: Team Intelligence That Every AI Tool Auto-Discovers
https://codehabits.dev/blog/introducing-codehabits

One command extracts your team's coding conventions, anti-patterns, and domain knowledge from PR history - then delivers it to Cursor, GitHub Copilot, Claude Code, and 20+ AI tools automatically.

### What Are Agent Skills? The Open Standard for AI Coding Tools
https://codehabits.dev/blog/what-are-agent-skills

Agent Skills solve the fragmentation problem across Cursor, Copilot, Claude Code, Codex, and Windsurf by giving every AI tool a shared way to discover team-specific coding intelligence.

### How to Make Cursor, GitHub Copilot, and Claude Code Follow Your Team's Conventions
https://codehabits.dev/blog/ai-coding-tools-team-conventions

A practical guide to configuring every major AI coding tool - Cursor, GitHub Copilot, Claude Code, Codex, Windsurf, Gemini CLI - to respect your team's patterns, or automating the entire process with codehabits.

### The Complete Guide to AI-Assisted Code Review in 2026
https://codehabits.dev/blog/ai-code-review-guide-2026

Everything teams need to know about AI-assisted code review - from GitHub Copilot code review to codehabits's team intelligence, comparing tools, workflows, and best practices for modern engineering teams.

### Why AI Coding Tools Ignore Your Team's Patterns (And How to Fix It)
https://codehabits.dev/blog/why-ai-tools-ignore-team-patterns

Cursor, Copilot, and Claude Code generate great code - but not your team's code. Here's why the gap exists, what it costs, and how team intelligence closes it.


---

## Links

- Web: https://codehabits.dev
- Short index: https://codehabits.dev/llms.txt
- Agent setup page: https://codehabits.dev/agents
- Source: https://github.com/codehabits-dev/codehabits
- npm CLI: https://www.npmjs.com/package/@codehabits/cli
- npm MCP: https://www.npmjs.com/package/@codehabits/mcp
- Agent Skills spec: https://agentskills.io