Skip to main content
The OpenViking plugin for OpenCode provides semantic search across your indexed repositories. Once installed, the AI can search through any repo you’ve added to OpenViking, understanding concepts and intent rather than just matching keywords.

​
Prerequisites

  • OpenCode installed
  • OpenViking installed: pip install openviking --upgrade --force-reinstall
  • OpenViking CLI configured at ~/.openviking/ovcli.conf
  • OpenViking Server running with ~/.openviking/ov.conf

​
Installation

1

Install OpenViking

pip install openviking --upgrade --force-reinstall
2

Configure Server

Create ~/.openviking/ov.conf:
{
  "storage": {
    "workspace": "/path/to/your/workspace"
  },
  "embedding": {
    "dense": {
      "provider": "openai",
      "model": "text-embedding-3-large",
      "api_key": "your-api-key",
      "api_base": "https://api.openai.com/v1",
      "dimension": 3072
    },
    "max_concurrent": 100
  },
  "vlm": {
    "provider": "openai",
    "model": "gpt-4o",
    "api_key": "your-api-key",
    "api_base": "https://api.openai.com/v1"
  }
}
For Volcengine, Anthropic, DeepSeek, Ollama, and other providers, see the Configuration Reference.
3

Start OpenViking Server

openviking-server --config ~/.openviking/ov.conf > /tmp/openviking.log 2>&1 &
Verify it’s running:
ov health
4

Add Plugin to OpenCode

Edit ~/.config/opencode/opencode.json:
{
  "plugin": ["openviking-opencode"]
}
Restart OpenCode — the skill is installed automatically.

​
Usage

​
Index a Repository

Simply ask in the chat: 
Add https://github.com/tiangolo/fastapi to OpenViking
The AI will execute: 
ov add-resource https://github.com/tiangolo/fastapi --to viking://resources/ --timeout 300
Indexing runs in the background. Check status: 
ov observer queue
Indexing Times:
  • Small repos (< 100 files): 2–5 minutes
  • Medium repos (100–500 files): 5–20 minutes
  • Large repos (500+ files): 20–60+ minutes

​
Search Indexed Repos

Once indexed, searches happen automatically when relevant: 
How does FastAPI handle dependency injection?
The AI will:
  1. Detect you’re asking about an indexed repo (FastAPI)
  2. Load the openviking skill
  3. Run semantic search: ov find "dependency injection" --uri viking://resources/fastapi --limit 10
  4. Read relevant files and answer your question
You can also trigger searches explicitly: 
Use OpenViking to find how JWT tokens are verified in FastAPI

​
Browse Indexed Repos

List all repos in OpenViking
Executes: 
ov ls viking://resources/

​
How It Works

​
Directory Structure

OpenViking organizes code in a virtual filesystem: 
viking://
└── resources/
    ├── fastapi/               ← repo A
    │   ├── fastapi/
    │   │   ├── routing.py
    │   │   └── dependencies/
    │   └── tests/
    └── requests/              ← repo B
        ├── requests/
        └── tests/
Each directory has AI-generated summaries:
  • abstract: One-line summary for quick scanning
  • overview: Detailed breakdown of purpose and structure

​
Search Types

The plugin uses three search strategies:
CommandWhen to UseExample
ov findConcept/intent search”dependency injection”, “rate limiting logic”
ov grepExact keyword/symbolFunction names, class names, error strings
ov globFile enumerationAll *.py files, all test files
Examples: 
# Semantic search
ov find "JWT authentication" --uri viking://resources/fastapi --limit 10
ov find "how tokens are refreshed" --uri viking://resources/fastapi/fastapi/security

# Keyword search
ov grep "verify_token" --uri viking://resources/fastapi
ov grep "class.*Session" --uri viking://resources/requests

# File patterns
ov glob "**/*.py" --uri viking://resources/fastapi
ov glob "**/test_*.py" --uri viking://resources/fastapi/tests

​
Context Injection

When indexed repos are available, the plugin injects context into the system prompt: 
## OpenViking — Indexed Code Repositories

The following repos are semantically indexed and searchable.
When the user asks about any of these projects, you MUST use the openviking skill:

- **fastapi** (viking://resources/fastapi)
  A modern, fast web framework for building APIs with Python 3.7+
  
- **requests** (viking://resources/requests)
  Python HTTP library for humans
This ensures the AI knows what’s available and when to use it.

​
Advanced Features

​
Narrow Search Scope

For faster, more precise results, narrow the URI scope: 
# Instead of searching entire repo:
ov find "token refresh" --uri viking://resources/fastapi

# Search specific subdirectory:
ov find "token refresh" --uri viking://resources/fastapi/fastapi/security

​
Read Content

# Get directory summaries
ov abstract viking://resources/fastapi/fastapi/dependencies/   # one-line
ov overview viking://resources/fastapi/fastapi/dependencies/   # detailed

# Read file content
ov read viking://resources/fastapi/fastapi/dependencies/utils.py
ov read viking://resources/fastapi/fastapi/dependencies/utils.py --offset 100 --limit 50

​
Remove Repository

ov rm viking://resources/fastapi --recursive
This permanently deletes the repo and all indexed content. The AI will confirm before executing.

​
Configuration

​
Auto-Start Server

The plugin automatically starts the OpenViking server if:
  • ov command is installed
  • ~/.openviking/ov.conf exists
  • Server is not already running
It waits up to 30 seconds for the server to become healthy.

​
CLI Config

Create ~/.openviking/ovcli.conf: 
{
  "url": "http://localhost:1933",
  "timeout": 60.0,
  "output": "table"
}
The plugin will auto-create this if missing.

​
Troubleshooting

OpenViking CLI is not installed:
pip install openviking --upgrade --force-reinstall
Server is not running. Check if ~/.openviking/ov.conf exists:
# If config exists, start server:
openviking-server --config ~/.openviking/ov.conf > /tmp/openviking.log 2>&1 &

# Wait for health check:
for i in $(seq 1 10); do ov health 2>/dev/null && break; sleep 3; done
If config doesn’t exist, create it first (see Installation step 2).
Verify the skill was installed:
ls -la ~/.config/opencode/skills/openviking/SKILL.md
If missing, reinstall the plugin or manually copy the skill file from the OpenViking repo.
Check if the repo is indexed:
ov ls viking://resources/
If your repo is missing, add it:
ov add-resource https://github.com/owner/repo --to viking://resources/ --timeout 300

​
Example Workflow

You: Add https://github.com/encode/starlette to OpenViking
AI: [Executes add-resource command]
    Repository is being indexed. This will take 5-10 minutes.
    
You: How does Starlette handle middleware?
AI: [Automatically searches OpenViking]
    Starlette uses a middleware stack pattern. Here's how it works...
    
    [Shows relevant code from starlette/middleware/base.py]

​
See Also