# CODEBUDDY.md This file provides guidance to CodeBuddy when working with code in this repository.

## Build and Development Commands

- **Build**: `npm run build` - Compiles TypeScript to dist/ and makes CLI executable.
- **Development**: `npm run dev` - Runs via tsx for development (faster than build+start).
- **Start**: `npm start` - Runs the compiled CLI from dist/cli.js.
- **Type Check**: `npm run typecheck` - Runs TypeScript without emitting files.
- **Clean**: `npm run clean` - Removes dist/ directory.

## Project Architecture

This is **Deep Code**, a fork of pi-coding-agent customized for DeepSeek API integration. It's a TypeScript/Node.js CLI application providing an AI-powered coding assistant with terminal UI, tool execution, and generative UI capabilities.

### Core Architecture

**Entry Points**:
- `src/cli.ts` - CLI entry point, sets up HTTP proxy and delegates to main().
- `src/main.ts` - Main orchestration: parses args, initializes core components, starts the appropriate mode.

**Three Run Modes** (in `src/modes/`):
1. **Interactive Mode** (`modes/interactive/`) - Full TUI with chat interface, editor, and real-time rendering.
2. **Print Mode** (`modes/print-mode.ts`) - Non-interactive, single prompt response, outputs to stdout.
3. **RPC Mode** (`modes/rpc/`) - JSON-RPC interface for external tool integration.

### Key Subsystems

**AI Layer** (`src/ai/`):
- Provider-agnostic abstraction supporting OpenAI-compatible APIs.
- DeepSeek is the primary provider; others (Anthropic, Google, etc.) are supported.
- `ai/types.ts` defines core types: `KnownProvider`, `ThinkingLevel`, `Model`.
- `ai/env-api-keys.ts` maps providers to environment variables (e.g., `DEEPSEEK_API_KEY`).

**Core Layer** (`src/core/`):
- `agent-session.ts` - Central abstraction managing agent lifecycle, event subscription, and session persistence. Used by all run modes.
- `session-manager.ts` - Handles session storage, branching, and tree navigation. Sessions are JSON files in `~/.deepseek-code/sessions/`.
- `model-registry.ts` - Runtime model registration and resolution. Supports custom models via `models.json`.
- `tools/` - Built-in tools: read, write, edit, bash, grep, find, ls. Each tool is a TypeScript file implementing the Tool interface.
- `extensions/` - Extension system for registering custom tools, UI components, and slash commands.

**TUI Layer** (`src/tui/`):
- Custom terminal UI framework (not dependent on external TUI libraries).
- `tui.ts` - Core TUI engine with component lifecycle and rendering.
- `components/editor.ts` - Multi-line text editor with autocomplete, history, and paste handling.
- `components/input.ts` - Single-line input component.
- Supports Kitty keyboard protocol and bracketed paste mode.

**Modes Layer** (`src/modes/interactive/`):
- `interactive-mode.ts` - Main TUI orchestrator (~4000 lines). Manages layout, keybindings, and component hierarchy.
- `components/` - UI components: `welcome-banner.ts`, `assistant-message.ts`, `bash-execution.ts`, `tool-execution.ts`, etc.
- `theme/theme.ts` - Theming system supporting custom color schemes.

### Configuration and Data Paths

- Config directory: `~/.deep-code/` (configurable via `DEEP_CODE_CODING_AGENT_DIR` env var).
- Sessions: `~/.deep-code/sessions/`
- Auth: `~/.deep-code/agent/auth.json`
- Models: `~/.deep-code/agent/models.json`
- Settings: `~/.deep-code/agent/settings.json`

### Key Files for Common Tasks

- Add new AI provider: `src/ai/providers/`, `src/ai/types.ts`, `src/ai/env-api-keys.ts`
- Add new tool: `src/core/tools/`, register in `src/core/tools/index.ts`
- Add new slash command: `src/core/slash-commands.ts`
- Modify startup banner: `src/modes/interactive/components/welcome-banner.ts`
- Change keybindings: `src/core/keybindings.ts`
- Modify system prompt: `src/core/system-prompt.ts`

### Build Output Structure

Compiled output goes to `dist/` preserving the `src/` structure. The CLI entry is `dist/cli.js` with shebang for direct execution. TypeScript path mappings are resolved during compilation; imports use `.js` extensions per Node.js ESM requirements.

### Runtime Requirements

- Node.js >= 20.6.0
- Automatically downloads `fd` and `ripgrep` binaries on first run to `~/.deep-code/bin/`
- Requires `DEEPSEEK_API_KEY` environment variable (or uses `models.json` for other providers)

### Important Implementation Details

- Most source files have `@ts-nocheck` to disable strict type checking (inherited from pi-mono).
- Uses ESM modules exclusively (`"type": "module"` in package.json).
- All imports must include `.js` extension (e.g., `import { x } from "./file.js"`).
- Agent loop uses event-driven architecture with `AgentSession` emitting events for UI updates.
- Tool execution runs in subprocesses with JSON-RPC communication for isolation.
