# CLAUDE.md

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

## Project Overview

Dropshell is a system management tool for server operations, written in C++. It provides a command-line interface for managing remote servers and services through Docker containers.

## Build Commands

The build system uses Docker for consistent, reproducible builds across all environments.

### Development Build (Debug)
```bash
# From repository root
./build.sh
# Or with environment variables
CMAKE_BUILD_TYPE=Debug INSTALL_LOCAL=true ./build.sh
```
This builds a debug version using Docker and optionally installs to ~/.local/bin/dropshell

### Production Build (Release)
```bash
CMAKE_BUILD_TYPE=Release ./build.sh
```

### Legacy Build Scripts
The scripts in `source/build_native.sh` and `source/build_production.sh` now call the Docker-based build system.

### Build Options
- `CMAKE_BUILD_TYPE`: Debug or Release (default: Debug)
- `INSTALL_LOCAL`: true/false - auto-install to ~/.local/bin (default: true)
- `NO_CACHE`: true/false - disable Docker build cache (default: false)

### Running Tests
```bash
cd source && ./test.sh
```

### Publishing Release
```bash
cd source && ./publish.sh
```

## Architecture

### Core Components

- **Command System**: Commands are registered through CommandRegistry (src/commands/command_registry.hpp). Each command has a handler function and optional autocomplete support. Commands can require config and/or agent installation.

- **Service Management**: Services are managed through LocalServiceInfo structures (src/services.hpp). Services are created from templates and installed on remote servers via Docker containers.

- **Server Management**: Servers represent remote hosts that run services. Server configuration includes SSH connection details and installed services.

- **Template System**: Templates define the structure for services. They are loaded from template sources and used to create new service instances.

- **Agent Components**: 
  - Local agent (agent-local/): Installed on the developer's machine
  - Remote agent (agent-remote/): Installed on remote servers to manage services

### Key Design Patterns

- **Singleton Configuration**: Global configuration accessed through gConfig()
- **Command Registry Pattern**: All commands register themselves with the central registry
- **Static Binary Distribution**: Uses musl-libc for fully static executables that work across Linux distributions

### Important Files

- **src/main.cpp**: Entry point, handles command dispatch and validation
- **src/config.cpp/hpp**: Configuration management 
- **src/services.cpp/hpp**: Service operations and metadata
- **src/servers.cpp/hpp**: Server management functions
- **src/templates.cpp/hpp**: Template loading and management
- **cmake_prebuild.sh**: Generates autogen files before build

### Build System

- Uses CMake with Ninja generator
- Fetches dependencies: libassert, cpptrace, nlohmann/json
- Generates version info from timestamps
- Creates fully static binaries using musl cross-compilation toolchain

## Common Operations

### Adding a New Command
1. Create command implementation in src/commands/
2. Register with CommandRegistry including handler, help text, and argument requirements
3. Add autocomplete handler if needed

### Modifying Service Behavior
- Service definitions are in src/services.cpp
- Remote agent scripts in source/agent-remote/ handle service operations on servers

### Working with Templates
- Templates are loaded from configured sources by TemplateManager
- Template metadata and files are cached locally