Concepts

Items

An item is some information that is relevant to parts of a code file, such as:

• A link to an internal wiki page with documentation about a package
• A link to live logs being printed by a logging statement
• A design mockup (image) showing how a UI component should appear
• A user analytics chart showing how often a certain UI button is pressed

The item describes how to present the information to the user and exposes raw information to code AI tools.

See the protocol documentation for the schema of items.

Providers

A provider returns items for a code file.

A provider is just a program that implements the provider API, which is basically: "given a file, return a list of items (for ranges in the file)".

Although there is no formal distinction between different kinds of providers, most providers will fit into one of these categories:

• Tool provider: a provider that integrates with an external dev tool (such as a log viewer or issue tracker) and provides relevant information from that tool.
• Custom provider: a provider that shows information from your custom internal dev tools or based on ad-hoc code analysis for your specific needs.
• Proxy provider: a provider that wraps other providers, for caching, configuration, authentication, etc.

See "Provider API" for more information.

User configuration

A list of provider URIs is the only configuration needed for OpenCtx.

To use a provider in your editor, you just need its URL (e.g., https://example.com/openctx).

For example, the following is an example of VS Code user settings for OpenCtx:

The first provider (https://sourcegraph.com/.api/openctx) is an HTTP endpoint. The others are JavaScript bundles that are executed on the client.

See the playground for examples of providers with settings.

Open questions & known issues

Authenticating with providers

How do clients authenticate with providers? Right now, a few hostnames are hard-coded in the VS Code extension as needing authentication, and the user will be prompted for a token. Should clients prompt the user for authentication when the server returns HTTP 401 Unauthorized? There is no standard way for authenticating to services, so this would not work in general.

Implementing providers: thin clients or lots-of-logic?

Will OpenCtx providers be super lightweight presentation-layer programs that hit some existing system that makes the data easy to fetch? Maybe that existing system is a separate server built for OpenCtx to hit for now, but ideally in the future (years) it would become a common endpoint for dev tools vendors to expose, like oEmbed.

Recording additional metadata

How should items record other kinds of metadata to make it searchable and exportable? For example, the Storybook provider could add {"storybook": true} metadata in an item on all storybook files, which would make it possible to identify all storybook files in a code search application.

Multiple resolution passes

Should items initially be returned with minimal information that can be quickly produced, and then resolved to provide additional detail (such as when the user interacts with the chip)?