Troubleshooting

Use the section for the setup step that failed.

Agent or installation issues

If code, git, or gh is not found, open a new terminal. On macOS, open Visual Studio Code, run the Command Palette, and choose Shell Command: Install 'code' command in PATH.

On a managed device, ask IT to install or approve Visual Studio Code, Git, GitHub CLI, and your chosen agent.

If the Claude Code or Codex extension is missing in Visual Studio Code, open Extensions with Command Shift X on macOS or Ctrl Shift X on Windows and Linux, search for the selected agent, and install the official extension. If the panel still does not appear, restart Visual Studio Code or run Developer: Reload Window from the Command Palette.

GitHub sign-in issues

If GitHub CLI cannot sign in, run:

gh auth logout
gh auth login
gh auth setup-git

Choose GitHub.com, HTTPS, and browser sign-in. If your organization blocks the request, ask a GitHub organization owner to approve it.

Repository access issues

For a new workspace, confirm the repository was created as private and that the selected owner is correct.

For an existing workspace, confirm you accepted the GitHub invitation and are cloning the repository URL supplied by the workspace owner.

gh auth status
git remote -v

You should see the GitHub account that has access and the intended repository URL.

Skills issues

If ACT Playbook skills do not appear, confirm GitHub CLI is authenticated and reinstall the pack:

gh auth status
gh skill install act-playbook/act-playbook-skills --all --scope user

Select your chosen agent, then restart or reload it.

MCP OAuth issues

If ACT Playbook MCP authentication fails or shows the wrong organization, disconnect the server, sign out of the unintended ACT Playbook account in your browser, reconnect, and complete OAuth again.

For Codex CLI:

codex mcp login act-playbook
codex mcp list

For Claude Code, enter /mcp, select act-playbook, and run the authentication action.

Verification issues

Run the final checks from the repository root:

code --version
git --version
gh --version
git remote -v
git status
gh auth status

Then ask your agent to list installed ACT Playbook skills and identify the connected ACT Playbook organization.