Troubleshooting

First stop for anything that isn't working. Most install/health problems are diagnosable with one command; everything else has a report path at the bottom.

If you are setting getmyorg up for the first time, start with Getting started.

Start here: /myorg:doctor

/myorg:doctor (Codex: $myorg:doctor) is the single health check. It inspects the install — git hooks, context directives, host capabilities, persistent instructions, autonomy resolution, and project-map freshness. Its first line names your getmyorg version. Its second line, repeated at the end, is one of:

  • OK — install is healthy.
  • DRIFT — run /myorg:doctor --fix to repair.
  • WARNING — repair pass did not resolve all drift.
  • BLOCKED — a Bash guard in this repo rejects getmyorg commands …

Run /myorg:doctor --fix to repair drift it can fix automatically (it reinstalls hooks and re-syncs context directives). It will not regenerate the project map or change anything you own — see the per-section hints in its output.

Common problems

The MCP server didn't start / no startup banner

When Claude Code starts the getmyorg MCP server it writes a banner starting getmyorg MCP server to the server's output. If you don't see it, the server isn't running. Check the MCP server output pane in Claude Code for [getmyorg] launcher messages. Common causes:

  • curl or python3 not found — the bundled launcher needs both to auto-install the binary. Install them and re-open Claude Code.
  • Binary installed but not authenticated — run /myorg:login, or in a terminal ${XDG_CONFIG_HOME:-$HOME/.config}/getmyorg/bin/getmyorg --login, then re-open Claude Code.
  • Windows without WSL — the binary is native macOS/Linux. Run getmyorg inside WSL2; see Before you start.

Login fails or keeps asking me to re-authenticate

Sign-in tokens last 30 minutes and renew automatically: every getmyorg command renews a token that is about to expire, and a session can still be renewed up to 30 days after its last token lapsed. If login won't stick:

  • getmyorg is in invite-only beta: sign-in needs an invitation. If the sign-in page says "You are not authorized to perform this request", ask for an invite for the email you sign in with (for GitHub sign-in, your GitHub account's primary email), then sign in again.
  • Confirm you are signing into the same account the OAuth flow opens.
  • Delete ~/.config/getmyorg/credentials.json and run /myorg:login again.
  • A transient worker blip at startup is tolerated automatically (the server retries with backoff before giving up). If it still exits, re-open Claude Code to retry the load.

/myorg:* commands are blocked or prompt on every step

getmyorg's own guards never stop getmyorg's commands. If your repo has its own Bash guard (a PreToolUse hook in .claude/settings.json, often a team command allowlist), it may block or ask about the getmyorg … commands /myorg:* skills run. /myorg:doctor runs that guard against getmyorg's commands and names the hook if it gets in the way:

  • [blocked]: the guard rejects getmyorg commands, so skills stop at it.
  • [asks]: you get a permission prompt on every step, and headless runs (claude -p) can't answer it.
  • [unverified]: doctor ran outside Claude Code in a repo you haven't trusted in Claude Code yet, so it didn't execute the hook. Run /myorg:doctor from Claude Code in the repo to check it.

Doctor checks the hooks in the repo's .claude/settings.json and .claude/settings.local.json. Your own user-level hooks (~/.claude/settings.json) apply too but aren't checked.

Fix it in the guard itself: add an allow rule for commands starting with getmyorg, then commit that so the whole team gets it. If the guard blocks /myorg:doctor too, run ~/.config/getmyorg/bin/getmyorg doctor in a terminal outside Claude Code to see the report.

getmyorg's guard stopped or bounced a command

The guardrails check what your agent runs. A stop can't be cleared by the agent: if the command is really needed, run it yourself with ! <command>. A bounce asks the agent to think the command through; it can retry once it has. At relaxed, the default, everything runs except never-OK commands and force-pushes to protected branches. If a stricter level you chose gets in the way of your work, /myorg:config guards relaxed goes back to it.

With gate mode on (/myorg:config gate on), Claude Code asks you about every command that isn't routine. If it asks too often, /myorg:config gate off turns it off; the guard level still applies.

/myorg:doctor has a "Session guards" line that shows the level and tests that the guards work:

  • [ok]: the guards are on and stopped a test command.
  • [off]: the level is off. /myorg:config guards relaxed turns them back on.
  • [broken]: the guards didn't stop the test command. Doctor says why; usually python3 is missing, or the plugin needs an update.
  • [unverified]: doctor ran outside Claude Code or Codex, so it couldn't find the plugin to test.

In Codex, the guards only run after you trust the plugin's hooks in /hooks.

"Project map: refresh failed" on startup

The map is repo-local and regenerated on startup for initialized repos. On failure the banner points you at /myorg:doctor, which reports map freshness in detail. To rebuild from scratch, run /myorg:refresh --full.

An agent seems stuck / nothing happens

An agent that needs a human decision asks you in the session and waits for your answer rather than guessing. If no one is at the keyboard it will appear stalled. This is expected: answer the question when you're back.

A crash / panic

A single tool panic no longer takes down the whole server — it's recovered and the session keeps running. A structured crash report is written to a private crashes/ directory next to your credentials (~/.config/getmyorg/crashes/). Attach that file when you report the problem.

Still stuck? Tell us

The beta is how we learn from real installs. If something is broken, confusing, or missing — or you want to request a feature — please open an issue:

https://github.com/praxiom-systems/getmyorg-community/issues/new/choose

Helpful things to include: what you ran, the /myorg:doctor output, the MCP server output pane (look for [getmyorg] lines), and any crash report file.

Docs for getmyorg v0.5.21.