drharness

A C++20 LLM (Open AI Compatible) harness designed for agentic workflows, file manipulation, and task delegation. It implements a tool-use loop that allows a large language model to dynamically invoke shell commands, edit files, and delegate sub-tasks to other specialized agents. (I wouldn't use the agents feature yet as it is kind of half baked, and I'm not sure when I'll loop back to it)

🏗️ Architectural Overview

drharness is built as a modular C++ application consisting of several key components:

• Harness: The core orchestrator. It manages the conversation history (stored as a JSON array), the active tool registry, and the main execution loop. It repeatedly pushes messages to the LLM, parses tool calls, executes them locally, and appends the results back into the history until the model indicates a final response.
• ToolRegistry: A dynamic system for managing available tools. The LLM receives the list of available tools in JSON format and can invoke them dynamically. The registry includes a base set of tools (file reading, editing, grepping, shell execution) and supports nested agent delegation.
• Agent Profiles: Configurable definitions for specialized sub-agents (e.g., shell_expert). These allow the main agent to offload complex multi-step tasks to a dedicated model/agent instance.
• Client Layer:
  • OllamaClient: Handles the actual communication with an Ollama-compatible API server via HTTP (using libcurl).
  • DebugClient: A CLI-friendly mock client that reads a mock JSON response from stdin, allowing for deterministic testing of harness logic without relying on an external LLM.
• State Management: Conversations are serialized to and deserialized from JSON files. This includes the full message history (history), the active tool registry (tools), and harness configuration (config).

🛠️ How to Build

The project requires CMake version 3.16 or newer, C++20 support, curl, and the nlohmann_json library.

# Configure the build
cmake -B build -DCMAKE_BUILD_TYPE=Release .

# Build the binary
cmake --build build

🧪 How to Run Tests

To run tests first you have to build the project. Then you can run ctest:

cd build
ctest

And it will run the entire test suite

💬 Starting & Continuing Conversations

The harness state is persisted in a JSON file specified by the -F flag.

Starting a New Conversation

To start fresh, you must provide the -n flag and point to a new or empty JSON file. If the file exists and contains data, the harness will refuse to start a new conversation to prevent overwriting history.

./build/drharness -F conversation.json -n -m "Let's start a new project."

Continuing an Old Conversation

To continue a previous session, simply invoke the harness with the same -F file. It will automatically deserialize the saved history, tool registry, and configuration.

./build/drharness -F conversation.json -m "Can you now refactor the main loop?"

Other Useful Flags

• -l: List all available tools.
• -p <file>: Pretty-print a conversation JSON file without running the harness.
• -t <tool>: Manually constrain the harness to a specific subset of tools (by default no tools are provided to the model)
• -m <prompt>: The user prompt to send to the agent.
• -M <model>: Override the Ollama model (e.g., mistral, llama3).

🐳 Docker Isolation

The harness can be compiled and run inside an isolated Alpine Linux container.

1. Build the Docker Image

Use the provided script to build the image. It passes your local Ollama auth token as a build-time argument.

./build_docker.sh

2. Run the Agent

Use the dockerdrh script. This script automatically maps the current working directory to /mnt inside the container and runs the container with the host user's UID/GID to preserve file permissions.

# Start a new conversation inside the container
./dockerdrh -F conversation.json -n -m "Initialize the project"

Note: Inside the container, the working directory is /mnt. Always pass your local JSON file relative to the mapped directory.