Troubleshooting - Check Docs

Lost a Check tab?

If you accidentally close a Check browser tab, the server is still running in the background. You can find and reopen it:

check sessions

This lists all active sessions with their mode, project, URL, and how long they’ve been running:

Active Check sessions:

  #1  review    my-project           http://localhost:54321    3m ago
  #2  plan      my-project           http://localhost:12345    15m ago

Reopen with: check sessions --open [N]

To reopen one:

check sessions --open       # reopens the most recent
check sessions --open 2     # reopens session #2

Stale sessions from crashed processes are cleaned up automatically. You can also force cleanup with check sessions --clean.

Where does Check store data?

All local data lives under ~/.check/:

Directory	What’s in it
`plans/`	Snapshots of approved and denied plans. Controlled by the “Save plans” toggle in Settings.
`history/`	Automatic version history for every plan, organized by project and heading. Powers the plan diff and version browser.
`drafts/`	Auto-saved annotation drafts. If a server crashes mid-review, your in-progress annotations are recovered on the next session.
`sessions/`	Temporary session files for active servers. Cleaned up automatically when a server exits.

Plan saving is enabled by default. You can change the save directory or disable it entirely in the Check UI settings (gear icon).

Browser doesn’t open

If the UI doesn’t open automatically, check:

Remote/SSH session? Set CHECK_REMOTE=1 and CHECK_PORT to a port you’ll forward. See the remote guide.
Wrong browser? Set CHECK_BROWSER to the app name or path, or use --browser for a one-off override.
URL still works — even if the browser didn’t open, the server is running. Check check sessions for the URL and open it manually.

Hook doesn’t fire

If ExitPlanMode doesn’t trigger Check:

Make sure the plugin is installed: /plugin install check@check
Restart Claude Code after installing (hooks load on startup)
Verify check is on your PATH: which check
Check that plan mode is enabled in your Claude Code session

Codex plan review doesn’t open

Codex plan review uses the experimental Stop hook, which the macOS, Linux, and WSL installer configures automatically when Codex is installed or ~/.codex already exists.

If a Codex plan turn completes without opening Check:

Rerun the installer: curl -fsSL https://check.pleaseai.dev/install.sh | bash
Restart Codex Desktop or CLI so hooks are reloaded
Check ~/.codex/config.toml contains hooks = true under [features]
Check ~/.codex/hooks.json has a Stop hook whose command points to check
Run check sessions in case the browser failed to open but the session is running

Codex hooks are currently disabled on Windows in the official Codex docs, so the Windows installer prints manual guidance instead of changing Codex config automatically.

OpenCode build agent cannot call `submit_plan`

This is expected with the default OpenCode workflow. Check now defaults to plan-agent, which keeps submit_plan available to OpenCode’s plan agent and hides or denies it for build and other non-planning primary agents.

If you want the old broad behavior, opt in from opencode.json:

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

If you do not want automatic plan review at all, use workflow: "manual" and run /check-last or /check-annotate when you want Check.