Codehabitscodehabits
Sign in

Quickstart

Set up Codehabits in your repository in under 5 minutes. Extract team intelligence and deliver it to your AI tools.

Run npx @codehabits/cli login, then npx @codehabits/cli enable in your repo. Codehabits builds a day-1 baseline from your codebase (PR history optional), writes .codehabits/ intelligence files, generates Agent Skills, and optionally installs MCP — all in under five minutes.

Prerequisites

  • Node.js 20 or later
  • A GitHub repository (PR history optional — day-1 baseline works with zero PRs)
  • A GitHub account (for authentication)

Step 1: Authenticate

Log in to Codehabits with your GitHub account. This opens your browser for OAuth authentication.

Terminal
npx @codehabits/cli login

A verification code will be displayed in your terminal. Confirm it in your browser, authorize the GitHub OAuth app, and the CLI will automatically pick up your credentials.

Step 2: Enable your repository

Navigate to your project directory and run enable. This performs a full analysis of your codebase (and PR history when available).

Terminal
cd your-project
npx @codehabits/cli enable

⚠GitHub organization repositories

If the repo is owned by a GitHub organization, you must link it to a team workspace when enabling: pick or create a team in the prompts, or run npx @codehabits/cli enable --team <team-slug-or-id>. The --personal shortcut is only for repositories under a personal GitHub account. In automation, always pass --team for org repos.

Codehabits will:

  1. Register your repository with the Codehabits cloud
  2. Scan your codebase (file patterns, exports, naming conventions)
  3. Import linter/formatter config as conventions
  4. Analyze git history for contributor expertise
  5. Fetch and analyze merged + closed PRs (skipped gracefully if none)
  6. Run AI-powered extraction when PRs or repo docs provide signal
  7. Write intelligence files and a heuristic repo map to your repo

ℹWhat gets created

.codehabits/conventions.json: Team coding conventions

.codehabits/anti-patterns.json: Anti-patterns to avoid

.codehabits/knowledge.json: Domain knowledge graph

.codehabits/reviewers.json: Team expertise map

.codehabits/map.json: Heuristic repo map (packages, entrypoints, change routes)

.codehabits/meta.json: Sync metadata

.codehabits/config.json: Codehabits configuration

.codehabits/proposals.json (gitignored): optional pending changes from MCP record_feedback; applied with approve_proposal

.claude/skills/codehabits-team-intel/ and .agents/skills/codehabits-team-intel/: Agent Skills (default emit targets; optional legacy .cursor/skills/)

AGENTS.md: Fallback instructions for agents that read it

Step 3: Commit the intelligence

Intelligence files are designed to be committed to your repository so your entire team benefits.

Terminal
git add .codehabits/ .claude/skills/ .agents/skills/ AGENTS.md
git commit -m "chore: add codehabits team intelligence"
git push

⚠Check your .gitignore

If your .gitignore contains .claude/, .agents/, or .codehabits/, you'll need to remove those entries (or force-add the skill paths). These files contain no secrets, only extracted patterns.

Step 4: Set up MCP (optional)

For real-time AI tool integration via the Model Context Protocol, install the MCP server in Cursor:

Terminal
npx @codehabits/cli mcp-install

This adds the Codehabits MCP server to your Cursor configuration, providing tools like get_team_context, check_code, get_knowledge, suggest_reviewers, plus record_feedback and approve_proposal for proposing and merging convention updates locally (then commit and sync so the dashboard stays aligned).

Step 5: Keep intelligence fresh

As your team merges new PRs, intelligence should be updated. You can sync manually or automate it:

Manual sync

Terminal
npx @codehabits/cli sync

Automated sync with GitHub Actions

Terminal
npx @codehabits/cli setup-action

This generates a GitHub Actions workflow that automatically syncs intelligence when PRs are merged to your default branch. See the CI auto-sync guide for details.

Next steps