Octocode Install — Interactive Setup

DETECT → CHECK INSTALLED → NODE → AUTH → INSTALL MCP → SKILLS → VERIFY

Agent rule: Detect what you can from context. Ask only what you can't determine. One step at a time — wait for the user's answer before proceeding.

Step 0 — Detect Platform & IDE

Check the conversation and environment context first:

• Platform: Is the OS already known? (macOS/Linux vs Windows)
• IDE: Is the user in Cursor, Claude Code, Claude Desktop, Windsurf, VS Code, Zed, Opencode, Trae, Kiro, Codex, Gemini CLI, Goose, Antigravity?

If either is unknown, ask:

"What platform are you on, and which IDE/client are you setting up?" - macOS / Linux - Windows

>

IDE: Cursor · Claude Code · Claude Desktop · Windsurf · Trae · Kiro · Antigravity · VS Code (Cline/Roo/Continue) · Zed · Opencode · Codex · Gemini CLI · Goose

Carry both answers through all remaining steps.

Step 1 — Check if Already Installed

Read the IDE's MCP config file (see config paths table below) and check whether an "octocode" or "octocode-mcp" server entry already exists.

Also run:

npx octocode status

If octocode-mcp is already configured in the IDE AND authenticated:

Tell the user: "Octocode is already installed and authenticated in your IDE. You're all set!"

>

Offer: "Would you like to update (npx octocode install --ide <key> --force), install skills, or change config?"

STOP here — do not continue with Steps 2–6 unless the user asks to update, reinstall, or add something.

Step 2 — Node.js

node --version

• v18+ → continue
• Missing or old → tell the user to install it, then wait for confirmation:
• macOS: brew install node or nodejs.org
• Windows: winget install OpenJS.NodeJS or nodejs.org

Ask: "Does node --version show v18 or higher now?"

Step 3 — GitHub Authentication

Ask the user:

"How would you like to authenticate with GitHub?" 1. `npx octocode login` — Octocode OAuth (opens browser, stores token automatically) 2. `gh auth login` — GitHub CLI (if gh is already installed) 3. GitHub PAT (token) — paste a token manually; always works, required on Windows if browser auth fails

Option 1 — Octocode OAuth (recommended)

npx octocode login

• Opens browser → approve the device code → done
• Token stored encrypted at ~/.octocode/credentials.json
• Automatically used by octocode-mcp — no env var needed

Windows: If the browser doesn't open or the command hangs, switch to Option 3 (PAT).

Option 2 — GitHub CLI

Requires gh already installed (cli.github.com):

gh auth login

• Follow the interactive prompts
• octocode-mcp reads the token via gh auth token automatically

Option 3 — GitHub PAT (always works, required on Windows if OAuth fails)

1. Create token at github.com/settings/tokens/new

• Scopes: repo + read:org

1. Copy the token — you'll paste it as GITHUB_TOKEN in the MCP config (Step 4)

After auth, verify:

npx octocode status

Expected: ✓ Authenticated as <username>

If not authenticated — repeat the chosen option or switch to Option 3.

Step 4 — Install MCP for IDE

If IDE is unknown, ask:

"Which IDE/client do you want to install octocode-mcp into?"

Run:

npx octocode install --ide <key>

The CLI writes the config file automatically. Then confirm the result:

What the config looks like

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": ["octocode-mcp@latest"]
    }
  }
}

Ask — enable local tools

"Do you want to enable local codebase tools (search files, LSP, browse dirs)? Recommended — Yes." → Yes: add "ENABLE_LOCAL": "true" to "env"

"Did you use a PAT (Option 3) for auth, or is npx octocode status not showing authenticated?" → Yes: add "GITHUB_TOKEN": "ghp_xxx" to "env"

Full config with all options:

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": ["octocode-mcp@latest"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx",
        "ENABLE_LOCAL": "true"
      }
    }
  }
}

Token resolution order (octocode-mcp picks the first found): OCTOCODE_TOKEN → GH_TOKEN → GITHUB_TOKEN → ~/.octocode/credentials.json → gh auth token If you used OAuth or gh auth login, you can omit GITHUB_TOKEN.

Restart the IDE after saving the config.

Step 5 — Install Octocode Skills

Ask the user:

"Would you like to install all Octocode skills? These add research, planning, code review, documentation, and more to your AI assistant."

• No → skip to Step 6
• Yes → ask which targets:

"Which AI clients should skills be installed into?" - Current IDE only (detected in Step 0) - All supported platforms (cursor, claude-code, claude-desktop, codex, opencode)

Then run:

npx octocode skills install --targets <selected-targets> --force

This installs 10 bundled skills:

After install, verify:

npx octocode skills list

Expected: all skills show installed for each target.

Step 6 — Verify

npx octocode status       # auth check
npx octocode skills list  # skills install check

Then open the IDE and test:

"Use octocode-engineer to find the main entry point of this project"

Tools responding = setup complete.

Using Skills

• Local tools require ENABLE_LOCAL=true in MCP config
• Skill not triggering? Name it explicitly: "use octocode-engineer to..."
• More skills: npx octocode → Manage Skills → Browse Marketplace

Troubleshooting

Docs: Auth · CLI Reference · Skills