Getting started

Mossbear manages your rules, skills and 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 session 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.

Full raw transcript files stay on your machine during session sync; Mossbear sends redacted turn excerpts.

When you connect, Mossbear stores your account and workspace information. Depending on the features you use, it also receives:

• Action types, summaries, file paths and skill-suggestion signals.
• Rule-file paths and content hashes.
• Guidance and context you choose to upload. Linking guidance sends the selected files, including supported files belonging to a selected skill.
• Redacted excerpts of user and assistant turns.
• Token counts, session usage, your CLI version and which sessions have finished.

The dashboard produces grades from that evidence and stores them with session metadata. The privacy page explains each data class and what stays on your machine.

Requirements

• Node.js 20 or newer.
• An agent the CLI can hook into. mossbear init wires the harnesses it finds and falls back to Claude Code in a repo where none has run yet. See local agents for what each one gets.
• No account is needed to install the CLI or run mossbear init. Pair with a Mossbear account to link guidance and view synced sessions and grades.

Install the CLI

npm install -g mossbear

There is no stable release yet: this installs an alpha, and breaking changes can land on it without a deprecation window.

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.

What the CLI runs on your machine and when, how a release is built, and how to check one yourself: Security.

Set up your project

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

cd your-project
mossbear init
mossbear doctor

What init wires depends on your agent. For Claude Code, it:

• registers an action-logging hook that records each tool use,
• registers a session-end hook that tells the dashboard the session is over, so it can be graded against your guides,
• 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

  dashboardUrl unset — falling back to https://app.mossbear.io
  created ~/.mossbear/config.json
  wrote .mossbear/config.json — project proj_8f2c1d47a9b30e56
    derived from this repo's root commit — commit the file so every clone agrees

Nothing detected here that `init` can wire — using the default:
  Claude Code  → .claude/settings.json

  created .claude/settings.json
    5 hooks: PostToolUse, PostToolUseFailure, Stop, SessionEnd, SessionStart
    This hook installs the current mossbear release before the first turn of
    every session, on this machine as well as in rebuilt ones — that is how a
    breaking release reaches a repo whose hooks still name the old commands.
    `mossbear init --no-auto-update` rewrites the entry without the install
    clause; remove the SessionStart entry from .claude/settings.json to drop the
    hook altogether.

  created .agents/
  created .claude/skills/ — mossbear, mossbear-context, mossbear-cli, mossbear-installer

  = MCP install skipped; agent tools were not connected by this run
      claude mcp add --scope user mossbear -- mossbear mcp

Done. Next steps:
  mossbear login          connect this machine to your account
                          prints a code you approve in the browser; `mossbear
                          report --token <token>` still works
  mossbear link           adopt this repo's 2 existing guide files
  mossbear guides active  list cached guides
  mossbear doctor         verify your environment
  mossbear what-syncs     show what leaves this machine

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 sessions list, pair this machine with your account once:

mossbear login

It prints a short code and opens the approval page in your browser. Approve the code there and the CLI writes the token to ~/.mossbear/config.json itself — nothing to copy, and nothing shown once. The link is printed too, for when the browser doesn’t open. See login for the flags, including --no-open, and --print-url for a machine with no browser of its own.

On a machine that can’t open a browser to approve a pairing — CI, a cloud container — issue a token under Settings → Machines instead and put it in the environment as MOSSBEAR_TOKEN. The cloud agents setup has the recipes.

Link the guidance you already use

From the same project, choose an existing rule file or skill that applies to a real task:

mossbear link

Enter the number of the file or skill you want from the list. Pressing Enter without a selection imports everything offered. Linking sends the selected content to your dashboard, so choose only what you want Mossbear to manage. This command adopts supported rules and skills, not arbitrary documents.

If you already adopted those files during setup, you do not need to link them again. Files listed as managed already belong to a bundle.

Refresh and check the connection before starting work:

mossbear refresh
mossbear doctor

Read any warnings or checks marked ?. An unconfirmed check does not establish that the connection works. For your agent’s hook approval and restart steps, see local agents.

Run a task and find its result

Use an agent with grading support and start a new session in this project. Do a small, real task covered by the guidance you linked. If you chose a skill, use it for the task.

End the session, then open Sessions in your dashboard and select it. Grading follows session closure and may arrive later. When a grade is available, read its explanation and any cited actions. Compare them with the instruction you expected the agent to follow.

If no session appears, run mossbear doctor in the same project and read its hook and dashboard connection messages, then follow the empty sessions checklist. If the session appears without a grade, check your agent’s session-closure support on the local agents page. A missing grade is not evidence that your guidance was followed.

Use it in the next session

Start another session in the same project for your next task with those rules or that skill. You do not need to link the same files again. Compare the next result with the first and note anything you still had to repeat to the agent.

Everyday commands

• mossbear refresh — deliver this repo’s artifacts and pull your latest guides.
• mossbear link — bring existing guide files (AGENTS.md, CLAUDE.md, .cursorrules) into Mossbear.
• mossbear guides active — list enabled guides in the local dashboard cache. This does not confirm which files are on disk or what your agent read.
• mossbear status — show queue and config status.

Every command and flag is in the CLI reference. To see what leaves your machine before you link anything, run mossbear what-syncs.

Next steps

Using Antigravity CLI, Codex or Cursor? See local agents for which half of the loop each one gets.

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