btca-server

BTCA (Better Context AI) server for answering questions about your codebase using OpenCode AI.

Installation

``bash
bun add btca-server
`

Usage

$3

`typescript
import { startServer } from 'btca-server';

// Start with default options (port 8080 or process.env.PORT)
const server = await startServer();
console.log(Server running at ${server.url});

// Start with custom port
const server = await startServer({ port: 3000 });

// Start with quiet mode (no logging)
const server = await startServer({ port: 3000, quiet: true });

// Stop the server when needed
server.stop();
`

$3

The startServer function returns a ServerInstance object:

`typescript
interface ServerInstance {
port: number; // Actual port the server is running on
url: string; // Full URL (e.g., "http://localhost:8080")
stop: () => void; // Function to stop the server
}
`

$3

You can pass port: 0 to let the OS assign a random available port:

`typescript
const server = await startServer({ port: 0 });
console.log(Server running on port ${server.port});
`

API Endpoints

Once the server is running, it exposes the following REST API endpoints:

$3

`
GET /
`

Returns service status and version info.

$3

`
GET /config
`

Returns current configuration (provider, model, resources).

$3

`
GET /resources
`

Lists all configured resources (local directories or git repositories).

`
POST /config/resources
`

Add a new resource (git or local).

`
DELETE /config/resources
`

Remove a resource by name.

`
POST /clear
`

Clear all locally cloned resources.

$3

`
POST /question
`

Ask a question (non-streaming response). The resources field accepts configured resource names or HTTPS Git URLs.

`
POST /question/stream
`

Ask a question with streaming SSE response. The resources field accepts configured resource names or HTTPS Git URLs.
The final done SSE event may include optional usage/metrics (tokens, timing, throughput, and best-effort pricing).

$3

`
PUT /config/model
`

Update the AI provider and model configuration.

Configuration

The server reads configuration from ~/.btca/config.toml or your local project's .btca/config.toml. You'll need to configure:

- AI Provider: OpenCode AI provider (e.g., "opencode", "anthropic")
- Model: AI model to use (e.g., "claude-3-7-sonnet-20250219")
- Resources: Local directories or git repositories to query

Example config.toml:

`toml
provider = "anthropic"
model = "claude-3-7-sonnet-20250219"
resourcesDirectory = "~/.btca/resources"

[[resources]]
type = "local"
name = "my-project"
path = "/path/to/my/project"

[[resources]]
type = "git"
name = "some-repo"
url = "https://github.com/user/repo"
branch = "main"
`

Supported Providers

BTCA supports the following providers only:

- opencode — API key required
- openrouter — API key required
- openai — OAuth only
- google — API key or OAuth
- anthropic — API key required

Authenticate providers via OpenCode:

`bash
opencode auth --provider
`

Authentication Notes

- OpenCode and OpenRouter can use environment variables or OpenCode auth.
- OpenAI requires OAuth (API keys are not supported).
- Anthropic requires an API key.
- Google supports API key or OAuth.

Environment Variables

- PORT: Server port (default: 8080)
- OPENCODE_API_KEY: OpenCode API key (required when provider is opencode)
- OPENROUTER_API_KEY: OpenRouter API key (required when provider is openrouter)
- OPENROUTER_BASE_URL: Override OpenRouter base URL (optional)
- OPENROUTER_HTTP_REFERER: Optional OpenRouter header for rankings
- OPENROUTER_X_TITLE: Optional OpenRouter header for rankings

TypeScript Types

The package exports TypeScript types for use with Hono RPC client:

`typescript
import type { AppType } from 'btca-server';
import { hc } from 'hono/client';

const client = hc('http://localhost:8080');
`

Stream Types

For working with SSE streaming responses:

`typescript
import type { BtcaStreamEvent, BtcaStreamMetaEvent } from 'btca-server/stream/types';
`

Requirements

- Bun: >= 1.1.0 (this package is designed specifically for Bun runtime)
- OpenCode API Key: Required when using the opencode` provider

License

MIT

Repository

https://github.com/bmdavis419/better-context