andy-agent

Andy Agent is not an agent. It’s the runtime that forms one.

A small local agent runtime for self-hosted, OpenAI-compatible inference servers. It has no mandatory cloud service and sends no telemetry.

The system is based on a clearly separated architecture of Persona, Skill, and Tools.

Core Idea

The system separates behavior and execution into three layers:

Persona → defines the agent's role and focus Skill → describes the working logic and analysis procedures Tools → stable, hardcoded functions (Shell, File I/O, Search, Edit)

Optionally, the system can integrate external toolchains and sub-agents via MCP.

Design Goals

• fully executable offline
• no mandatory cloud API
• reproducible behavior per session
• minimized system context for VRAM-efficient execution
• clear separation between identity (Persona) and logic (Skill)
• safe tool execution with a permission system

Important System Property

Skills are loaded and overwritten on a per-session basis. Exactly one active skill is valid per session.

No skill composition or skill stacking takes place.

Project Structure

andy-agent/
├── personas/        # Persona definitions (Role Layer)
├── skills/          # Execution logic (Skill Layer)
├── tools/           # Hardcoded runtime tools
├── docs/            # Architecture & developer documentation
├── utils/           # MCP/VM launch helpers
├── vendor/          # Audited bundled dependencies
├── agent.sh         # Linux/macOS launcher (profile + persona selection)
├── agent.bat        # Windows launcher (profile + persona selection)
├── agent-basic.ps1  # Windows basic-profile script
└── agent-full.ps1   # Windows full-profile script

Quick Start

1. Install Build Dependencies

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install -y build-essential cmake ccache

Linux (Arch Linux):

sudo pacman -S --needed base-devel cmake ccache

macOS:

brew install cmake ccache

Windows:

• Install Visual Studio 2026 (Community Edition is free)
• Check "C++ desktop development" during installation
• Install CMake or use the VS Code CMake extension

2. Build

Linux / macOS:

# Change into the program directory
cd andy-agent

# CMake (recommended)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target andy-agent-basic andy-agent-full andy-agent-mcp-router andy-agent-mcp -j

Tip: For faster incremental builds, configure with ccache:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

Windows (MSVC):

# Change into the program directory
cd andy-agent

# CMake with Visual Studio generator
cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release --target ALL_BUILD -j

# Or build specific targets
cmake --build build --config Release --target andy-agent-basic

Note: On Windows, the build directory can be either in the project root (andy-agent-main/build/) when invoking CMake from there, or inside the andy-agent/ folder. The agent.bat launcher handles both locations automatically.

Low-memory systems (Raspberry Pi, Odroid): CMake is configured to build sequentially by default (CMAKE_BUILD_PARALLEL_LEVEL=1). For faster builds on systems with more RAM, use:

cmake --build build --target ALL_BUILD -j2

The build produces four security profiles:

• build/andy-agent-basic: safe local default with bounded file tools, no shell executor, no stdio-MCP process launch, and no --yolo option. HTTP-MCP remains available.
• build/andy-agent-full: shell-enabled local runtime with interactive permissions; no --yolo option.
• build/andy-agent-mcp-router: host-side router with only local read, update_plan, and validated single-file unidiff tools.
• build/andy-agent-mcp: Streamable HTTP subagent runtime intended for an isolated VM with the complete local tool set. This is the only profile that accepts --yolo.

2. Start

Linux / macOS:

# Interactive: build-profile selection (basic/full) + persona selection
./agent.sh

# Direct
./build/andy-agent-basic --url http://localhost:8081

# Restricted router with its fixed Persona, Skill, and one HTTP MCP subagent
ANDY_INFERENCE_URL=http://localhost:8081 \
ANDY_SUBAGENT_URL=http://127.0.0.1:31234/mcp \
./mcp-router.sh

Build-profile selection: agent.sh prompts for a build profile before starting. Choosing andy-agent-full (option 2) requires two explicit confirmations (j) because the full profile can access the filesystem, execute programs, and make system changes.

Windows:

# Interactive: build-profile selection (basic/full) + persona selection
.\agent.bat

# Direct
.\build\Debug\andy-agent-basic.exe --url http://localhost:8081

# Restricted router with its fixed Persona, Skill, and one HTTP MCP subagent
$env:ANDY_INFERENCE_URL="http://localhost:8081"
$env:ANDY_SUBAGENT_URL="http://127.0.0.1:31234/mcp"
.\build\Debug\andy-agent-mcp-router.exe

Windows launcher: agent.bat prompts for a build profile (basic or full), then calls the matching PowerShell script (agent-basic.ps1 or agent-full.ps1). Choosing the full profile requires two explicit confirmations (j). The script provides an interactive wizard for selecting the inference server (host/port), workspace directory, and persona. It copies the selected persona and skill to ~/.andy-agent/ and starts the agent automatically.

