sophia-code/CLAUDE.md

Production-ready agentic CLI code editor with AI-powered coding assistance, planning, and multi-agent delegation. Enterprise-grade security and reliability.

# CLAUDE.md

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

## Project Overview

Sophia is an agentic CLI code editor - similar to Claude Code or Gemini CLI - that provides AI-powered coding assistance through multiple interfaces. It features a sophisticated agent delegation system and extensible plugin architecture.

## Development Commands

This project uses both Python (via Makefile) and Node.js (via npm scripts) tooling:

### Python Development (Primary)
- `make test` - Run Python tests with pytest
- `make lint` - Run flake8 linting on Python code  
- `make format` - Format Python code with black and isort
- `make type-check` - Run mypy type checking
- `make pre-commit` - Run all code quality checks (format, lint, type-check, test)
- `make setup` - Set up development environment via setup.sh
- `make install-dev` - Install Python development dependencies

### Node.js Tooling (NPM Package)
- `npm test` - Run Node.js tests
- `npm run postinstall` - Post-installation setup script
- `npm run setup-python` - Python environment setup

### VS Code Extension
- `cd vscode-extension && npm run build` - Build TypeScript extension
- `cd vscode-extension && npm run watch` - Watch mode for development

## Agentic Architecture

Sophia implements a sophisticated multi-agent system:

### Core Agent System
- **Primary CLI Agent** (`src/cli.py`): Main interactive terminal interface with conversation management
- **Subagent Delegation** (`src/subagents.py`): YAML-configurable specialized agents with custom system prompts and tool access
- **Tool Registry** (`src/tool_registry.py`): Extensible plugin system for command execution
- **Session Management**: Persistent conversation history with resumption capabilities

### Agent Configuration
- **User-level agents**: `~/.sophia/agents/*.yml` 
- **Project-level agents**: `.sophia/agents/*.yml`
- **Agent definition**: name, description, system_prompt, tools list
- **Command invocation**: `/agent <agent-name> <task>`

### Built-in Tool Ecosystem
- `/edit` - AI-driven file editing with patch application
- `/search` - Web search via DuckDuckGo HTML parsing
- `/http` - HTTP content fetching 
- `/github_issue` - GitHub issue retrieval (supports GITHUB_TOKEN)
- `/help`, `/clear`, `/model`, `/config` - Session management
- Custom plugins loaded from `plugins/` directory

### Multi-Interface Design
- **Terminal CLI**: Primary interactive interface with readline support
- **NPM Global Package**: Cross-platform distribution and setup
- **VS Code Extension**: IDE integration with chat panel
- **Groq API Integration**: Fast inference with configurable models

## Code Editor Capabilities

### File Operations
- AI-driven code editing through `/edit` command
- Multi-file project understanding and context management
- Session-based conversation history for coding context
- Intelligent code analysis and modification suggestions

### Agent Specialization
- Dedicated agents for specific coding tasks (code review, debugging, documentation)
- Tool-restricted agents for security and focused functionality
- Project-specific agent configurations for domain expertise
- Hierarchical agent delegation system

### Development Workflow Integration
- Persistent session management across coding sessions
- Integration with existing development tools and workflows
- Extensible plugin system for custom tool integration
- Multi-language support through evaluation frameworks

## Configuration and Setup

### Environment Configuration
- `GROQ_API_KEY` (required) - Primary AI inference API key
- `GITHUB_TOKEN` (optional) - For GitHub issue fetching
- Model configs in `config/model_configs.py`
- Session data stored in `~/.sophia/sessions/`

### Plugin Development
- Plugin interface via `Tool` class with `execute` callable
- Automatic plugin loading from `plugins/` directory
- Registration pattern: `def register(registry: ToolRegistry)`
- Example plugins: search, HTTP, GitHub integration

### Dependencies
- **Python Core**: torch, transformers, accelerate, groq
- **Development**: black, isort, flake8, mypy, pytest
- **Node.js**: chalk, commander, cross-spawn, fs-extra
- **Python 3.9-3.12** compatibility (3.13+ has vllm issues)

## File Structure
- `src/` - Core Python application (CLI, agents, tools)
- `plugins/` - Extensible tool implementations
- `config/` - Model and application configurations
- `tests/` - Python test suite
- `vscode-extension/` - VS Code integration
- `qwencoder-eval/` - Comprehensive code evaluation benchmarks
- `finetuning/` - Model training utilities (SFT, DPO)
- `examples/` - Usage examples and API demonstrations