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:
curlorpython3not 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.jsonand run/myorg:loginagain. - 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:doctorfrom 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 isoff./myorg:config guards relaxedturns them back on.[broken]: the guards didn't stop the test command. Doctor says why; usuallypython3is 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.