Help

What to do when Claude Code is blocked. You do not need to be signed in to read this — if the problem is your account, signing in is the thing that will not work.

The editor window's session was never registered

The gateway does not recognise this session, so it cannot be authorized.

A session registers when the editor window opens. If the gateway or your network was down at that moment the registration never happened — and the window stays that way afterwards, because the editor does not re-run its start-up step for a window that is already open. Other windows on the same machine are unaffected, which is why one project works and another does not.

What to do. Send the prompt once more — the hook re-registers automatically and one retry is usually enough. If it repeats, close that editor window and open it again. A fresh window registers cleanly. Reinstalling does not help here: the hooks are shared by every window on the machine, so they are already correct.

agentgov gateway logs | tail -40

Look for /admin/session/register. Absent means the window never tried; present with an error names the reason.

The editor was opened on the wrong folder

This folder is not a git repository, so there is nothing to authorize.

A session is registered against a repository. A folder with no .git has nothing to register, so every prompt is refused — and retrying can never change that. The usual cause is a wrapper directory holding the real project one level inside it, so the project looks open while the folder the editor actually has is empty of git.

What to do. Open the folder that contains .git — normally the one with your package.json or pyproject.toml in it — and start Claude Code there. The message names the nested checkout when it can find exactly one. Reinstalling does not help: the installation is fine, the folder is the problem.

git rev-parse --show-toplevel

Prints the checkout you are in, or an error if there is none. Run it where you opened your editor.

Windows and WSL each have their own Claude Code

A SECOND, ungoverned Claude Code at /mnt/c/Users/… has opened N WSL folder(s).

On Windows, AgentGov is installed inside WSL. Claude Code running natively on Windows reads a completely different configuration — its own user folder and ProgramData — where AgentGov is not installed and cannot be: the path guard only understands POSIX paths and would fail open on Windows ones. Both clients can open the same project, because Windows can reach WSL files over a network path. Opened from the Windows side, a granted repository runs with no work-item gate, no repo lock and no token attribution, and nothing on screen says so. agentgov doctor run inside WSL reports that install — the healthy one — and is blind to the other.

What to do. Always open projects from WSL: run code . in a WSL terminal, inside the repository. The editor title must end in [WSL: Ubuntu] — if that badge is missing, the window is not governed, whatever the folder is. Closing and reopening from the WSL side is the whole fix; nothing needs reinstalling.

cd ~/path/to/your/repo && code .

Run this in a WSL terminal, never in PowerShell or Command Prompt. Then re-run `agentgov doctor` from the terminal inside that new window.

The repository is not granted

This repository has not been granted to you.

AgentGov is a second permission layer, narrower than your git host. Being able to clone a repository does not authorise Claude Code to run inside it — an admin grants that separately, per person, per repository. This is the repo lock working, not a fault.

What to do. Ask an admin to add it on the Grants page. It must match your origin remote exactly, including capitalisation — a near-miss silently never matches.

git remote get-url origin

Send an admin exactly what this prints. That is the string the grant must carry.

The gateway is not running

Could not reach the governance gateway at http://127.0.0.1:8000

The gateway runs on your own machine and every request passes through it. When it is not running there is no route to the model at all — by design, so that bypassing governance yields no access rather than unsupervised access.

What to do. Start it, then confirm. If it was already installed, the logs say why it stopped.

agentgov gateway install && agentgov doctor

Already installed? Use `agentgov gateway logs` instead.

The grant has expired

Your access to this repository has expired.

Grants can carry an expiry date. Yours has passed, so the repository is no longer authorised for you even though it once was.

What to do. Ask an admin to renew it on the Grants page. Nothing on your machine needs changing.

agentgov status

Confirms which repository and work item this session is currently attached to.

The account is deactivated

Your account is not active.

An admin has deactivated the account, or offboarding has run. Every repository is unavailable while this is true, not just the one you were in.

What to do. Ask an admin to reactivate you on the Team page.

The work item did not resolve

That work item could not be validated with your tracker.

When a tracker is connected, a reference that looks like a ticket id is checked against it. The id matched nothing, so it was refused rather than filed against a ticket that does not exist.

What to do. Check the id, or use a short label instead — anything in brackets works, for example [payment-retry-spike]. A label needs no tracker.

The session is not bound to a work item

Start your prompt with a work item in square brackets.

Every session must be attached to a work item before any tokens are spent — that is what makes the spend attributable. Nothing was sent and nothing was charged.

What to do. Open your prompt with the work item in brackets: [PROJ-1234] add the retry loop. You only need it once; later prompts in the same session inherit it until you write a new one.

agentgov workitem PROJ-1234

Binds without sending a prompt. The bracket form is usually easier.

All commands

Run these in a terminal, from inside the repository you are working in. None of them send a prompt or spend tokens.

agentgov doctor: Checks every step in order and names the first one failing. Start here.
agentgov doctor --fix: Repairs what it safely can — mainly missing or stale hook files.
agentgov status: Which repository and work item this session is attached to.
agentgov gateway logs: Why the gateway refused something, in its own words.
agentgov gateway install: Starts the local gateway as a background service.
agentgov --version: Which CLI version is installed. Worth quoting in a bug report.

Reinstalling from scratch

Try this only after agentgov doctor, which usually names something smaller. Removing and reinstalling does not fix a problem in a single editor window — the hooks are shared by every window on the machine, so if one project works and another does not, the installation is already correct. Close and reopen the window that is failing instead.

1. Remove

agentgov uninstall

Deregisters the hooks before deleting them, so a half-removed install cannot break your editor. Your data in the dashboard is untouched.

2. Reinstall

The install commands carry your own token, so they are different for every person and cannot be printed here. Sign in and open Setup — it shows the exact three commands for your account, ready to copy.

Open Setup Sign-in required — that is where your token lives.

No account yet? Someone at your company has to invite you first. If you cannot sign in at all, that is the problem to solve — not the install.

Still stuck

Send the output of agentgov doctor to info@aicodekeyshare.com. It contains no prompts, no code and no credentials — only which checks passed and which did not.