Coddy Agent

Run a full general purpose agent from one static Go binary. ReAct, filesystem and shell tools, MCP, Skills, optional OpenAI-compatible API with an embedded UI, scheduler, and long-term memory.

| Desktop (1920×1080) | Mobile (390×844) | |---|---| | | |

More screenshots

| Chat | Mobile chat | |---|---| | | | | History | Scheduler | | | | | Settings | Settings — Skills | | | | | Settings — Appearance | | | | |

Screenshots: desktop at 1920×1080, mobile at 390×844 from the embedded UI (coddy http + Vite dev). Spec and dev workflow: [docs/ui.md](docs/ui.md), layout tokens: [DESIGN.md](DESIGN.md).

Coddy is a distroless-friendly harness: drop it into minimal images (scratch, distroless, read-only workspaces) without a full OS shell. The harness layer (ACP RPC, sessions, prompts, providers) stays the same if you tighten the toolset or drive it from automation instead of an IDE. The design also targets container fleets - many Coddy instances in Docker (orchestrator-defined limits, read-only rootfs, mounted workspace) with full control of each container, similar in spirit to agent OS / swarm-style agents, not a single shared chat pool.

Contents

• [Features](#features)
• [Quick start](#quick-start)
• [Install](#install)
• [Other installation methods](#other-installation-methods)
• [Build tags](#build-tags)
• [Docker](#docker)
• [Paths (CODDY_HOME, CODDY_CWD)](#paths-coddyhome-coddycwd)
• [Configuration](#configuration)
• [How to update](#how-to-update)
• [Operating modes](#operating-modes)
• [Editor and IDE integration](#editor-and-ide-integration)
• [Rules](#rules)
• [Skills](#skills)
• [MCP server integration](#mcp-server-integration)
• [Messenger gateway](#messenger-gateway)
• [Configuration (reference)](#configuration-1)
• [Architecture](#architecture)
• [Documentation](#documentation)
• [Examples (ACP over stdio)](#examples-acp-over-stdio)
• [Persistent sessions](#persistent-sessions)
• [Development](#development)
• [License](#license)

Features

• Harness-first - ACP server, session lifecycle, prompts, LLM backends, MCP merge, distroless-ready binary
• ReAct loop - LLM alternates between reasoning, acting (tool calls), and observing results (coding-agent persona out of the box)
• Two operating modes - agent (full tool access) and plan (planning + text files only)
• Rules - auto-discovers .cursor/rules/, .coddy/rules/, .claude/rules/, and .codex/rules/ under the session cwd - see [Rules](docs/rules.md)
• Skills - slash commands and SKILL.md packs from skills.dirs (defaults: ~/.agents/skills, ~/.coddy/skills, ${CWD}/.coddy/skills; later dirs override earlier) - see [Skills](docs/skills.md)
• MCP server integration - connect any MCP server for additional tools
• Multi-provider LLM - OpenAI, Anthropic, Ollama, any OpenAI-compatible API
• Multimodal / file attachments - attach images and files via the composer (📎) when multimodal: true in the model config; assets saved to ~/.coddy/sessions//assets/ and injected into the agent context; file chips displayed in the user bubble
• Reasoning level - for reasoning models (gpt-5, o-series, Claude thinking models) a composer dropdown picks the effort level (minimal/low/medium/high), mapped to OpenAI reasoning_effort or Anthropic extended-thinking budget_tokens; levels auto-detect from the model id and are configurable per model — see [Configuration](docs/config.md)
• ACP protocol - Coddy is an ACP server (coddy acp); pair it with editors or scripts that implement an ACP client (see [Editor and IDE integration](#editor-and-ide-integration))
• SSH remote execution - built-in ssh_run_command tool runs commands on remote hosts over pure-Go SSH (no external binary); authenticates via SSH agent (SSH_AUTH_SOCK) or ~/.ssh key files — see [Configuration](docs/config.md#ssh-remote-execution)
• Messenger gateway - optional Telegram bot adapter (-tags gateway.telegram); per-user sessions, group isolation modes, admin ACL; extensible to Discord, Slack, etc. — see [Messenger Gateway](docs/gateway.md)

Editor and IDE integration

Coddy is an ACP server (coddy acp). Obsidian, VS Code, Zed, scripts, and the bundled coddy http UI are clients that share the same CODDY_HOME sessions when configured with the same home directory.

Protocol details: docs/acp-protocol.md. Harness examples: examples/acp/.

Quick Start

Install

Linux / macOS - release binary plus ~/.coddy bootstrap:

curl -fsSL https://coddy.dev/install.sh | bash

Windows (PowerShell)

irm https://coddy.dev/install.ps1 | iex

Creates ~/.coddy/config.yaml from the release config.example.yaml when missing. Puts coddy on PATH (Unix: ~/.local/bin; Windows: %LOCALAPPDATA%\Programs\coddy). Full installer options: [docs/install.md](docs/install.md).

Then set a provider key in ~/.coddy/config.yaml (or OPENAI_API_KEY in the environment) and run coddy http for the UI, or coddy acp for an editor client.

Docker - same full binary in ghcr.io/coddy-project/coddy-agent: docker compose up -d (see [Docker](#docker)).

Upgrade later with coddy update -y ([How to update](#how-to-update)).

Other installation methods (build from source, Go install, manual)

Prerequisites for building

• Go - same minor version as [go.mod](go.mod) (currently 1.25).
• Git - used by the Makefile for the embedded version string.
• Node.js / npm - only if you build with http and ui (the Makefile runs ui-build for embedded assets).

Install with Go (lean module default, no http / UI tags)

go install github.com/EvilFreelancer/coddy-agent/cmd/coddy@latest

For coddy http, the bundled SPA, scheduler, and memory, use a release binary (install script above) or build from source below.

Recommended full binary from source

git clone https://github.com/EvilFreelancer/coddy-agent
cd coddy-agent
make build TAGS="http ui scheduler memory"
make install   # copies build/coddy to ~/.local/bin or /usr/local/bin

Or download archives from GitHub Releases.

Manual go build

When TAGS includes http and ui, run make ui-build first.

make ui-build
VERSION="$(make -s print-version)"
go build -tags=http,ui,scheduler,memory \
  -ldflags "-X github.com/EvilFreelancer/coddy-agent/internal/version.Version=${VERSION}" \
  -o build/coddy \
  ./cmd/coddy/

Lean ACP-only binary: make build (no http / UI / scheduler / memory tags).

Build reference: [docs/build.md](docs/build.md).

coddy -v prints the embedded version. coddy acp --help lists ACP flags (--home, --cwd, --config, etc.).

Build tags

Use Makefile variable TAGS with spaces (make build TAGS="http ui scheduler memory"). go build uses commas (-tags=http,ui,scheduler,memory).

| Tag | Enables | Docs | |-----|---------|------| | memory | Long-term memory copilot (memory.enabled in YAML); with http, session memory REST under /coddy/sessions/{id}/memory/* | [external/memory/README.md](external/memory/README.md) | | http | coddy http, REST gateway, /docs, /openapi.yaml | [docs/http-api.md](docs/http-api.md) | | ui | Embedded SPA on / (needs http) | [docs/ui.md](docs/ui.md), [DESIGN.md](DESIGN.md) | | scheduler | Scheduler daemon and coddy_scheduler_* tools; with http, /coddy/scheduler REST | [docs/scheduler.md](docs/scheduler.md), [external/scheduler/README.md](external/scheduler/README.md) | | gateway.telegram | Telegram bot adapter — coddy gateway subcommand, per-user sessions, access control | [docs/gateway.md](docs/gateway.md) | | gateway | All messenger adapters (superset of gateway.telegram; add Discord/Slack without changing the core) | [docs/gateway.md](docs/gateway.md) |

Extended narrative and Docker alignment - [docs/build.md](docs/build.md).

Docker

Release images are published on GitHub Container Registry as ghcr.io/coddy-project/coddy-agent (tags such as latest and X.Y.Z, linux/amd64 and linux/arm64). Each SemVer git tag also gets GitHub Release archives (Linux, Windows, macOS Intel and Apple Silicon) - see [docs/build.md](docs/build.md#release-binaries-ci). The default image includes http, ui, scheduler, and memory - the same feature set as make build TAGS="http ui scheduler memory".

1. Config and workspace (from the repo root, or any directory where you keep config.yaml):

cp config.example.yaml config.yaml
mkdir -p workspace coddy_home
# Edit config.yaml: at least one provider api_key (or rely on OPENAI_API_KEY etc. in compose)

2. Start with Compose (pull published image, no local build):

docker compose pull
docker compose up -d

To build the image locally instead, use docker-compose.dev.yml: docker compose -f docker-compose.dev.yml up -d --build.

3. Open the bundled UI in a browser on the host:

http://127.0.0.1:12345/

The SPA is served on GET / by coddy http. Pick a model in the composer (YAML backends from GET /v1/models), choose agent or plan mode, then send a message - the UI creates a session and streams the reply via POST /v1/responses. Agent files and shell tools use the mounted workspace (./workspace → /workspace in the container). Live YAML editing: http://127.0.0.1:12345/#/settings.

Sanity check without a browser: curl -sS http://127.0.0.1:12345/v1/models | head.

There is no login on the HTTP surface - expose port 12345 only on trusted networks. Full compose options, volumes, and CI image tags: [docs/docker.md](docs/docker.md). Smoke script: examples/httpserver/docker.sh.

Paths (CODDY_HOME, CODDY_CWD)

• CODDY_HOME (or coddy acp --home) is the agent state directory. Default ~/.coddy. The process creates sessions/ and skills/ under it. Config defaults to $CODDY_HOME/config.yaml.
• CODDY_CWD (or coddy acp --cwd) is the default session working directory when session/new sends an empty cwd. Default is the process current directory at startup. Editors that pass a path in session/new use that path instead.

Configuration

CODDY_HOME defaults to ~/.coddy. Unless you set CODDY_CONFIG or pass --config, the primary config file is config.yaml at $CODDY_HOME/config.yaml.

Copy the example and edit it:

mkdir -p ~/.coddy && cp config.example.yaml ~/.coddy/config.yaml

If $CODDY_HOME/config.yaml is absent, the loader may use config.yaml in the process working directory (useful when running from a repository clone). See docs/config.md.

Providers and models

• providers - named backends (type: openai for OpenAI and OpenAI-compatible HTTP APIs, anthropic for Anthropic). Each name must be ASCII letters, digits, hyphen, or underscore, starting with a letter (it becomes the prefix in model ids). Each row has api_key (literal, ${ENV} expanded when the file loads, or empty to read NAME_API_KEY from the environment at LLM call time, with NAME derived from providers[].name in uppercase and hyphens mapped to underscores), and optionally api_base when the API is not the vendor default.
• models - selectable models. Each model string is / where provider_name matches providers[].name. Tunables include max_tokens, temperature, and optional max_context_tokens.
• agent - model picks the default ReAct model (must match one models[].model entry). max_turns and max_tokens_per_turn bound one user turn.

Example (openai provider and gpt-5.4-mini; store secrets in the environment, not in git):

providers:
  - name: openai
    type: openai
    api_key: "${OPENAI_API_KEY}"

models:
  - model: "openai/gpt-5.4-mini"
    max_tokens: 400000
    temperature: 0.2

agent:
  model: "openai/gpt-5.4-mini"
  max_turns: 35
  max_tokens_per_turn: 128000

Then export the key the YAML references:

export OPENAI_API_KEY="sk-..."

Other setups (Anthropic, Ollama, a non-default api_base, and env-based defaults) are covered in config.example.yaml and [docs/config.md](docs/config.md).

How to update

Official CLI binaries are published on GitHub Releases (assets such as coddy_0.9.3_linux_amd64.tar.gz). Each release matches the full feature set from make build TAGS="http ui scheduler memory".

coddy update downloads the archive for your OS/architecture and replaces the binary you invoked (symlinks resolved). That is the usual path after make install (~/.local/bin/coddy) or when you run ./build/coddy update to refresh a local build artifact.

1. See what you run today

which coddy
coddy -v

2. Check for a newer release

coddy update --check

Exit code 0 means you are already on the latest published X.Y.Z (or newer). Exit code 1 means a newer release is available.

3. Install

coddy update          # asks [y/N]
coddy update -y       # no prompt

4. Confirm

coddy -v
coddy http --help     # only when the binary includes -tags=http (release builds do)

Common flags

| Flag | Purpose | |------|---------| | --check | Only report whether an update exists (no download). | | -y / --yes | Install without confirmation. | | --version X.Y.Z | Install a specific release, not only "latest". | | --repo owner/name | Alternate GitHub repo (default coddy-project/coddy-agent). |

Notes

• Update the same binary you intend to use. If which coddy points at ~/.local/bin/coddy, run coddy update from that install, not a different copy on PATH.
• $CODDY_HOME (config, sessions, skills) is untouched; only the executable changes.
• To build from source or change tags, use make build instead. For containers, use docker compose pull. See [docs/update.md](docs/update.md) for platform tables, limitations, and other upgrade paths.

Operating Modes

Agent Mode (default)

Full task execution mode. The agent has access to all tools:

• Read and write files
• Execute shell commands (with permission prompt)
• Search codebase
• Call MCP server tools

Best for: code generation, refactoring, debugging, feature implementation.

Plan Mode

Planning and documentation mode. Restricted tools:

• Read files (no write to code files)
• Write/edit text and markdown files
• Search codebase

When the plan is ready, switch to agent mode yourself for full tools and implementation.

Best for: architecture planning, writing specs, design documents, code review.

Use your editor session mode selector (or session/set_config_option).

Rules

Project rules (injected as {{.Rules}}) are discovered under the session working directory from .coddy/rules, .cursor/rules, .claude/rules, and .codex/rules when rules.auto_discover is true. See [docs/rules.md](docs/rules.md).

Rule files often use Cursor-style frontmatter, for example:

---
description: "Go coding st

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [coddy-project](https://github.com/coddy-project)
- **Source:** [coddy-project/coddy-agent](https://github.com/coddy-project/coddy-agent)
- **License:** MIT
- **Homepage:** https://coddy.dev/

Install and usage instructions live in the source repository linked above.