DOCSEARCHbyAlgolia
Submit Docs

btca (better-context)

repository·main·Indexed 22 days ago

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

A tool designed to help AI agents answer questions about libraries and frameworks by searching actual source code instead of relying on outdated documentation. It includes a CLI (@btca/cli) with an interactive TUI, a server for handling HTTP requests, and a sandbox environment. The tool supports managing resources such as Git repositories, npm packages, and local directories, and integrates with AI providers like OpenCode and OpenAI-compatible servers.

Tokens
69K
Snippets
285
Records
356
Agent score
77%

What's inside btca

  2. Configure Typography and Font Scales

    main

    The btca design system uses Geist for UI/Body and Geist Mono for Monospace. Follow these scale and weight guidelines to maintain the 'calm technical' feel:

    Font Scale (px)

    • 12: Overline, micro-labels
    • 13: Dense tables, helper text (use sparingly)
    • 14: Default body, buttons
    • 16: Body, long-form
    • 18: Lead paragraphs, section intros
    • 20: H3 / card titles
    • 24: H2
    • 32: H1
    • 40: Landing hero (rare)

    Font Weights

    • Regular 400: Body
    • Medium 500: Buttons and UI emphasis
    • Semibold 600: Headings

    Line Heights

    • Dense UI: 1.25
    • Body: 1.45
    • Headlines: 1.1–1.2

    Typography Rules

    • Default to 14/16px body for product UI; 16px for docs.
    • Code blocks should never be smaller than 13px.
    • Headings should be compact (max 2 lines).

  3. Choose a btca workflow

    main

    btca offers three main entry points: the CLI, a web app, and an MCP (Model Context Protocol) server. Select a workflow based on your data privacy and infrastructure needs:

    • CLI + Local MCP: Recommended if you want your codebase to remain strictly on your local machine.
    • Web app + Cloud API: Recommended if you want to use saved threads, manage projects, and work with repos indexed in the cloud.

  4. Manage environment variable separation for @btca/web

    main

    When deploying @btca/web, environment variables are split between Vercel and Convex based on their visibility and usage:

    Vercel (SvelteKit App)

    Hosts the SvelteKit application and its public environment variables (prefixed with PUBLIC_).

    Convex (Backend Functions)

    Convex manages all backend-only secrets and function environment variables. These include:

    • CLERK_SECRET_KEY
    • CLERK_WEBHOOK_SECRET
    • DAYTONA_WEBHOOK_SECRET
    • POSTHOG_ID
    • Other backend-only secrets.

  5. Choose between Cloud and Local MCP modes

    main

    btca provides two ways to connect your coding tools to its context-aware resources via the Model Context Protocol (MCP):

    1. Cloud MCP: Uses your btca subscription to give tools access to btca-managed resources via an HTTP endpoint. This is optimized for request/response tool calls. Note that long-lived SSE notification streams are disabled in cloud deployments.
    2. Local MCP: Runs btca entirely on your machine and exposes local resources to coding tools via stdio.

    You can automatically scaffold local configurations by running the following command:

    btca mcp local

    btca mcp local

  6. Configure AI Providers and Authentication

    main

    BTCA supports several providers. Authentication varies by provider:

    • opencode: Requires API key.
    • openrouter: Requires API key.
    • openai: Requires OAuth only.
    • google: Requires API key or OAuth.
    • anthropic: Requires API key.

    You can authenticate providers via the OpenCode CLI: opencode auth --provider <provider>

  7. BTCA Local Startup Behavior

    main

    The behavior of the btca-local skill changes based on how it is invoked:

    App Startup (No context/question provided)

    If the skill is invoked without an accompanying question, it acts like a terminal application boot sequence. It searches the top level of ~/.btca/agent/sandbox to list previously cloned repositories and outputs a summary:

    # BTCA Local

_use your coding agent to search any git repo locally_

Previously searched:

- repo 1
- ...

Give me a question and the link to a git repo to get started!
(we can also clean out or pre-load some resources to this list...)

    Prompt-driven Execution

    • Invoked via user prompt: The skill executes the user's prompt faithfully while applying the BTCA search workflow to gather context.
    • Invoked with a specific question: The skill directly answers the user's question using the BTCA search workflow to find the necessary information within the local repositories.

  8. Understand the sandbox file system and project isolation

    main

    The sandbox uses a specific directory structure to manage configurations and cached resources.

    Default Project Structure

    For backward compatibility, the 'default' project uses root-level paths:

    • Config: /root/btca.config.jsonc
    • Resources: /root/.local/share/btca/resources/

    Project-Aware Structure

    Future implementations use isolated directories for different projects to prevent resource conflicts (e.g., two different projects using a resource named 'svelte'):

    • Project Config: /root/.local/share/btca/projects/{project}/btca.config.jsonc
    • Project Resources: /root/.local/share/btca/projects/{project}/resources/

    Request Flow

    1. An MCP client calls ask with an optional project parameter.
    2. Convex (the database layer) forwards the request to the sandbox's /question endpoint, including the project name.
    3. The btca server determines the correct config/resource path based on that project name.

  10. Configure Elevation and Surfaces

    main

    Use subtle elevation and borders instead of heavy shadows to maintain a technical feel.

    Elevation Tokens

    • Elevation 0: Flat
    • Elevation 1: 0 1px 2px rgba(0,0,0,0.06)
    • Elevation 2: 0 4px 12px rgba(0,0,0,0.08)
    • Elevation 3: 0 10px 24px rgba(0,0,0,0.12)

    Surface Rules

    • Cards: Use N0 or N50 background.
    • Structure: Use 1px borders on N200 for structure instead of heavy shadows.
    • Modals: Use rgba(10, 18, 28, 0.5) for backdrops.

  11. Documentation standards for MDX pages

    main

    When using Claude Code to generate or edit documentation, adhere to these specific requirements for MDX files:

    Frontmatter Requirements

    Every MDX file must include YAML frontmatter with:

    • title: A clear, descriptive page title.
    • description: A concise summary for SEO and navigation.

    Writing and Formatting Standards

    • Voice: Use second-person voice ("you").
    • Structure: Place prerequisites at the start of procedural content.
    • Code Blocks: Always include language tags on all code blocks and ensure all examples are tested.
    • Links: Use relative paths for all internal links; never use absolute URLs.
    • Images: Include alt text on all images.
    • Consistency: Match the style and formatting of existing pages and include both basic and advanced use cases.

  12. Apply Spacing and Layout Rules

    main

    The btca layout is built on a 4px grid. Use the following scale for margins, padding, and spacing:

    Spacing Scale (px)

    4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80

    Layout Constraints

    • Max Content Width: 1200px for docs, 1400px for app.
    • Primary Gutters: 24px (desktop), 16px (tablet), 12px (mobile).
    • Vertical Rhythm: 24px between major sections.
    • Density: Prefer dense layouts; reduce whitespace before adding pagination.