Development Guide - djvolz/coda-code-assistant GitHub Wiki

Development Guide

Welcome to Coda development! This guide will help you contribute to Coda effectively, whether you're fixing bugs, adding features, or improving documentation.

Getting Started

First, read the Roadmap for architecture and planned features.

Coda is a multi-provider CLI code assistant providing a unified interface for LLMs (OCI GenAI, OpenAI, Anthropic, Ollama). Built for developers who prefer terminal workflows.

Core Principles: Simplicity, Flexibility, Performance, Developer Experience, Extensibility

Environment Setup

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/djvolz/coda-code-assistant.git
cd coda-code-assistant
uv sync --all-extras

Quick Commands

# Development
uv sync --all-extras          # Install all dependencies
uv run coda                   # Run interactive CLI
uv run coda --one-shot "..."  # One-shot mode
make test                     # Run unit tests
make test-cov                 # Run tests with coverage
make format                   # Format code
make version                  # Update version timestamp

# Git workflow
gh pr create                  # Create PR (use conventional commits)
gh pr checks                  # Check CI status
git commit -m "type(scope): message"  # Conventional commit format

Project Structure

coda/
├── __version__.py         # Version management (year.month.day.HHMM)
├── cli/
│   ├── main.py           # CLI entry point
│   ├── interactive.py    # Interactive mode implementation
│   ├── command_registry.py  # Centralized command management
│   └── shared/           # Shared commands and help
├── providers/
│   ├── base.py          # Abstract provider interface
│   ├── oci_genai.py     # OCI GenAI implementation
│   ├── litellm_provider.py  # LiteLLM integration
│   ├── ollama_provider.py   # Ollama integration
│   └── mock_provider.py  # Testing provider
├── agents/               # Agent framework
│   ├── agent.py         # Core agent implementation
│   └── tool_adapter.py  # Tool integration
├── tools/               # Tool system (MCP)
│   ├── base.py         # Tool interfaces
│   ├── file_tools.py   # File operations
│   ├── git_tools.py    # Git integration
│   └── web_tools.py    # Web tools
├── session/             # Session management
│   ├── manager.py      # Session operations
│   └── database.py     # SQLite persistence
├── themes.py           # UI theme system
└── configuration.py    # Configuration management

tests/                    # Comprehensive test suite
scripts/                  # Utility scripts
examples/                 # Usage examples

Code Style Guidelines

IMPORTANT: Follow these patterns exactly:

  • Use type hints for ALL functions
  • Prefer async/await for I/O operations
  • Use Pydantic for data validation
  • Follow existing import patterns
  • Add docstrings to public APIs only
  • Keep functions under 50 lines

Example Code Style

from typing import List, Optional
import asyncio
from pydantic import BaseModel

class ModelInfo(BaseModel):
    name: str
    provider: str
    available: bool = True

async def get_models(provider: str) -> List[ModelInfo]:
    """Get available models for a provider."""
    # Implementation here
    pass

Testing Requirements

ALWAYS run tests before committing:

  • New features need unit tests
  • Use pytest markers: @pytest.mark.unit, @pytest.mark.integration
  • Mock external services (OCI, APIs)
  • Aim for >80% coverage on new code
  • Use MockProvider for deterministic testing
# Run specific test types
pytest -m unit           # Unit tests only
pytest -m integration    # Integration tests
pytest --cov=coda       # With coverage
make test               # Run all tests
make test-cov           # Run with coverage report

Using MockProvider

For testing conversational features:

from coda.providers.mock_provider import MockProvider

# MockProvider returns deterministic responses
provider = MockProvider()
response = provider.chat_completion(messages=[...])

Provider Implementation

When adding new providers:

  1. Inherit from BaseProvider in providers/base.py
  2. Implement all abstract methods
  3. Add model discovery/caching
  4. Handle streaming responses
  5. Map provider-specific errors
  6. Add comprehensive tests

See Provider Architecture for detailed implementation guide.

Configuration System

Configuration priority (highest to lowest):

  1. CLI parameters
  2. Environment variables
  3. Project config: .coda/config.toml
  4. User config: ~/.config/coda/config.toml
  5. Defaults

XDG Directories

  • Config: ~/.config/coda/
  • Sessions: ~/.local/share/coda/sessions/
  • Cache: ~/.cache/coda/

Commit Guidelines

IMPORTANT: Use conventional commits for automated releases:

feat(providers): add OpenAI support     # Triggers release
fix(cli): handle timeout errors         # Triggers release
docs: update installation guide         # No release
chore: update dependencies             # No release

AI Development Metadata

Include AI metadata in commits when using AI assistance:

feat: implement feature X

AI Prompt: "user's actual request"
AI Tools: Read, Write, Edit, Bash

- Implementation details
- Changes made

IMPORTANT: Always scrub PII from prompts:

  • Replace actual paths with generic ones
  • Remove API keys, tokens, or secrets
  • Replace specific company/project names if sensitive
  • Remove email addresses, usernames, or other identifying information

Pull Request Requirements

IMPORTANT: Never squash commits - preserve AI development history

PR must include:

  1. Conventional commit messages
  2. AI Development Summary section (if applicable)
  3. Test results
  4. No merge until CI passes

See existing PRs for examples of proper format.

Development Workflow

  1. Explore - Read this guide and understand the codebase structure
  2. Plan - Break down complex tasks into smaller steps
  3. Code - Implement changes following project conventions
  4. Test - Run tests and linting
  5. Commit - Use conventional commits
  6. Review - Create PR and address feedback

Release Process

Automatic releases triggered by:

  • feat: - New features
  • fix: - Bug fixes
  • perf: - Performance improvements
  • refactor: - Code refactoring

Skip release: add [skip ci] or [skip release] to commit message

Version format: year.month.day.HHMM (e.g., 2024.07.05.1430)

Current Development Status

✅ Completed:

  • Multi-provider support (OCI GenAI, LiteLLM, Ollama)
  • Agent Tools System with 12 built-in tools
  • Theme system with 11 color themes
  • Session management with auto-save and branching
  • Interactive CLI with prompt-toolkit
  • Date-based versioning and automated releases

🚧 In Progress:

  • Enhanced tool capabilities
  • Performance optimizations
  • Additional provider integrations

See Roadmap for complete development phases.

Common Issues & Debugging

Debugging Tips

  • Use --debug flag for verbose output
  • Check ~/.cache/coda/ for cached models
  • OCI errors usually mean config issues
  • Streaming issues: check httpx timeout settings

Gotchas & Warnings

  • OCI requires compartment_id configuration
  • Version updates only happen during releases
  • Tests use python -m pytest (not direct pytest)
  • Always use absolute paths in file operations
  • Provider model names use dot notation: provider.model-name

Preferred Tools

  • rg instead of grep
  • fd instead of find
  • uv instead of pip
  • gh for GitHub operations

Security Guidelines

  • Never expose secrets or credentials in code
  • Always use environment variables for API keys
  • Validate all user inputs
  • Follow secure coding practices
  • Never commit sensitive information

Getting Help

  • Check Troubleshooting for common issues
  • Read existing code for patterns and examples
  • Open an issue for questions or problems
  • Join discussions in GitHub Discussions

See also: Contributing, Testing, Architecture