Skip to content

CLAUDE.md

Latest commit

 

History

History
154 lines (127 loc) · 6.65 KB

CLAUDE.md

File metadata and controls

154 lines (127 loc) · 6.65 KB

CLAUDE.md

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

Project Overview

Terminal Coding Agent (v5.0) is a CLI-based multi-agent coding assistant powered by the Claude Agent SDK. It wraps the SDK's query() function with a custom terminal UI featuring:

  • / command menu for invoking Skills
  • @ file browser for attaching files to context
  • Smart routing to specialized agents (Reader, Coder, Reviewer, Coordinator)
  • Inter-agent communication via message bus and shared context
  • Multiple execution modes: single, parallel, react, coordinator

Important: The agent spawns Claude Code as a subprocess and cannot run inside Claude Code itself.

Commands

# From repo root
npm run install:all    # Install all dependencies (into deepresearch/)
npm run dev            # Development (tsx src/index.ts)
npm run build          # TypeScript compilation
npm start              # Run compiled output

# From deepresearch/ directory
npm run test:ui        # Test UI components

# Global CLI (after npm link in deepresearch/)
agent                  # Interactive mode
agent "your question"  # Single query
agent /commit          # Invoke a skill directly

Architecture

deepresearch/
├── src/
│   ├── index.ts                  # Main entry, input loop, runQuery/runCoordinator
│   ├── agents/                   # Agent classes
│   │   ├── base.ts               # BaseAgent abstract class (SDK integration)
│   │   ├── types.ts              # SubagentType, AgentConfig, AgentResult
│   │   ├── coordinator.ts        # Multi-agent dispatch, [DISPATCH:agent] parsing
│   │   ├── reader.ts             # Code reading and analysis
│   │   ├── coder.ts              # Code writing and modification
│   │   └── reviewer.ts           # Code review and quality checks
│   ├── core/
│   │   ├── router.ts             # Router class - keyword matching, skill→agent mapping
│   │   ├── session.ts            # Session management
│   │   └── permissions.ts        # Permission mode handling
│   ├── runtime/
│   │   ├── bus.ts                # MessageBus - inter-agent pub/sub communication
│   │   ├── shared.ts             # SharedContext - cross-agent state
│   │   ├── pool.ts               # AgentPool - task queue and parallel execution
│   │   ├── orchestrator.ts       # Orchestrator - execution mode coordination
│   │   └── react.ts              # ReAct executor for multi-step reasoning
│   ├── config/
│   │   ├── agents.ts             # AGENT_CONFIGS, AGENT_KEYWORDS, SKILL_AGENT_MAP
│   │   ├── constants.ts          # VERSION, MAX_SUBAGENT_DEPTH, DEFAULT_MODEL
│   │   └── tools.ts              # MCP_SERVERS configuration
│   ├── ui/
│   │   ├── smart-input.ts        # SmartInput - main input with "/" and "@" triggers
│   │   ├── commands.ts           # CommandPicker - arrow-key navigable "/" menu
│   │   ├── file-browser.ts       # FileBrowser - "@" file selection
│   │   └── theme.ts              # ANSI colors, icons, box drawing
│   ├── tools/
│   │   ├── message.ts            # MessageTool - agent messaging wrapper
│   │   ├── context.ts            # ContextTool - shared context wrapper
│   │   └── dispatch.ts           # Dispatch utilities
│   └── utils/
│       ├── prompt-loader.ts      # Loads agent prompts from .md files
│       ├── transcript.ts         # Session logging (text + JSON)
│       └── message-handler.ts    # SDK message processing
├── prompts/                      # Agent-specific system prompts (.md)
├── .claude/skills/               # Global Skills
├── bin/agent.cjs                 # Global CLI entry (CommonJS wrapper)
└── dist/                         # Build output

Multi-Agent System

Agent Types (defined in config/agents.ts):

  • Coordinator (🎯): Task decomposition, multi-agent dispatch via [DISPATCH:agent]
  • Reader (📖): Code reading, analysis, understanding
  • Coder (💻): Code writing, modification, implementation
  • Reviewer (🔍): Code review, quality checks, bug detection

Routing Logic (core/router.ts):

  1. Skill commands have highest priority (/code-review → Reviewer via SKILL_AGENT_MAP)
  2. Keyword detection with word boundaries (see AGENT_KEYWORDS in config/agents.ts)
  3. Default to Reader for understanding context first

Execution Modes (via runtime/orchestrator.ts):

  • single: Direct agent execution
  • parallel: Multiple agents via AgentPool
  • react: Multi-step reasoning loop
  • coordinator: Reader → Coder → Reviewer pipeline

Inter-Agent Communication:

  • MessageBus (runtime/bus.ts): EventEmitter-based pub/sub
  • SharedContext (runtime/shared.ts): Key-value store for cross-agent state

Key Patterns

SDK Integration (agents/base.ts):

  • Uses @anthropic-ai/claude-agent-sdk's query() function
  • Configures: settingSources: ["project"], additionalDirectories, mcpServers
  • Uses permissionMode: "acceptEdits" (safe) or "bypassPermissions" (unsafe)
  • Streams messages via async iterator, handles system, assistant, result, tool_progress

Skills Loading (index.ts: loadSkillsFromDir):

  • Global skills: deepresearch/.claude/skills/
  • Project skills: <cwd>/.claude/skills/
  • Internal skills (hidden from menu): web-scrape, doc-generate, deep-research

Dispatch Pattern (index.ts: detectDispatch):

  • Coordinator outputs [DISPATCH:reader] task description
  • Main loop parses these and spawns subagents
  • Results are fed back to Coordinator for synthesis

UI Components (src/ui/):

  • All use raw process.stdin with setRawMode(true) for keyboard handling
  • SmartInput: Main input, detects / and @ triggers
  • CommandPicker: Arrow-key navigable popup for / commands
  • FileBrowser: Directory navigation + fuzzy search for @ files

Skills Format

Skills follow Anthropic's official format in .claude/skills/<name>/SKILL.md:

---
name: skill-name
description: Brief description
version: 1.0.0
allowed-tools:
  - Read
  - Write
  - Bash
---

# Skill Name

Instructions for Claude...

Coding Conventions

  • TypeScript ES modules for src/, CommonJS for bin/
  • 2-space indentation, semicolons required
  • Kebab-case filenames
  • Use .js extension in imports (ESM requirement)
  • Run npm run build before committing to verify types
  • Global singletons: getRouter(), getMessageBus(), getSharedContext(), getOrchestrator()