getting started

Mossbear manages your rules, skills, and planning docs in one place and delivers them to every agent you run. The CLI is the on-device half: it hooks into your agent’s lifecycle, records what each run did, and syncs that record to your dashboard, which does the grading. The CLI never grades — it holds no model credentials and produces no verdict of its own, so a verdict has exactly one source.

Your file contents, your diffs and your raw transcripts never leave your machine. What does sync is enumerated on the privacy page — action metadata, rule-file manifests, token counts, anything you push on purpose, and guide suggestions with redacted excerpts of the turns behind them.

requirements

• Node.js 20 or newer.
• An agent the CLI can hook into, such as Claude Code.
• Optionally, a Mossbear account to sync verdicts to your dashboard — free, no card required. Everything local works without one.

install the CLI

npm install -g mossbear

A global install is required (not just npx): the hook that Mossbear registers invokes the CLI from your agent’s session, so the binary must be on PATH.

set up your project

Initialize Mossbear inside your project — no token or account needed for this step:

cd your-project
mossbear init
mossbear doctor

Running init detects your agent platform and does the rest:

• registers an action-logging hook that records each tool use,
• registers a session-end hook that tells the dashboard the run is over, so it can be graded against your guides,
• scaffolds an AGENTS.md guide file if your project has none,
• installs a user-invocable Claude Code skill.

Here is what that prints, in a repo that already has a CLAUDE.md and a .cursorrules:

mossbear init

  created ~/.mossbear/config.json
  ~/.mossbear/config.json: dashboardUrl unset — runtime falls back to https://app.mossbear.io
  .mossbear/config.json: project proj_8f2c1d47a9b30e56 (derived from this repo's root commit — commit the file so every clone agrees)
  created .claude/settings.json with PostToolUse hook
  updated .claude/settings.json with PostToolUseFailure hook
  updated .claude/settings.json with Stop hook (mossbear sync)
  updated .claude/settings.json with SessionEnd hook (mossbear sync --session-complete)
  updated .claude/settings.json with SessionStart hook (mossbear sync --no-actions)
  created AGENTS.md
  created .agents/
  created .claude/skills/mossbear/SKILL.md
  created .claude/skills/mossbear-context/SKILL.md
  created .claude/skills/mossbear-cli/SKILL.md

Done. Next steps:
  Edit AGENTS.md to add your rules
  mossbear sync --token <token>  — connect your dashboard (Settings → Developer → CLI Token); remembered after the first run
  mossbear link            — adopt this repo's existing guide files (2 found) into your dashboard
  mossbear guides active   — list cached guides
  mossbear doctor          — verify your environment

That output is captured from the real binary by scripts/capture-cli-output.ts and checked in CI, so it cannot drift from what you will actually see.

Use doctor any time to verify hooks and config.

connect your dashboard

To see graded sessions in your runs list, connect the CLI to your dashboard once. Grab a CLI token under Settings → Developer → CLI Token and run:

mossbear sync --token <your-token>

The token is remembered after the first successful sync, so future syncs need no flag. Then just work normally — your runs list fills in as your agent acts.

everyday commands

• mossbear sync — push queued verdicts and feedback, pull your latest guides.
• mossbear link — bring existing guide files (AGENTS.md, CLAUDE.md, .cursorrules) into Mossbear.
• mossbear guides active — list the guides your agent is graded against.
• mossbear status — show queue and config status.

next steps

Running agents in the cloud or CI? See remote agents.