Skip to main content

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.

Confirm CLI Auth​

gitghost-cli auth status

If the CLI is not signed in:

gitghost-cli auth login

Confirm The Code Type​

There are two different codes:

CodeCreated byUsed for
CLI login codegitghost-cli auth loginSigning the CLI into your Gitghost AI account.
Local-agent connect codeGitghost AI project AI chat or agent panelLinking one local agent to one project.

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

If you see --code is required, open the project AI chat or local agent panel and generate a local-agent connect code. Do not use the code from gitghost-cli auth login for this command.

Connect Command​

gitghost-cli agent connect --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.
  • Confirm the connect code was generated recently.
  • Confirm the agent kind is allowed by project policy.
  • Confirm CLI login, local-agent connect, 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.