openviking-opencode

OpenViking official plugin for OpenCode.

Automatically injects your indexed code repositories into the AI assistant's context, so it proactively searches them without you having to ask.

What It Does

• Auto-installs the openviking skill into ~/.config/opencode/skills/openviking/ on first load
• Injects indexed repo summaries into the system prompt so the AI knows what's available
• Auto-starts the OpenViking server if it's installed and configured but not running
• Shows clear toast notifications if setup is incomplete (missing install, missing config, failed start)

Prerequisites

1. Install OpenViking

pip install openviking

2. Configure OpenViking

OpenViking requires an embedding model and a VLM (for generating directory summaries). Create ~/.openviking/ov.conf with the following structure:

{
  "server": {
    "host": "0.0.0.0",
    "port": 1933,
    "api_key": null,
    "cors_origins": ["*"]
  },
  "storage": {
    "workspace": "/path/to/your/workspace",
    "vectordb": {
      "name": "context",
      "backend": "local",
      "project": "default"
    },
    "agfs": {
      "port": 1833,
      "log_level": "warn",
      "backend": "local",
      "timeout": 10,
      "retry_times": 3
    }
  },
  "embedding": {
    "dense": {
      "model": "your-embedding-model",
      "api_key": "your-api-key",
      "api_base": "https://your-provider/api/v3",
      "dimension": 1024,
      "provider": "openai",
      "input": "multimodal"
    },
    "max_concurrent": 100
  },
  "vlm": {
    "model": "your-vlm-model",
    "api_key": "your-api-key",
    "api_base": "https://your-provider/api/v3",
    "temperature": 0,
    "max_retries": 2,
    "provider": "openai",
    "thinking": false
  },
  "auto_generate_l0": true,
  "auto_generate_l1": true,
  "default_search_mode": "thinking",
  "default_search_limit": 3,
  "log": {
    "level": "WARNING"
  }
}

Important: set embedding.max_concurrent to at least 100. The default value is too low — indexing a repo will be extremely slow without this. Each file requires an embedding call, and low concurrency means they queue up one by one.

See the OpenViking docs for all supported providers.

3. Install OpenCode

npm install -g opencode-ai

Installation

Add the plugin to your OpenCode config at ~/.config/opencode/opencode.json:

{
  "plugin": ["openviking-opencode"]
}

OpenCode will automatically install the plugin via bun on next startup. No other steps needed — the skill is installed automatically.

Usage

Index a repository

Once OpenViking is running, index any GitHub repo or local project:

# In OpenCode, just ask:
"Add https://github.com/tiangolo/fastapi to OpenViking"

Indexing runs in the background. Small repos (~100 files) take 2–5 min; large repos (500+ files) can take 20–60 min. Search works progressively as files are indexed.

Search automatically

Once repos are indexed, the AI will proactively search them when relevant — no need to ask:

"How does fastapi handle dependency injection?"
→ AI automatically searches viking://resources/fastapi/ before answering

"How is authentication implemented in my-project?"
→ AI automatically searches viking://resources/my-project/ before answering

Trigger manually

You can also explicitly invoke the skill:

"Use openviking to find how JWT tokens are verified in my projects"

Best Practices

Keep the server running persistently

The plugin auto-starts the server when OpenCode launches, but for the best experience start it as a background service:

openviking serve --config ~/.openviking/ov.conf > /tmp/openviking.log 2>&1 &

Or add it to your shell profile (~/.zshrc / ~/.bashrc):

# Auto-start OpenViking if not already running
openviking health 2>/dev/null || openviking serve --config ~/.openviking/ov.conf > /tmp/openviking.log 2>&1 &

Use viking://resources/ for all code repos

Always index under viking://resources/ — this is the scope the plugin and skill are configured to search:

openviking add-resource https://github.com/owner/repo --to viking://resources/
openviking add-resource /path/to/project --to viking://resources/

Index repos you reference often

The more repos indexed, the more useful the AI becomes. Good candidates:

• Internal libraries your project depends on
• Open source libraries you frequently look up
• Other projects in your monorepo

Don't index everything

Avoid indexing repos you rarely touch — it adds noise to search results. Use openviking rm viking://resources/repo --recursive to remove repos you no longer need.

Troubleshooting

License

Apache-2.0