@codehabits/cli

Team intelligence for AI coding agents. Extract conventions, anti-patterns, and domain knowledge from your codebase and pull-request history, then deliver it to Cursor, Claude Code, VS Code Copilot, and other agents.

• Website: codehabits.dev
• Docs: codehabits.dev/docs
• MCP server (IDE tools): @codehabits/mcp

Why codehabits?

Generic AI assistants do not know how your team writes code. codehabits analyzes your repository and merged PRs, then writes structured intelligence your agents can load automatically, without manual rule files to maintain.

| You get | From | | --- | --- | | Coding conventions & anti-patterns | PR review comments + codebase scan | | Domain knowledge graph | Repeated patterns across PRs | | Reviewer expertise map | Who owns which areas | | Agent-ready outputs | AGENTS.md, Agent Skills, optional MCP tools |

Requires: Node.js 20+, a GitHub repository, and a free codehabits account (codehabits login).

Quick start

npx @codehabits/cli login
npx @codehabits/cli enable

Typical flow:

1. Register the repo with codehabits (GitHub OAuth).
2. Scan the codebase and fetch PR history.
3. Analyze patterns with AI (cloud).
4. Write .codehabits/ intelligence, then AGENTS.md and skill files for your agents.

Check everything with:

npx @codehabits/cli status

Optional: give agents live access to conventions in the IDE:

npx @codehabits/cli mcp-install

See @codehabits/mcp for MCP tool details.

What gets generated

Committed to your repo (safe to review in PR):

| Output | Purpose | | --- | --- | | .codehabits/conventions.json | Team coding rules | | .codehabits/anti-patterns.json | Patterns to avoid | | .codehabits/knowledge.json | Domain topics & facts | | .codehabits/reviewers.json | Expertise by path/area | | .codehabits/meta.json | Maturity, sync metadata | | .codehabits/config.json | Lookback, ignores, emit_targets (editable) | | AGENTS.md | Universal entry point for agents that read it | | .claude/skills/codehabits-team-intel/ | Agent Skill (Claude Code; Cursor discovers this path) | | .agents/skills/codehabits-team-intel/ | Cross-client skill layout (VS Code Copilot, installers) |

Not committed (local / MCP workflow only):

| Output | Purpose | | --- | --- | | .codehabits/proposals.json | Draft convention changes from MCP record_feedback |

After enable, commit the tracked files and open a PR so the team adopts the intelligence together.

Multi-tool agent outputs

By default, enable writes three emit targets: agents-md, claude-skills, and agents-skills.

# Non-interactive defaults (CI-friendly)
npx @codehabits/cli enable -y --team your-team-slug

# Pick outputs interactively (after analysis completes)
npx @codehabits/cli enable --configure-targets

# Explicit CSV
npx @codehabits/cli enable --targets agents-md,claude-skills,agents-skills

# Legacy Cursor-only skill path (optional)
npx @codehabits/cli enable --targets agents-md,cursor-skills

Change targets later in .codehabits/config.json (emit_targets) and re-run sync, or run enable --configure-targets again.

Commands

| Command | Description | | --- | --- | | codehabits login | Sign in with GitHub OAuth | | codehabits logout | Clear stored credentials | | codehabits whoami | Show current user | | codehabits enable | Full setup: register, analyze, write intelligence & agent files | | codehabits sync | Incremental update from latest PRs (merges with cloud) | | codehabits status | Auth, intelligence, config, emit targets, MCP wiring | | codehabits show <type> | Print conventions, anti-patterns, knowledge, or reviewers | | codehabits check <file> | Validate a file against team conventions | | codehabits mcp-install | Add @codehabits/mcp to Cursor MCP config | | codehabits setup-action | Scaffold GitHub Actions workflow for auto-sync | | codehabits token create | Create API token for CI (--name required) | | codehabits team assign | Assign current repo to a team workspace |

enable options

| Flag | Description | | --- | --- | | --path <dir> | Repository path (default .) | | --skip-prs | Local codebase scan only (no PR fetch) | | --team <ref> | Team id or slug (required for org repos in CI) | | --personal | Leave repo unassigned (user-owned repos only) | | --targets <csv> | agents-md, claude-skills, agents-skills, cursor-skills | | -y, --yes | Non-interactive; default emit targets | | --configure-targets | Multiselect agent outputs after analysis |

Organization repositories

Repos under a GitHub organization must be assigned to a team workspace on first enable:

• Interactive: codehabits enable prompts for a team.
• Non-interactive: codehabits enable --team <team-id-or-slug>.
• --personal is only for user-owned repositories.

CI/CD

Ongoing sync (repo already enabled; run on merge to main):

- name: Sync codehabits intelligence
  run: npx @codehabits/cli@latest sync --ci
  env:
    CODEHABITS_TOKEN: ${{ secrets.CODEHABITS_TOKEN }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Create a token once:

npx @codehabits/cli token create --name "GitHub Actions"

Add the secret as CODEHABITS_TOKEN in the repository.

First-time enable in CI (organization repo):

npx @codehabits/cli@latest enable -y --team your-team-slug

setup-action can generate a workflow stub:

npx @codehabits/cli setup-action

Install globally

npm install -g @codehabits/cli
codehabits enable

Global install uses the codehabits command (not npx @codehabits/cli).

How it fits together

flowchart LR
  subgraph cli ["@codehabits/cli"]
    login[login]
    enable[enable / sync]
  end
  subgraph repo ["Your repository"]
    ch[".codehabits/*.json"]
    agents[AGENTS.md + skills]
  end
  subgraph agents_layer ["AI tools"]
    cursor[Cursor]
    claude[Claude Code]
    copilot[VS Code Copilot]
  end
  subgraph mcp ["@codehabits/mcp optional"]
    tools[get_team_context / check_code / ...]
  end
  login --> enable
  enable --> ch
  enable --> agents
  ch --> cursor
  ch --> claude
  ch --> copilot
  agents --> cursor
  agents --> claude
  agents --> copilot
  ch --> tools
  mcp-install[mcp-install] --> mcp

• Passive context: agents read AGENTS.md and skill files on their own.
• Active tools: MCP server reads .codehabits/ from the project cwd and exposes lookup, check, and feedback tools.

Environment variables

| Variable | Description | | --- | --- | | CODEHABITS_TOKEN | API token for CI (sync --ci) | | CODEHABITS_API_URL | API base URL (default https://codehabits.dev) |

FAQ

Do I need MCP?
No. Skills and AGENTS.md work without MCP. MCP adds on-demand tools (get_team_context, check_code, etc.) inside supported IDEs.

Is my code sent to the cloud?
Enable/sync sends codebase signals (patterns, stack, file stats) and PR metadata to the codehabits API for analysis, not your full source tree as a zip. See codehabits.dev/docs for privacy details.

How often should we sync?
After meaningful PR volume (e.g. weekly) or on every merge via GitHub Actions.

Can I edit conventions?
Edit JSON under .codehabits/ or use MCP record_feedback → approve_proposal for a guided workflow.

Related packages

| Package | Role | | --- | --- | | @codehabits/mcp | Model Context Protocol server for IDE agents |

License

MIT © codehabits