Skip to content

Troubleshooting

Start with:

meshpoint doctor

It checks the login file, the token, the repository, each harness’s connection, the last capture and the spool directory. ✗ lines are the problem; · lines are informational.

  • Not a project. The directory must be a git repository with an origin remote. meshpoint status prints the project id or says why there is none. Directories without a remote are ignored by design.
  • Hooks not loaded. Harnesses read their config at session start. Start a new session after meshpoint connect. For pi, /reload; for OpenClaw, restart the Gateway.
  • Still spooled. Turns are sent once the oldest spooled turn is 60 s old, at session end, and at compaction. A session shorter than a minute sends on exit. One-shot opencode run exits before the flush; see opencode. Look at ~/.local/state/meshpoint/spool/: a non-empty file is waiting for the next event.
  • Project scope mismatch. Connected with --project for one repository, then opened another. Connect at user scope, or for that repository too.
  • Plan limit. The first write to a fourth project on Free is refused (402). The console’s Org page shows projects used.
  • The branch has no items yet. Memory is per branch; master and feature/x are separate. Write items or wait for the first checkpoint.
  • The inject is served from the edge and can lag up to a minute after an item is written. Start the session again a minute later.
  • Codex: project .codex/ files load only once the repository is trusted in ~/.codex/config.toml; see Codex.
  • OpenClaw caches the inject per session for 15 minutes; a new session sees new items at once.
  • It needs 20 assistant replies or 60k characters since the later of the last checkpoint on the branch and the last nudge in this session. Someone else’s items put on the branch resets the counter for everyone on it.
  • Cursor and Antigravity depend on transcript formats that are not yet confirmed; see their pages.
  • opencode one-shot runs exit before the nudge turn.
  • OpenClaw shows the nudge at the next bootstrap, not in the current reply.

The nudge is a message, not a command. The skill must be installed where the harness loads skills from (connect does this), and the harness must be allowed to run meshpoint items put: Claude Code’s skill allowlists it; Codex needs the rules file connect writes; Cursor needs the command allowed in its shell approvals. An ignored nudge is not repeated until the next twenty replies.

  • No browser opens. The CLI switches to a device code on its own when it finds no display; force it with meshpoint login --device. Approve at app.meshpoint.dev/device. The code expires after 15 minutes.
  • “session invalid, revoked or expired”. An owner or admin revoked the session, rotated keys with --revoke-sessions, or 90 days passed. Run meshpoint login again.
  • Wrong organization. meshpoint whoami shows the current one; meshpoint login --org <id> picks another.
  • Invite not applied. Invites match the email you sign in with. Sign in with that address, with any provider.
  • npm i -g permission error: set npm config set prefix ~/.npm-global and add ~/.npm-global/bin to PATH. Do not use sudo.
  • meshpoint: command not found inside a hook: the harness’s PATH lacks the npm global bin directory. GUI apps and systemd services often have a shorter PATH than your shell; set it in the harness’s environment (for OpenClaw, in the service drop-in).
  • pi or opencode stop capturing after npm i -g again: their extension and plugin point at the CLI’s install path. Re-run meshpoint connect pi or meshpoint connect opencode.
cat ~/.local/state/meshpoint/spool/*.jsonl

One JSON line per turn: body starting with [user] or [assistant], paths, at, branch. Credentials appear as [REDACTED:<kind>]. Deleting a spool file drops those turns; nothing else breaks.

Collect meshpoint doctor --json, the harness name and version, and the spool file after one session, and open an issue from meshpoint.dev. Strip anything you would not post publicly first.