Check is configured through environment variables, hook/plugin configuration files, and an optional ~/.check/config.json file for persistent settings and feature-specific overrides.

Environment variables

See the environment variables reference for full details, port resolution order, and examples.

Hook configuration (Claude Code)

The hook is defined in hooks.json inside the plugin directory. When installed via the marketplace, this is managed automatically. For manual installation, add to ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "check",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}

The matcher targets the ExitPlanMode tool specifically. The timeout is in seconds (345600 = 96 hours) — long reviews can stay open without expiring.

Plugin configuration (OpenCode)

OpenCode uses opencode.json to load the plugin:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@pleaseai/opencode@latest"]
}

This uses the default plan-agent workflow: submit_plan is registered for OpenCode’s plan agent, while build and other primary agents do not see it.

To configure the workflow explicitly:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["@pleaseai/opencode@latest", {
      "workflow": "plan-agent",
      "planningAgents": ["plan"]
    }]
  ]
}

When Check is used with other OpenCode plugins, the options object must stay attached to the Check plugin entry:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["@pleaseai/opencode@latest", {
      "workflow": "plan-agent",
      "planningAgents": ["plan", "sisyphus"]
    }],
    "oh-my-opencode-slim",
    "openviking-opencode"
  ]
}

Use workflow: "manual" for commands-only mode, or workflow: "all-agents" to restore the legacy behavior where primary agents can call submit_plan. In plan-agent mode, any names listed in planningAgents are added alongside OpenCode’s built-in plan agent. Slash commands (/check-review, /check-annotate, /check-last) require the CLI to be installed separately via the install script.

If you are upgrading from an older OpenCode install, see the OpenCode 0.19.1 migration guide.

Plan saving

Approved and denied plans are saved to ~/.check/plans/ by default. You can change the save directory or disable saving in the Check UI settings (gear icon).

Config file

Check reads ~/.check/config.json for persistent settings. This includes display name, diff options, conventional comment labels, and feedback message customization.

You can customize the messages Check sends to the agent when you approve, deny, or annotate plans and documents. See the custom feedback guide for the full config shape, template variables, and runtime-specific overrides.

Remote mode

When working over SSH, in a devcontainer, or in Docker, set CHECK_REMOTE=1 (or true) and CHECK_PORT to a port you’ll forward. Set CHECK_REMOTE=0 / false if you need to force local behavior even when SSH env vars are present. See the remote & devcontainers guide for setup instructions.

Custom browser

CHECK_BROWSER accepts an app name (macOS), executable path (Linux/Windows), or a custom script. This is useful for opening Check in a specific browser or handling URL opening in unusual environments.

# macOS
export CHECK_BROWSER="Google Chrome"

# Linux
export CHECK_BROWSER="/usr/bin/firefox"

# Custom script
export CHECK_BROWSER="/path/to/my-open-script.sh"

For one-off overrides without changing your shell profile, use the --browser flag:

check review --browser "Safari"
check annotate plan.md --browser "Firefox"

Session discovery

If you accidentally close a Check browser tab, the server is still running — you just need the URL. The sessions subcommand lists active sessions and can reopen them:

check sessions              # list active sessions
check sessions --open       # reopen most recent session
check sessions --open 2     # reopen a specific session
check sessions --clean      # remove stale session files

Sessions are tracked automatically. Stale entries from crashed processes are cleaned up on the next listing.

Disabling sharing

Set CHECK_SHARE=disabled to remove all sharing UI — the Share tab, copy link action, and import review option are all hidden. Useful for teams working with sensitive plans. To make this persistent without an environment variable, add "share": "disabled" to ~/.check/config.json. The environment variable takes precedence over the config file.

To self-host the share portal instead, see the self-hosting guide.