conductor: Instructions file for Claude Code

CLAUDE.md

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

Commands

npm run build          # Compile TypeScript → dist/
npm run dev            # Watch mode (tsx watch)
npm test               # Run all tests (vitest)
npm run test:watch     # Watch mode tests
npm run test:coverage  # Coverage report
npm run typecheck      # Type-check without emit
npm run lint           # ESLint
npm run lint:fix       # ESLint with auto-fix
npm run format         # Prettier

Run a single test file:

npx vitest run tests/calculator.test.ts

Run the CLI locally (without building):

npx tsx src/cli/index.ts <command>

After building, run the CLI:

node dist/cli/index.js <command>
# or if globally linked:
conductor <command>

Tests live in tests/ and match **/*.test.ts. The postbuild script copies src/dashboard/index.html to dist/dashboard/index.html — if you add other static assets to src/dashboard/, add them to the postbuild script too.

Architecture

Conductor is an MCP (Model Context Protocol) server that exposes a plugin system as tools to AI agents. The codebase is ESM TypeScript ("type": "module", Node16 module resolution). All imports must use .js extensions even for .ts source files.

Core Object Model

Conductor (src/core/conductor.ts) is the central orchestrator. It owns:

• ConfigManager — reads/writes ~/.conductor/config.json
• DatabaseManager — SQLite via sql.js at ~/.conductor/conductor.db
• PluginManager — lazy-initializes plugins on first use
• AIManager — multi-provider AI (Claude, OpenAI, Gemini, Ollama)

Consumers should depend on the narrow interfaces in src/core/interfaces.ts (IConfig, IDatabase, IPluginRegistry) rather than the concrete classes.

Plugin System

Every capability is a plugin implementing the Plugin interface (src/plugins/manager.ts):

interface Plugin {
  name: string; description: string; version: string;
  initialize(conductor: Conductor): Promise<void>;
  isConfigured(): boolean;
  getTools(): PluginTool[];
  configSchema?: PluginConfigSchema;  // for `conductor config setup <plugin>`
  getContext?(): Promise<string | null>; // proactive reasoning cycle
}