Library Navigation

Library navigation lets you explore third-party dependency source code using the same symbol tools you use for your own project — symbols, symbols, symbol_at, semantic_search — without switching contexts or manually locating package directories.

Auto-Discovery

Libraries are discovered automatically. When you call symbol_at on a symbol and the LSP resolves it to a path outside the project root (typically inside a language package cache), codescout registers that path as a library and names it by the package name inferred from the manifest it finds there.

The next time you call list_libraries, the dependency appears in the list. No manual registration is required for the common case.

The Scope Parameter

Once a library is registered, pass scope to any navigation or search tool to target it:

{
  "tool": "semantic_search",
  "arguments": { "query": "retry with backoff", "scope": "lib:reqwest" }
}

Results include a "source" field so you can tell project code from library code at a glance.

Building a Library Index

Semantic search over library code requires an embedding index, just like project code. Build one with index(action: build) pointed at the library’s root path:

{ "tool": "index(action: build)", "arguments": { "path": "/path/to/tokio-1.35.1/" } }

This is a one-time cost per library. The index persists in .codescout/embeddings/lib/<name>.db — see Per-Library Embedding Databases below.

When to Use Library Navigation

• You’re debugging an unfamiliar error from a dependency and want to read its source without leaving your session
• You want to understand how a library’s internal types relate before writing integration code
• You’re doing a security audit and want to trace a call chain into a dependency
• You want to find usage examples by searching the library’s own tests with semantic_search(scope: "lib:<name>")

Further Reading

• Library Navigation Tools — full reference for list_libraries and library indexing
• Symbol Navigation Tools — the tools that accept the scope parameter
• Semantic Search Tools — semantic search within library scope

Per-Library Embedding Databases

Earlier versions stored all embeddings in a single .codescout/embeddings.db. The current layout splits storage into separate databases:

.codescout/
  embeddings/
    project.db          ← your project's code
    lib/
      tokio.db          ← one file per registered library
      serde.db
      reqwest.db

The filename for each library is derived from its registered name: / and \ are replaced with -- and the result is lowercased (e.g. @org/pkg → org--pkg.db).

Migration is automatic. If an old embeddings.db is found, codescout moves its contents into the new structure the first time the project is opened. No manual steps required.

To build or rebuild a library’s index:

{ "tool": "index(action: build)", "arguments": { "scope": "lib:tokio" } }

Version Tracking and Staleness Hints

When index(action: build, scope="lib:<name>") runs, codescout reads the project’s lockfile (Cargo.lock, package-lock.json, etc.) to record the library version that was indexed.

After a dependency upgrade, semantic_search includes a stale_libraries field:

{
  "stale_libraries": [
    {
      "name": "tokio",
      "indexed": "1.37.0",
      "current": "1.38.0",
      "hint": "tokio was updated — run index(action: build, scope='lib:tokio') to re-index"
    }
  ]
}

Staleness is detected by comparing indexed vs current versions from the lockfile. If the lockfile ecosystem is not recognised, version tracking is skipped.