Configuration

kinetic-context uses JSON configuration files to manage OpenCode settings, packages, and projects.

OpenCode Configuration

The OpenCode configuration file controls which AI model and provider to use for answering questions about dependencies.

Location: ~/.kctx/config/opencode.json (or /config/opencode.json in Docker)

OpenRouter Example

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenRouter",
      "options": {
        "baseURL": "https://openrouter.ai/api/v1",
        "apiKey": "your-api-key-here"
      },
      "models": {
        "openrouter/anthropic/claude-3.5-sonnet": {
          "name": "Claude 3.5 Sonnet"
        }
      }
    }
  },
  "model": "openrouter/anthropic/claude-3.5-sonnet"
}

Supported Providers

OpenCode supports multiple providers. See the OpenCode providers documentation for a complete list and configuration examples.

Common providers include:

• OpenRouter
• OpenAI
• Anthropic
• Google (Gemini)
• And more...

Package Configuration

Package configuration files define which dependencies are available for querying.

Location: ~/.kctx/data/packages/ (or /data/packages/ in Docker)

Package Config Format

Each package needs a JSON configuration file. The filename should match the package identifier (e.g., @hookform/resolvers.json).

{
  "identifier": "@hookform/resolvers",
  "package_manager": "npm",
  "display_name": "React Hook Form - Resolvers",
  "default_tag": "master",
  "urls": {
    "website": "https://react-hook-form.com/",
    "docs": "https://react-hook-form.com/docs/useform#resolver",
    "git_browser": "https://github.com/react-hook-form/resolvers",
    "git": "git@github.com:react-hook-form/resolvers.git",
    "logo": ""
  }
}

Field Descriptions

• identifier (required): Unique identifier for the package (e.g., @hookform/resolvers, zod)
• package_manager (required): Package manager (e.g., npm, pnpm, yarn)
• display_name (required): Human-readable name for the package
• default_tag (required): Default git tag/branch to use when cloning (e.g., master, main, v1.0.0)
• urls.website (optional): Link to package website
• urls.docs (optional): Link to package documentation
• urls.git_browser (optional): Link to view repo in browser
• urls.git (required): Git URL to clone the repository (can be https:// or git@ SSH format)
• urls.logo (optional): Link to logo image file

Adding a Package

1. Create a JSON file in ~/.kctx/data/packages/ with the package identifier as the filename
2. Fill in the configuration with the package details
3. The repository will be cloned automatically when first queried

Package Repository Structure

After a package is cloned, the structure looks like:

/data/packages/
├── @hookform/
│   └── resolvers/          # Cloned git repository
├── @hookform/
│   └── resolvers.json      # Package configuration
└── zod/
    └── zod.json            # Package configuration

Project Configuration

Project configuration files define which dependencies are associated with a project and which versions/tags to use.

Location: ~/.kctx/data/projects/ (or /data/projects/ in Docker)

Project Config Format

Each project needs a JSON configuration file. The filename should match the project identifier (e.g., my-project.json).

{
  "identifier": "my-project",
  "display_name": "My Project",
  "urls": {
    "website": "https://my-project.com",
    "git_browser": "https://github.com/user/my-project",
    "git": "git@github.com:user/my-project.git",
    "logo": ""
  },
  "dependencies": [
    {
      "identifier": "@hookform/resolvers",
      "tag": "master"
    },
    {
      "identifier": "zod",
      "tag": "v3.22.0"
    }
  ]
}

Field Descriptions

• identifier (required): Unique identifier for the project. This should match the directory name of your project when using the MCP server.
• display_name (required): Human-readable name for the project
• urls.website (optional): Link to project website
• urls.git_browser (optional): Link to view repo in browser
• urls.git (optional): Git URL for the project
• urls.logo (optional): Link to logo image file
• dependencies (required): Array of dependency objects, each containing:
  • identifier (required): Must match a package identifier from /packages
  • tag (optional): Git tag/branch to use for this dependency in this project. If not specified, uses the package's default_tag

Creating a Project

1. Create a JSON file in ~/.kctx/data/projects/ with your project identifier as the filename
2. Add the project details and list of dependencies
3. Each dependency can specify a specific tag/version, or use the package's default

Project-Dependency Versioning

Projects can override the default tag for dependencies. This allows you to:

• Pin specific versions for production projects
• Use different versions for different projects
• Test with beta/alpha versions

Example:

{
  "identifier": "production-app",
  "display_name": "Production App",
  "dependencies": [
    {
      "identifier": "zod",
      "tag": "v3.22.0"  // Pin to specific version
    }
  ]
}

vs.

{
  "identifier": "experimental-app",
  "display_name": "Experimental App",
  "dependencies": [
    {
      "identifier": "zod",
      "tag": "next"  // Use beta version
    }
  ]
}

Environment Variables

You can also configure kinetic-context using environment variables in your compose.yaml:

• CORS_ORIGIN: CORS origin URL (default: http://localhost:7167)
• NODE_ENV: Environment mode (default: production)
• PACKAGES_DIR: Path to packages directory (default: /data/packages)
• PROJECTS_DIR: Path to projects directory (default: /data/projects)
• OPENCODE_CONFIG_PATH: Path to opencode.json (default: /config/opencode.json)
• OPENCODE_URL: OpenCode service URL (default: http://opencode:4096)

Configuration Best Practices

1. Use descriptive identifiers - Make package and project identifiers clear and consistent
2. Pin versions for production - Use specific tags for production projects
3. Keep configs in version control - Consider backing up your configuration files
4. Document custom tags - If using non-standard tags, document why
5. Test configurations - Verify packages clone and checkout correctly