A general-purpose agent in one static Go binary.
A console TUI, an ACP server for editors, an OpenAI-compatible API with an embedded web UI, a Telegram gateway, a cron scheduler, a swarm relay for fleets of nodes and a remote mode, all over the same sessions.
ReAct loop, filesystem and shell tools, MCP, rules, skills, subagents, hooks, background tasks, long-term memory, context compaction and project trust for what arrives with a checkout.

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

Coddy is a harness: the same agent core is reachable from a terminal through the console TUI, from an editor over the Agent Client Protocol, from a browser or any OpenAI client over HTTP, from Telegram through the messenger gateway, and from cron through the scheduler. Every surface shares the sessions under ~/.coddy, so a conversation started in a chat is live in the browser and can be continued in either. It runs in scratch and distroless images with a read-only root filesystem, needs no runtime, and is built for fleets of containers as much as for one laptop.

Install

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

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

The installer puts coddy on PATH, creates ~/.coddy/config.yaml from the release config.example.yaml when it is missing and, on Linux and macOS, installs the man page and the shell completions. Every release also publishes .deb and .rpm packages, a Homebrew cask, archives for Linux, macOS and Windows, and the image ghcr.io/coddy-project/coddy-agent for docker compose up -d. Details for each route are in Install and Docker; building from source is make build TAGS="http ui scheduler memory cli gateway swarm" after git clone, see Build from source.

Then give it a model. Put a provider key into ~/.coddy/config.yaml, or export OPENAI_API_KEY and let the defaults pick it up:

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

models:
  - model: "openai/gpt-5.6-terra"
    max_tokens: 8192
    reasoning_default: medium

agent:
  model: "openai/gpt-5.6-terra"

coddy -t checks the file and coddy --dry-run probes what it points at. Anthropic, NeuralDeep, ChatGPT sign-in through the Codex backend, Ollama, llama.cpp and any other OpenAI-compatible server are covered in Configuration. The first five minutes on every surface are in Quickstart; upgrades are coddy update -y, which ends with the release notes of every version it skipped over (Update).

Surfaces

Surface	Start it	What you get	Guide
Console	coddy	A terminal chat with streamed tool calls, permission prompts, a model picker, !! for a local shell, coddy -c to continue, coddy -p "..." for one-shot answers	Console, video
Web UI and HTTP API	coddy serve	The embedded single-page app on http://127.0.0.1:12345/, OpenAI-compatible /v1/* endpoints and the /coddy REST surface, Swagger at /docs/	Web UI, HTTP API, video
Editors	coddy acp	Zed, VS Code, Obsidian and scripts as ACP clients, with Coddy's modes, models, permissions and skills in the editor's composer	Editors, Zed video, VS Code video
Telegram	coddy serve with gateways.telegram.enable	A bot with per-user sessions, access levels and group isolation; the same chat is live in the web UI	Telegram gateway
Scheduler	coddy serve with scheduler.enable	Cron jobs as Markdown files, each run a session of its own	Scheduler
Swarm	coddy serve with swarm.enable	A relay that lists and reaches many Coddy nodes, including ones that can only dial out	Swarm, video
Remote	coddy --remote host:port	The console, an editor or the browser driving a coddy serve on another machine	Remote mode

coddy serve runs whatever config.yaml enables in one process, and coddy serve --daemon keeps it running in the background with status, stop and restart (coddy serve and the daemon).

What it does

• Three operating modes: agent with every tool, plan for planning and text files, ask for read-only research, switched from any surface (Operating modes).

• Rules and project files: .coddy/rules, .agents/rules, .cursor/rules, .claude/rules, .codex/rules and nested AGENTS.md are picked up as the agent works, and your own ~/.coddy/AGENTS.md, ~/.coddy/DESIGN.md and ~/.coddy/rules apply in every workspace (Rules and instructions).

• Skills: SKILL.md packs become slash commands, installed from skills.sh, the skillsbd registry or any repository (Skills).

• Subagents: spawn_agent delegates a bounded task to a child with its own context and session, tools and permissions only narrowing (Subagents).

