OpenViking openviking

Activate when the user asks about any repository listed in the system prompt under 'OpenViking — Indexed Code Repositories', or when they ask about an external library, framework, or project that may have been indexed. Also activate when the user wants to add, remove, or manage repos. Always search the local codebase first before using this skill.

install

source · Clone the upstream repo

git clone https://github.com/volcengine/OpenViking

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/volcengine/OpenViking "$T" && mkdir -p ~/.claude/skills && cp -r "$T/examples/opencode/plugin/skills/openviking" ~/.claude/skills/volcengine-openviking-openviking && rm -rf "$T"

manifest: examples/opencode/plugin/skills/openviking/SKILL.md

source content

OpenViking Code Repository Search

IMPORTANT: All

ov

commands are terminal (shell) commands — run them via the
bash
tool. Execute directly — no pre-checks, no test commands. Handle errors when they occur.

How OpenViking Organizes Data

OpenViking stores content in a virtual filesystem under the

viking://

namespace. Each URI maps to a file or directory, e.g.

viking://resources/fastapi/routing.py

. Each directory has AI-generated summaries (

abstract

overview

). The key principle: narrow the URI scope to improve retrieval efficiency. Instead of searching all repos, lock to a specific repo or subdirectory — this reduces noise and speeds up results significantly.

Search Commands

Choose the right command based on what you're looking for:

Command	Use when	Example
`ov search`	Semantic search — use for concept/intent based queries	"dependency injection", "how auth works"
`ov grep`	You know the exact keyword or symbol	function name, class name, error string
`ov glob`	You want to enumerate files by pattern	all `*.py` files, all test files

# Semantic search
ov search "dependency injection" --uri viking://resources/fastapi --limit 10
ov search "how tokens are refreshed" --uri viking://resources/fastapi/fastapi/security
ov search "JWT authentication" --limit 10          # across all repos
ov search "error handling" --limit 5 --threshold 0.7  # filter low-relevance results

# Keyword search — exact match or regex
ov grep "verify_token" --uri viking://resources/fastapi
ov grep "class.*Session" --uri viking://resources/requests/requests

# File enumeration — by name pattern (always specify --uri to scope the search)
ov glob "**/*.py" --uri viking://resources/fastapi
ov glob "**/test_*.py" --uri viking://resources/fastapi/tests
ov glob "**/*.py" --uri viking://resources/   # across all repos

Narrowing scope: once you identify a relevant directory, pass it as

--uri

to restrict subsequent searches to that subtree — this is faster and more precise than searching the whole repo.

Query formulation: write specific, contextual queries rather than single keywords.

ov search "API"                                                       # too vague
ov search "REST API authentication with JWT tokens"                   # better
ov search "JWT token refresh flow" --uri viking://resources/backend   # best

Read Content

# Directories: AI-generated summaries
ov abstract viking://resources/fastapi/fastapi/dependencies/   # one-line summary
ov overview viking://resources/fastapi/fastapi/dependencies/   # detailed breakdown

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

abstract

overview

only work on directories.

read

only works on files.

Browse

ov ls viking://resources/                        # list all indexed repos
ov ls viking://resources/fastapi                 # list repo top-level contents
ov ls viking://resources/fastapi --simple        # paths only, no metadata
ov ls viking://resources/fastapi --recursive     # list all files recursively
ov tree viking://resources/fastapi               # full directory tree (default: 3 levels deep)
ov tree viking://resources/fastapi -L 2          # limit depth to 2 levels
ov tree viking://resources/fastapi -l 200        # truncate abstract column to 200 chars
ov tree viking://resources/fastapi -L 2 -l 200   # combined: 2 levels deep, 200-char summaries

-L

controls how many levels deep the tree expands.

-l

controls the length of the AI-generated summary per directory. Use

ov tree -L 2 -l 200

as a good starting point to understand a repo's structure before diving in.

Add a Repository

ov add-resource https://github.com/owner/repo --to viking://resources/repo --timeout 300

--timeout

is required (seconds). Use 300 (5 min) for small repos, increase for larger ones.

After submitting, run

ov observer queue

once and report status to user. Indexing runs in background — do not poll or wait.

Repo Size	Files	Est. Time
Small	< 100	2–5 min
Medium	100–500	5–20 min
Large	500+	20–60+ min

Remove a Repository

ov rm viking://resources/fastapi --recursive

This permanently deletes the repo and all its indexed content. Confirm with the user before running.

Error Handling

command not found: ov

→ Tell user:

pip install openviking --upgrade

. Stop.

url is required

/
CLI_CONFIG
error → Auto-create config and retry:

mkdir -p ~/.openviking && echo '{"url": "http://localhost:1933"}' > ~/.openviking/ovcli.conf

CONNECTION_ERROR

/ failed to connect:

~/.openviking/ov.conf

exists → auto-start server, wait until healthy, retry:

openviking-server > /tmp/openviking.log 2>&1 &
for i in $(seq 1 10); do ov health 2>/dev/null && break; sleep 3; done

Does not exist → Tell user to configure
```
~/.openviking/ov.conf
```
first. Stop.

More Help

For other issues or command details, run:

ov help
ov <command> --help   # e.g. ov search --help