OpenCode Integration

Semantic code search plugin for OpenCode AI coding assistant

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

Explicit Search

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:

Command	When to Use	Example
ov find	Concept/intent search	”dependency injection”, “rate limiting logic”
ov grep	Exact keyword/symbol	Function names, class names, error strings
ov glob	File enumeration	All *.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

Command not found: ov

OpenViking CLI is not installed:

pip install openviking --upgrade --force-reinstall

Connection error

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).

Skill not loading

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.

Searches return no results

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

• OpenCode Documentation
• Semantic Search
• Adding Resources