openviking

What this skill does

# 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 |

```bash
# 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.
```bash
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

```bash
# 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

```bash
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

```bash
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

```bash
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:
```bash
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:
  ```bash
  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:

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