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:

cp /path/to/OpenViking/examples/ov.conf.example ~/.openviking/ov.conf

Then fill in your API keys. Minimum required fields:

{
  "embedding": {
    "provider": "openai",
    "api_key": "sk-..."
  },
  "vlm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "api_key": "sk-..."
  }
}

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