Harvey Developer Guide

This guide is for developers who want to understand Harvey’s internals, contribute to the project, or extend its functionality.

🏗️ Architecture & Design

Core Architecture

• ARCHITECTURE.md — Component map, core types (Agent, LLMClient, Message, Workspace), and how they interact

Design Documents

• DECISIONS.md — Key design decisions and their rationale
• RAG Support Design — Design document for retrieval-augmented generation support
• Harvey Skill-Set Design — Design for the /skill-set command and skill bundling system
• Improved Tool Handling with Schemas — Tool schema validation and handling design
• Memory Unified Design — Unified memory system architecture
• Memory Unified Plan — Implementation plan for memory system unification
• Profile Templates Design — Profile-based configuration templates
• Profile Templates Plan — Implementation plan for profile templates
• Programming Language Support Design — Multi-language support architecture
• Programming Language Support Plan — Implementation roadmap for language support
• Pipeline Design — Multi-step prompt pipeline architecture
• Pipeline Plan — Implementation plan for pipeline support
• Loop Design — REPL loop architecture
• Loop Plan — Implementation plan for the REPL loop

🛠️ Development Setup

Prerequisites

• about.md — Project metadata, requirements (Go >= 1.26.3), and author information

Building Harvey

# Build all programs
make build

# Build a single program
go build -o bin/<name> cmd/<name>/*.go

# Generate version.go from codemeta.json
cmt codemeta.json version.go

# Build website (HTML from Markdown via pandoc)
make website

# Clean build artifacts
make clean

🧪 Testing

• TESTING.md — Running tests, test architecture, writing tests, and CI/CD setup
• agent_integration_test.go — Integration tests for agent functionality
• anyllm_client_test.go — Tests for the AnyLLM client wrapper
• commands_test.go — Tests for slash command handlers
• config_test.go — Configuration loading and validation tests
• knowledge_test.go — Knowledge base functionality tests
• memory_*_test.go — Memory system tests (manifest, miner, onboarding, rolling, store, unified)
• ollama_probe_test.go — Ollama probing tests
• pipeline_test.go — Pipeline functionality tests
• rag_support_test.go — RAG support tests

📦 Code Organization

Main Package (harvey/)

• harvey.go — Core types: Agent, LLMClient, Message, ChatStats
• commands.go — All slash-command handlers and dispatch logic
• config.go — Configuration struct, loading, and validation
• terminal.go — REPL loop, startup sequence, backend selection
• workspace.go — Sandboxed file I/O operations
• knowledge.go — SQLite knowledge base implementation
• audit.go — In-memory ring-buffer audit log
• permissions.go — Permission check helpers
• ollama.go — OllamaClient helpers and probing utilities
• anyllm_client.go — AnyLLMClient wrapper for mozilla-ai/any-llm-go
• routing.go — RouteRegistry, named remote endpoints, @mention dispatch
• recorder.go — Fountain (.spmd) session recorder
• spinner.go — Animated spinner with Edward Lear messages

Command Entry Points (cmd/)

• Each subdirectory contains a CLI entry point
• Built using go build -o bin/<name> cmd/<name>/*.go

Built-in Tools (builtin_tools.go)

• Schema-based tools: read_file, write_file, run_command, list_files, git_command
• All tools enforce workspace boundary and permission checks

🎨 Conventions & Style

Documentation Conventions

All exported functions, structs/types, interfaces, and constants must be documented with a /** ... */ block comment including: - Description of what the symbol is or does - Parameters — name, type, and purpose for each - Return values — type and meaning - An embedded usage example

Code Conventions

• version.go is generated by cmt — do not edit by hand
• bin/, dist/, man/, testout/ are gitignored build artifacts
• Source lives at the package level (harvey/*.go)
• CLI entry points go under cmd/<program>/
• See HARVEY.md for full toolchain dependencies and release targets

📚 Additional Resources

For Contributors

• GitHub Issues — Bug reports and feature requests
• CONTRIBUTING.md — Contribution guidelines (if available)
• CHANGES.md — Version history and release notes

Related Documentation

• Security — Security model and protections (also relevant for developers)
• Configuration — Workspace configuration reference