Troubleshoot CLI Agent Connect

Use this guide when Claude Code, Codex, Gemini, Cursor, OpenCode, or another local agent cannot connect to a GitGhost AI project or does not produce a captured session.

Confirm CLI Auth

gitghost-cli auth status

If the CLI is not signed in:

gitghost-cli auth login

Retry The Guided Start

From the affected checkout, run:

gitghost-cli start
gitghost-cli status --verbose

The normal path lists repositories available to your account and does not require a connect code. Confirm that the verbose status names the intended local repository and GitGhost project.

Confirm The Code Type For Delegated Access

There are two different codes:

Code	Created by	Used for
CLI login code	gitghost-cli auth login	Signing the CLI into your Gitghost AI account.
Local-agent connect code	Gitghost AI project AI chat or agent panel	Linking one local agent to one project.

Using the CLI login code with agent connect will not work.

Use a project connect code only when an organization delegated one repository to you. Do not use the code from gitghost-cli auth login for this purpose.

Delegated Connect Command

gitghost-cli start --code <short-code> --agent codex

Use the correct agent identifier for your local tool.

Policy Block

If Gitghost AI shows:

Local agent sync is disabled by project Agent Policy

the project or organization policy blocks local agent sync. Ask a project admin to review the AI Agent Policy and allow the agent type you want to connect.

Git Push Still Asks For Credentials

CLI login and local agent connect do not automatically change your Git remote. Git push uses Git's credential helper for the repository URL.

Use:

gitghost-cli auth status
gitghost-cli project git-credentials
git push origin main

The remote should stay in this form:

https://gitghost.ai/git/<owner>/<project>.git

Do not put tokens into the remote URL. If push still fails, confirm the project token has Git read/write scope and that credential.useHttpPath is enabled for the repository.

Safe Checks

• Confirm you can open Gitghost AI in a browser.
• Confirm you have access to the project.
• For direct account access, confirm gitghost-cli start lists the intended project.
• For delegated access, confirm the project connect code was generated recently.
• Confirm the agent kind is allowed by project policy.
• Confirm CLI login, project connection, and Git credentials were completed separately.
• Run gitghost-cli doctor.

Do not share tokens, one-time codes, connect-code screenshots, or private project details in support messages.