@codehabits/cli

@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:

• Register the repo with codehabits (GitHub OAuth).
• Scan the codebase and fetch PR history.
• Analyze patterns with AI (cloud).
• 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