coddy-agent

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

Chat	Mobile chat
History	Scheduler
Scheduler — job editor	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, layout tokens: DESIGN.md.

Coddy is a distroless-friendly harness: drop it into minimal images (scratch, distroless, read-only workspaces) without a full OS shell. The same agent core is reachable from an IDE over ACP, a browser or any OpenAI client over HTTP, Telegram through the messenger gateway, and cron through the scheduler. The grep and glob filesystem tools use system ripgrep when available and fall back to built-in Go implementations when it is not. 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
• Quick start
  • Install
  • Other installation methods
  • Build tags
  • Docker
  • Paths (CODDY_HOME, CODDY_CWD)
  • Configuration
• How to update
• Operating modes
• Editor and IDE integration
• Rules
• Skills
• MCP server integration
• Messenger gateway
• Configuration (reference)
• Architecture
• Documentation
• Examples (ACP over stdio)
• Persistent sessions
• Development
• 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/, .codex/rules/, and nested **/AGENTS.md (agents.md) under the session cwd - see Rules
• Skills - slash commands and SKILL.md packs from skills.dirs (defaults: ~/.agents/skills, ~/.coddy/skills, ${CWD}/.coddy/skills; later dirs override earlier) - see Skills
• MCP server integration - connect any MCP server for additional tools
• Multi-provider LLM - OpenAI, Anthropic, Ollama, any OpenAI-compatible API
• Context compaction - built-in /compact [instructions] command and automatic summarization when the context reaches compaction.threshold_percent (default 80%) of the model's max_context_tokens; the last compaction.keep_recent_turns (default 2) user turns stay verbatim and the full transcript is preserved on disk - see Configuration
• Multimodal / file attachments - attach images and files via the composer (📎) when multimodal: true in the model config; assets saved to ~/.coddy/sessions/<id>/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
• 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)
• 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
• 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

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.

Configure clients with the absolute path to the binary rather than relying on PATH — some harnesses spawn the agent via cmd /c or sh -c without the user PATH (on Windows: %LOCALAPPDATA%\Programs\coddy\coddy.exe; see docs/install.md).

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.

Windows. The binary lands at %LOCALAPPDATA%\Programs\coddy\coddy.exe; config and sessions live under %USERPROFILE%\.coddy\ (use $env:USERPROFILE, not $HOME). Runtime commands select pwsh, then Windows PowerShell, then cmd.exe; Unix builds select bash, then sh. The installing terminal does not see the updated PATH — open a new one or refresh it in place. Details: 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).

Upgrade later with coddy update -y (How to update).

Prerequisites for building

• Go - same minor version as 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=h