abhigyanpatwari/GitNexus · error · Error

OpenCode CLI not found. Install OpenCode CLI and ensure `ope

Error message

OpenCode CLI not found. Install OpenCode CLI and ensure `opencode` is on PATH.

What it means

callOpenCodeLLM resolves the `opencode` executable through getDetectedCommand('opencode') before doing anything else. If detection fails (no opencode binary reachable on the PATH of the GitNexus process), it throws immediately with install guidance rather than spawning and failing cryptically.

Source

Thrown at gitnexus/src/core/wiki/local-cli-client.ts:244

  };

  if (provider === 'opencode') {
    delete env.OPENCODE_SERVER_PASSWORD;
    delete env.OPENCODE_SERVER_USERNAME;
  }

  return env;
}

export async function callOpenCodeLLM(
  prompt: string,
  config: LocalCLIConfig,
  systemPrompt?: string,
  options?: CallLLMOptions,
): Promise<LLMResponse> {
  const commandInfo = getDetectedCommand('opencode');
  if (!commandInfo) {
    throw new Error(
      'OpenCode CLI not found. Install OpenCode CLI and ensure `opencode` is on PATH.',
    );
  }

  const workingDirectory = config.workingDirectory || process.cwd();
  const fullPrompt = systemPrompt ? `${systemPrompt}\n\n---\n\n${prompt}` : prompt;
  // OpenCode does not expose a Codex-style read-only sandbox / no-tools flag,
  // so we rely on its non-interactive permission model and tolerate any
  // non-JSON stdout warnings in the parser.
  const args = ['run', '--format', 'json', '--dir', workingDirectory];

  if (config.model) {
    args.push('--model', config.model);
  }

  const response = await runLocalCLI('opencode', commandInfo, args, config, fullPrompt, options);
  return { content: parseOpenCodeEventStream(response.content) };
}

View on GitHub (pinned to 52924ef12c)

Solutions

Install OpenCode CLI: `curl -fsSL https://opencode.ai/install | bash` or `npm install -g opencode-ai`.
Verify resolution in the same environment GitNexus runs in: `which opencode && opencode --version`.
Add the install's bin directory to PATH (export PATH="$PATH:$HOME/.opencode/bin" or the npm global bin dir) in the shell profile, service unit, or CI env.
If you cannot install it, switch the wiki generator's provider away from 'opencode' so GitNexus never attempts detection.

Example fix

# before: binary not on PATH of the GitNexus process
$ gitnexus wiki generate --provider opencode
Error: OpenCode CLI not found. Install OpenCode CLI and ensure `opencode` is on PATH.

# after: install, verify, retry
$ npm install -g opencode-ai
$ which opencode && opencode --version
$ gitnexus wiki generate --provider opencode

Defensive patterns

Strategy: validation

Validate before calling

import { execFileSync } from 'node:child_process';

function opencodeAvailable(): boolean {
  try {
    execFileSync(process.platform === 'win32' ? 'where' : 'which', ['opencode'], { stdio: 'ignore' });
    return true;
  } catch {
    return false;
  }
}

if (config.wiki?.provider === 'opencode' && !opencodeAvailable()) {
  throw new Error('opencode selected for wiki but not on PATH — install it or change provider');
}

Try / catch

try {
  return await callOpenCodeLLM(prompt, config);
} catch (err) {
  if (err instanceof Error && err.message.includes('OpenCode CLI not found')) {
    // configuration problem, not transient: switch provider or surface install instructions
    return useNonLLMWikiFallback();
  }
  throw err;
}

Prevention

Verify `which opencode` inside the exact environment gitnexus runs in (CI, IDE, service units strip PATH).
Install opencode in a standard bin location or add its bin dir to PATH in the service/CI env.
Add a startup check for the configured provider's binary before launching long jobs.

When it happens

Trigger: Enabling wiki generation or any local-LLM step with provider 'opencode' on a machine where the opencode binary is not installed, is installed under a bin directory absent from PATH, or GitNexus runs in an environment with a stripped PATH (IDE-launched shells, launchd, minimal CI containers, nvm node bin mismatch).

Common situations: Fresh machine without opencode; installed via a non-default package manager prefix (pnpm/bun global dirs) not on PATH; running GitNexus from an IDE terminal or systemd/launchd unit where PATH differs from the login shell; switching wiki provider to 'opencode' without ever installing it.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-08-20). Data as JSON: /api/errors/6ddd297fa4a8e690. Report an issue: GitHub.