Bearing

Turn AGENTS.md and skills into lint checks.

Your skills describe how you want code written. Bearing turns those preferences into checks that run at the end of an agent turn, while the agent still has the context to act on them.

Ask your agent to propose rules from your project conventions: keep business logic in models, use the framework's built-ins, or test observable behavior. You choose the criteria and feedback. Bearing checks the change with Jev and returns findings and review items so the agent can correct its work.

Works with Claude Code and Codex, in Git, JJ, and Composal repositories.

Install

On macOS or Linux (Apple Silicon/ARM64 or x64), with Node.js 18 or newer:

npm install -D bearing-lint
npx bearing --version

Bearing includes prebuilt binaries; Rust is not required. Install the dependency before running npx bearing or setting up hooks. Windows is not supported.

Set up your project

From your project's repository root:

# Codex
npx bearing init --agent codex --hooks
# Or Claude Code
npx bearing init --agent claude --hooks

npx bearing auth set-key

Enter your Jev API key at the hidden prompt. Bearing saves it in your user configuration outside the project. Checks send matching rules, paths, code changes, and any requested full-file context to Jev. Review what you share and keep keys out of project files.

Restart your agent and approve its project hooks when prompted. Invoke $bearing in Codex or /bearing in Claude Code. Ask it to turn your project preferences and skills into rules, then review and validate them:

npx bearing rules
npx bearing validate

Rules live in .bearing/rules/. The starter is disabled until you author your own rules.

Agent hooks

With --hooks enabled, prompt your agent as usual. At the end of its turn, Bearing checks only changes made since your prompt. Findings, rule guidance, and source links go back to the agent, which judges the feedback and can fix the code or explain why it should stay. Bearing does not rewrite code itself.

For an already initialized project, install hooks with the command below (use --agent claude for Claude Code). Check their status at any time:

npx bearing hooks install --agent codex
npx bearing hooks status

Restart your agent after installation and approve its project hooks when prompted. Keep the dependency installed; reinstall hooks if you move the project. Omit --hooks during setup if you prefer manual checks.

To keep hook setup personal, including when the project tracks Codex settings:

npx bearing init --agent codex --hooks --local
# Or Claude Code
npx bearing init --agent claude --hooks --local

For an existing setup, use npx bearing hooks install --agent codex --local (or --agent claude). Codex adds an entry to $CODEX_HOME/hooks.json (default ~/.codex/hooks.json) that runs only for this project and its subdirectories, excluding nested repositories. It leaves project settings alone. Claude uses .claude/settings.local.json, its private project settings file; it leaves shared .claude/settings.json and user settings alone.

npx bearing hooks status --local
npx bearing hooks uninstall --agent codex --local

Use --agent claude to uninstall Claude hooks. Existing defaults are unchanged. To switch Codex between project and user-local hooks, uninstall the old installation first; --local and --shared cannot be combined. Installation does not prove host activation: restart the agent and review /hooks.

Hooks use private settings by default. If your project intentionally tracks .codex/hooks.json, leave it tracked and explicitly allow that shared file:

npx bearing hooks install --agent codex --shared

A refused hook install leaves project configuration and the agent skill in place, but exits with an error. Shared hooks still require private lock/state files; review the installed machine-specific paths before committing settings.

Check changes yourself

npx bearing check
npx bearing check --format diff

Manual checks cover the whole working change. Findings include the rule guidance and affected files. Review items need judgment. Exit codes are 0 for clear/no work, 1 for findings or review, and 2 for errors or incomplete checks. With no enabled rules, invoke the Bearing agent skill to author and validate them. Text and diff output summarize excluded paths; npx bearing check --json retains the complete list. Unchecked work and errors remain visible in every format.

Go deeper

• Writing rules and interpreting results
• Example rules and reports
• CLI, configuration, hooks, and output formats
• Implementation and qualification

For development, run mise run check. Licensed under MIT.