• Hooks: your own commands at every lifecycle point, in Claude Code's hooks.json shape, able to deny, approve or rewrite a tool call (Hooks).

• MCP servers over stdio, streamable HTTP and SSE, from config.yaml, mcp.json files or the editor, with a trust gate for what arrives with a checkout (MCP servers).

• Message queue: a follow-up written while the agent works is read by the running turn at its next step, not after it, and a shared session shows the same queue in every browser and console (Message queue).

• Background tasks: detached commands and subagent runs collected later, with a Tasks drawer in the UI (Background tasks).

• Context compaction and long-term memory: /compact and automatic summarisation at a threshold, result eviction with keep_result, a memory copilot that recalls before a turn and saves after (Compaction, Memory).

• Self-configuration: the agent edits its own YAML through staged config_* tools; nothing lands until you approve the commit (config.yaml reference).

• Sessions everywhere: bundles on disk, resume from any surface, branches from an edited message, /export to Markdown, HTML or JSON (Sessions, Session export).

• Any model: OpenAI, Anthropic, NeuralDeep, ChatGPT through Codex, Ollama, llama.cpp, vLLM and every OpenAI-compatible API, with reasoning levels and multimodal attachments per model and retries that honour Retry-After (Configuration).

• Usage and limits: the quota behind the current model in the console footer and in the web UI for providers that publish one (NeuralDeep today), and a turn that hits a limit can wait for the reset and resume by itself (Console, config.yaml reference).

• Config check, dry run and hot reload: coddy -t validates config.yaml against the embedded schema with file:line:col and a fix line, --dry-run probes paths, providers and models, ports, MCP servers, the Telegram token, remotes and swarm joins before anything starts, and a running coddy serve picks up an edited file without a restart (Configuration, coddy serve).

• Fleets: a swarm relay lists and reaches many nodes, mounts their sessions into one list, routes across rings and pulls in nodes that can only dial out through a reverse tunnel; --remote drives a coddy serve on another machine from the console, an editor or the browser (Swarm, Remote mode).

• In the browser: seven themes, English and Russian, @ file mentions and multimodal attachments in the composer, a plan document card, a Tasks drawer, a scheduler editor and a swarm map with the topology (Web UI).

• Closed when it is on a network: a bearer token gates the API for clients, and an optional password sign-in gates the browser - coddy serve set-password, or CODDY_HTTP_USER / CODDY_HTTP_PASSWORD in ~/.coddy/.env - so a coddy serve on 0.0.0.0 is not readable by whoever finds the port (Remote mode, Security and trust).

Project trust is one decision for MCP servers, hooks and subagents that arrive with a repository: nothing from a checkout runs until you approve that exact file (Security and trust).

Documentation

Goal	Start here
Install and run it for the first time	Quickstart, Install
Give it a model or check a config file	Configuration, config.yaml reference
Use it from a terminal, a browser, an editor or Telegram	Console, Web UI, Editors, Telegram gateway
Run it as a service or reach it from elsewhere	coddy serve, Remote mode, Swarm, Scheduler
Bound what it may execute	Security and trust, Operating modes
Teach it your project	Rules, Skills, Subagents, Hooks, MCP servers
Look something up	CLI reference, Environment variables, Slash commands, Tools, HTTP API, ACP protocol
Fix something	Troubleshooting, Changelog
Combine features for a task	Tutorials, the swarm ones included: a relay and its nodes, a chain of relays, working with remote nodes
Change Coddy itself	Contributing, Architecture, AGENTS.md, DESIGN.md

The whole map is docs/README.md. Agents that read documentation get the same pages as llms.txt and llms-full.txt, and the config file carries a JSON Schema at https://coddy.dev/config.schema.json for editor validation. How Coddy compares with other agent harnesses is on coddy.dev/compare.

Contributing

Bug reports and pull requests are welcome at github.com/coddy-project/coddy-agent. CONTRIBUTING.md covers the development environment, the test runs and what a change must carry; AGENTS.md is the map coding agents read before they touch the tree.

License

MIT, see LICENSE.