mcp-router.sh uses the fixed resources in router/, keeps its configuration and sessions separate under ~/.andy-agent-router, and connects only to the explicit Streamable HTTP endpoint in router/mcp.json. Override the trusted configuration with ANDY_ROUTER_MCP_CONFIG=/absolute/path/mcp.json.

Slash Commands

Command	Description
/exit	Exit
/clear	Clear chat history
/tools	Show available tools
/skills	Show available skills
/stats	Token statistics
/compact	Compact the context

Personas

Personas control the agentic behavior via personas/*.md:

personas/
├── cpp-expert.md        # Senior C++ developer
├── python-expert.md     # Python expert
├── devops.md            # DevOps engineer
├── rust-specialist.md   # Rust specialist
├── tech-writer.md       # Technical writer
└── ...                 # More in personas/

Selection via agent.sh

Skills

Skills define the execution logic of an agent.

They contain, for example:

Analysis workflows Decision logic Verification processes Output structure Test generation

Important property:

Exactly one skill is active per session.

Tool profiles

Binary	Local tools
andy-agent-basic	read, glob, edit, write, update_plan; HTTP-MCP only
andy-agent-full	Basic tools plus bash and interactive !/!!
andy-agent-mcp-router	read, unidiff, update_plan plus configured HTTP MCP tools
andy-agent-mcp	Basic tools plus bash, for an isolated guest only

Security

The local runtimes ask for confirmation before dangerous actions (y/n/a/d). --yolo is rejected by every local binary. It is available only to andy-agent-mcp, which additionally requires an explicit isolation acknowledgement:

./build/andy-agent-mcp --url http://localhost:8081 \
  --acknowledge-isolation --yolo

The acknowledgement records an operator decision; it cannot technically prove that a VM or equivalent isolation boundary exists.

Session Management

# Resume
./build/andy-agent-basic --url http://localhost:8081 --resume

# Explicit session file
./build/andy-agent-basic --url http://localhost:8081 --session ./session.jsonl

# Disable session
./build/andy-agent-basic --url http://localhost:8081 --no-session

Structure

andy-agent/
├── agent.sh              # Launch script (server + persona)
├── personas/               # Persona definitions (*.md)
│   ├── cpp-expert.md
│   ├── python-expert.md
│   ├── devops.md
│   ├── rust-specialist.md
│   ├── tech-writer.md
│   ├── ui-designer.md
│   ├── unit-test-writer.md
│   └── ...               # More in personas/
├── build/                # Compiled binary
├── docs/                 # Complete documentation
│   ├── DOCUMENTATION.md  # Everything in one place
│   └── templates/        # Inactive, manually reviewed examples
├── skills/               # Project-local skills
│   ├── cpp-expert/
│   ├── python/
│   ├── testing/
│   └── ...               # More in skills/
├── tools/                # C++ tool implementations
│   ├── tools/            # Bash, Read, Write, Edit, Glob, Plan
│   ├── mcp/              # MCP client & server
│   ├── persona/          # Active persona loader
│   └── skills/           # Skills manager
├── vendor/               # Dependencies (cpp-httplib, json, stb)

Advanced Options

# Limit the maximum number of iterations
./build/andy-agent-basic --url http://localhost:8081 --max-iterations 10

# Disable MCP or skills
./build/andy-agent-basic --url http://localhost:8081 --no-mcp
./build/andy-agent-basic --url http://localhost:8081 --no-skills

# Disable context compaction
./build/andy-agent-basic --url http://localhost:8081 --no-compaction

# Additional skills search path
./build/andy-agent-basic --url http://localhost:8081 --skills-path /path/to/skills

# Simple output (no colors, no formatting)
./build/andy-agent-basic --url http://localhost:8081 --simple-io --no-color

Complete Documentation

See docs/DOCUMENTATION.md for build instructions, architecture, developer guide, and all details. See MCP_SERVER.md for isolated MCP deployment.

Contributing and security

Community contributions are welcome. See CONTRIBUTING.md before opening a pull request and CODE_OF_CONDUCT.md for the project community guidelines.

Please report potentially exploitable issues according to SECURITY.md, without publishing credentials, private sessions, or working exploit details in a public issue. A secrets-free configuration starting point is available in .env.example.

The vendored component inventory is available as a CycloneDX SBOM in sbom.cdx.json. Security support terms are documented in SUPPORT.md.

License and attribution

Andy Agent is open-source software licensed under the MIT License. Project-owned source code and documentation may be used, modified, and redistributed under those terms. Bundled third-party files remain subject to their retained copyright and license notices.

The project was originally based on and inspired by llama-agent by Victor Mustar (gary149). llama-agent builds on the pioneering work of the llama.cpp and ggml contributors and credits Pi by Mario Zechner as an inspiration.

Andy Agent has since evolved into an independent, small HTTP- and MCP-based agent runtime with a substantially different architecture and scope. The original ggml copyright and MIT permission notice are retained in the project license. Notices for bundled libraries are listed in THIRD_PARTY_NOTICES.md.

Project maintainer

Andy Agent is initiated and maintained by Ralf Meyne.