Skip to content

CLAUDE.md

Latest commit

 

History

History
92 lines (67 loc) · 3.96 KB

CLAUDE.md

File metadata and controls

92 lines (67 loc) · 3.96 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OpenCode is an open-source AI coding agent (TUI + web + desktop). It's a Bun-based TypeScript monorepo using workspaces and Turborepo.

Key Commands

# Install dependencies
bun install

# Run dev (TUI mode, against packages/opencode dir by default)
bun dev
bun dev <directory>       # run against a different directory
bun dev .                 # run against repo root

# Headless API server
bun dev serve             # port 4096 by default
bun dev serve --port 8080

# Web UI dev (requires server running separately)
bun run --cwd packages/app dev

# Desktop app (requires Tauri/Rust)
bun run --cwd packages/desktop tauri dev

# Typecheck
bun turbo typecheck

# Tests — MUST run from packages/opencode, NOT repo root
cd packages/opencode && bun test --timeout 30000
cd packages/opencode && bun test --timeout 30000 test/tool/bash.test.ts  # single test

# Build standalone executable
./packages/opencode/script/build.ts --single

# Regenerate SDK after API/server changes
./script/generate.ts

Repository Structure

  • packages/opencode/ — Core business logic, CLI, server, and AI agent loop
    • src/provider/ — AI provider integrations (Anthropic, OpenAI, Bedrock, Vertex, Databricks, etc.) via Vercel AI SDK
    • src/session/ — Session management, LLM orchestration (llm.ts), message handling, compaction, system prompts
    • src/tool/ — Built-in tools (bash, read, edit, write, grep, glob, webfetch, etc.) with .txt prompt files
    • src/server/ — Hono-based HTTP API server with SSE events
    • src/cli/ — CLI entry point and TUI (SolidJS with opentui)
    • src/config/ — Configuration parsing and paths
    • src/agent/ — Agent definitions and orchestration
    • src/mcp/ — MCP (Model Context Protocol) client
    • src/plugin/ — Plugin system
    • test/ — Tests (bun test), organized mirroring src/
  • packages/app/ — Shared web UI components (SolidJS)
  • packages/desktop/ — Native desktop app (Tauri wrapping packages/app)
  • packages/sdk/ — Generated JS SDK for the API
  • packages/plugin/ — @opencode-ai/plugin package
  • packages/web/ — Landing page / website
  • packages/ui/ — Shared UI primitives

Architecture

The core loop: session/ manages conversations, llm.ts calls AI providers via the Vercel AI SDK (ai package), tool calls are routed through tool/registry.ts, and results stream back via server/ (Hono + SSE). Provider configuration comes from provider/provider.ts which pulls model definitions from models.dev. The TUI is SolidJS rendered to terminal via opentui. Configuration is in opencode.json at project root.

Default Branch

The default branch is dev, not main. Use dev or origin/dev for diffs and PR base.

Style Guide

  • No semicolons (prettier: semi: false, printWidth: 120)
  • Prefer const, ternaries, early returns over let/else
  • Avoid try/catch, unnecessary destructuring, and any
  • Use Bun APIs (Bun.file(), etc.) when possible
  • Prefer single-word variable/function names; inline values used only once
  • Drizzle schemas: use snake_case field names (no string column name args)
  • Functional array methods (flatMap, filter, map) over for loops
  • Rely on type inference; avoid explicit type annotations unless needed for exports
  • Use @/ path alias for imports within packages/opencode/src/

Testing

  • Tests use bun test — run from packages/opencode/, never from repo root
  • Avoid mocks; test actual implementations
  • Test files live in packages/opencode/test/ mirroring src/ structure

Provider System

New providers generally don't require code changes — add them to models.dev. The provider system in provider/provider.ts dynamically creates AI SDK instances based on provider type. Provider-specific transforms live in provider/transform.ts.