{"id":50140330,"url":"https://github.com/coddy-project/coddy-agent","last_synced_at":"2026-06-15T01:03:44.971Z","repository":{"id":347676954,"uuid":"1189273325","full_name":"coddy-project/coddy-agent","owner":"coddy-project","description":"Open-source distroless harness coding agent in Go. Has embedded WebUI. Works with any IDE via ACP and with OpenAI clients via OpenAI-compatible REST API. Supports any OpenAI-compatible providers. Can use SKILLS and MCP servers.","archived":false,"fork":false,"pushed_at":"2026-06-14T16:06:42.000Z","size":12257,"stargazers_count":52,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-14T18:06:48.282Z","etag":null,"topics":["acp","agent","agent-client-protocol","antropic","cli","code-agent","llm","mcp","openai","skills"],"latest_commit_sha":null,"homepage":"https://coddy.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coddy-project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-23T06:37:12.000Z","updated_at":"2026-06-14T16:06:38.000Z","dependencies_parsed_at":"2026-06-07T01:01:06.158Z","dependency_job_id":null,"html_url":"https://github.com/coddy-project/coddy-agent","commit_stats":null,"previous_names":["coddy-project/coddy-agent"],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/coddy-project/coddy-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coddy-project%2Fcoddy-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coddy-project%2Fcoddy-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coddy-project%2Fcoddy-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coddy-project%2Fcoddy-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coddy-project","download_url":"https://codeload.github.com/coddy-project/coddy-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coddy-project%2Fcoddy-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34343313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acp","agent","agent-client-protocol","antropic","cli","code-agent","llm","mcp","openai","skills"],"created_at":"2026-05-24T01:01:12.349Z","updated_at":"2026-06-15T01:03:44.964Z","avatar_url":"https://github.com/coddy-project.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://go.dev/doc/go1.25\"\u003e\u003cimg src=\"https://img.shields.io/badge/go-1.25+-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go 1.25+\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/EvilFreelancer/coddy-agent\" alt=\"MIT License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/EvilFreelancer/coddy-agent/actions/workflows/tests-on-pr.yaml\"\u003e\u003cimg src=\"https://github.com/EvilFreelancer/coddy-agent/actions/workflows/tests-on-pr.yaml/badge.svg\" alt=\"Tests on PR\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://agentclientprotocol.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/ACP-harness-9333EA\" alt=\"ACP harness\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/distroless%20ready-252525\" alt=\"distroless-ready\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/single%20binary-252525\" alt=\"single binary\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/coddy-logo-wordmark.svg\" alt=\"Coddy agent\" height=\"156\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eRun a full general purpose agent from one static Go binary.\u003c/strong\u003e\u003cbr /\u003e\n  ReAct, filesystem and shell tools, MCP, Skills, optional OpenAI-compatible API with an embedded UI, scheduler, and long-term memory.\n\u003c/p\u003e\n\n| Desktop (1920×1080) | Mobile (390×844) |\n|---|---|\n| ![Start screen](docs/assets/screenshot-fullhd-start.png) | ![Mobile start](docs/assets/screenshot-mobile-start.png) |\n\n\u003cdetails\u003e\n\u003csummary\u003eMore screenshots\u003c/summary\u003e\n\n| Chat | Mobile chat |\n|---|---|\n| ![Chat](docs/assets/screenshot-fullhd-chat.png) | ![Mobile chat](docs/assets/screenshot-mobile-chat.png) |\n| **History** | **Scheduler** |\n| ![History](docs/assets/screenshot-fullhd-history.png) | ![Scheduler](docs/assets/screenshot-fullhd-scheduler.png) |\n| **Settings** | **Settings — Skills** |\n| ![Settings](docs/assets/screenshot-fullhd-settings.png) | ![Settings Skills](docs/assets/screenshot-fullhd-settings-skills.png) |\n| **Settings — Appearance** | |\n| ![Settings Appearance](docs/assets/screenshot-fullhd-settings-appearance.png) | |\n\nScreenshots: 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).\n\n\u003c/details\u003e\n\nCoddy 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.\n\n## Contents\n\n- [Features](#features)\n- [Quick start](#quick-start)\n  - [Install](#install)\n  - [Other installation methods](#other-installation-methods)\n  - [Build tags](#build-tags)\n  - [Docker](#docker)\n  - [Paths (`CODDY_HOME`, `CODDY_CWD`)](#paths-coddy_home-coddy_cwd)\n  - [Configuration](#configuration)\n- [How to update](#how-to-update)\n- [Operating modes](#operating-modes)\n- [Editor and IDE integration](#editor-and-ide-integration)\n- [Rules](#rules)\n- [Skills](#skills)\n- [MCP server integration](#mcp-server-integration)\n- [Messenger gateway](#messenger-gateway)\n- [Configuration (reference)](#configuration-1)\n- [Architecture](#architecture)\n- [Documentation](#documentation)\n- [Examples (ACP over stdio)](#examples-acp-over-stdio)\n- [Persistent sessions](#persistent-sessions)\n- [Development](#development)\n- [License](#license)\n\n## Features\n\n- **Harness-first** - ACP server, session lifecycle, prompts, LLM backends, MCP merge, distroless-ready binary\n- **ReAct loop** - LLM alternates between reasoning, acting (tool calls), and observing results (coding-agent persona out of the box)\n- **Two operating modes** - `agent` (full tool access) and `plan` (planning + text files only)\n- **Rules** - auto-discovers **`.cursor/rules/`**, **`.coddy/rules/`**, **`.claude/rules/`**, and **`.codex/rules/`** under the session cwd - see [Rules](docs/rules.md)\n- **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)\n- **MCP server integration** - connect any MCP server for additional tools\n- **Multi-provider LLM** - OpenAI, Anthropic, Ollama, any OpenAI-compatible API\n- **Multimodal / file attachments** - attach images and files via the composer (📎) when `multimodal: true` in the model config; assets saved to `~/.coddy/sessions/\u003cid\u003e/assets/` and injected into the agent context; file chips displayed in the user bubble\n- **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)\n- **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))\n- **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)\n- **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)\n\n## Editor and IDE integration\n\nCoddy 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.\n\nProtocol details: **`docs/acp-protocol.md`**. Harness examples: **`examples/acp/`**.\n\n## Quick Start\n\n### Install\n\n**Linux / macOS** - release binary plus **`~/.coddy`** bootstrap:\n\n```bash\ncurl -fsSL https://coddy.dev/install.sh | bash\n```\n\n**Windows (PowerShell)**\n\n```powershell\nirm https://coddy.dev/install.ps1 | iex\n```\n\nCreates **`~/.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)**.\n\nThen 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.\n\n**Docker** - same full binary in **`ghcr.io/coddy-project/coddy-agent`**: **`docker compose up -d`** (see [Docker](#docker)).\n\nUpgrade later with **`coddy update -y`** ([How to update](#how-to-update)).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOther installation methods\u003c/strong\u003e (build from source, Go install, manual)\u003c/summary\u003e\n\n**Prerequisites for building**\n\n- **Go** - same minor version as [`go.mod`](go.mod) (currently **1.25**).\n- **Git** - used by the Makefile for the embedded version string.\n- **Node.js / npm** - only if you build with **`http`** and **`ui`** (the Makefile runs **`ui-build`** for embedded assets).\n\n**Install with Go (lean module default, no `http` / UI tags)**\n\n```bash\ngo install github.com/EvilFreelancer/coddy-agent/cmd/coddy@latest\n```\n\nFor **`coddy http`**, the bundled SPA, scheduler, and memory, use a **release binary** (install script above) or **build from source** below.\n\n**Recommended full binary from source**\n\n```bash\ngit clone https://github.com/EvilFreelancer/coddy-agent\ncd coddy-agent\nmake build TAGS=\"http ui scheduler memory\"\nmake install   # copies build/coddy to ~/.local/bin or /usr/local/bin\n```\n\nOr download archives from [GitHub Releases](https://github.com/coddy-project/coddy-agent/releases).\n\n**Manual `go build`**\n\nWhen **`TAGS`** includes **`http`** and **`ui`**, run **`make ui-build`** first.\n\n```bash\nmake ui-build\nVERSION=\"$(make -s print-version)\"\ngo build -tags=http,ui,scheduler,memory \\\n  -ldflags \"-X github.com/EvilFreelancer/coddy-agent/internal/version.Version=${VERSION}\" \\\n  -o build/coddy \\\n  ./cmd/coddy/\n```\n\nLean **ACP-only** binary: **`make build`** (no **`http`** / UI / scheduler / memory tags).\n\nBuild reference: **[`docs/build.md`](docs/build.md)**.\n\n\u003c/details\u003e\n\n**`coddy -v`** prints the embedded version. **`coddy acp --help`** lists ACP flags (**`--home`**, **`--cwd`**, **`--config`**, etc.).\n\n### Build tags\n\nUse **`Makefile`** variable **`TAGS`** with **spaces** (**`make build TAGS=\"http ui scheduler memory\"`**). **`go build`** uses **commas** (**`-tags=http,ui,scheduler,memory`**).\n\n| Tag | Enables | Docs |\n|-----|---------|------|\n| **`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) |\n| **`http`** | **`coddy http`**, REST gateway, **`/docs`**, **`/openapi.yaml`** | [`docs/http-api.md`](docs/http-api.md) |\n| **`ui`** | Embedded SPA on **`/`** (needs **`http`**) | [`docs/ui.md`](docs/ui.md), [`DESIGN.md`](DESIGN.md) |\n| **`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) |\n| **`gateway.telegram`** | Telegram bot adapter — **`coddy gateway`** subcommand, per-user sessions, access control | [`docs/gateway.md`](docs/gateway.md) |\n| **`gateway`** | All messenger adapters (superset of `gateway.telegram`; add Discord/Slack without changing the core) | [`docs/gateway.md`](docs/gateway.md) |\n\nExtended narrative and Docker alignment - **[docs/build.md](docs/build.md)**.\n\n### Docker\n\nRelease images are published on **[GitHub Container Registry](https://github.com/coddy-project/coddy-agent/pkgs/container/coddy-agent)** 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\"`**.\n\n**1. Config and workspace** (from the repo root, or any directory where you keep **`config.yaml`**):\n\n```bash\ncp config.example.yaml config.yaml\nmkdir -p workspace coddy_home\n# Edit config.yaml: at least one provider api_key (or rely on OPENAI_API_KEY etc. in compose)\n```\n\n**2. Start with Compose** (pull published image, no local build):\n\n```bash\ndocker compose pull\ndocker compose up -d\n```\n\nTo **build the image locally** instead, use **`docker-compose.dev.yml`**: **`docker compose -f docker-compose.dev.yml up -d --build`**.\n\n**3. Open the bundled UI** in a browser on the host:\n\n```text\nhttp://127.0.0.1:12345/\n```\n\nThe 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`**.\n\nSanity check without a browser: **`curl -sS http://127.0.0.1:12345/v1/models | head`**.\n\nThere 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`**.\n\n### Paths (`CODDY_HOME`, `CODDY_CWD`)\n\n- **`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`**.\n- **`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.\n\n### Configuration\n\n**`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`**.\n\nCopy the example and edit it:\n\n```bash\nmkdir -p ~/.coddy \u0026\u0026 cp config.example.yaml ~/.coddy/config.yaml\n```\n\nIf **`$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`**.\n\n**Providers and models**\n\n- **`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.\n- **`models`** - selectable models. Each **`model`** string is **`\u003cprovider_name\u003e/\u003capi_model_id\u003e`** where **`provider_name`** matches **`providers[].name`**. Tunables include **`max_tokens`**, **`temperature`**, and optional **`max_context_tokens`**.\n- **`agent`** - **`model`** picks the default ReAct model (must match one **`models[].model`** entry). **`max_turns`** and **`max_tokens_per_turn`** bound one user turn.\n\nExample (**`openai`** provider and **`gpt-5.4-mini`**; store secrets in the environment, not in git):\n\n```yaml\nproviders:\n  - name: openai\n    type: openai\n    api_key: \"${OPENAI_API_KEY}\"\n\nmodels:\n  - model: \"openai/gpt-5.4-mini\"\n    max_tokens: 400000\n    temperature: 0.2\n\nagent:\n  model: \"openai/gpt-5.4-mini\"\n  max_turns: 35\n  max_tokens_per_turn: 128000\n```\n\nThen export the key the YAML references:\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\nOther 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)**.\n\n## How to update\n\nOfficial CLI binaries are published on **[GitHub Releases](https://github.com/coddy-project/coddy-agent/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\"`**.\n\n**`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.\n\n**1. See what you run today**\n\n```bash\nwhich coddy\ncoddy -v\n```\n\n**2. Check for a newer release**\n\n```bash\ncoddy update --check\n```\n\nExit code **0** means you are already on the latest published **`X.Y.Z`** (or newer). Exit code **1** means a newer release is available.\n\n**3. Install**\n\n```bash\ncoddy update          # asks [y/N]\ncoddy update -y       # no prompt\n```\n\n**4. Confirm**\n\n```bash\ncoddy -v\ncoddy http --help     # only when the binary includes -tags=http (release builds do)\n```\n\n**Common flags**\n\n| Flag | Purpose |\n|------|---------|\n| **`--check`** | Only report whether an update exists (no download). |\n| **`-y`** / **`--yes`** | Install without confirmation. |\n| **`--version X.Y.Z`** | Install a specific release, not only \"latest\". |\n| **`--repo owner/name`** | Alternate GitHub repo (default **`coddy-project/coddy-agent`**). |\n\n**Notes**\n\n- 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`**.\n- **`$CODDY_HOME`** (config, sessions, skills) is untouched; only the executable changes.\n- 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.\n\n## Operating Modes\n\n### Agent Mode (default)\n\nFull task execution mode. The agent has access to all tools:\n- Read and write files\n- Execute shell commands (with permission prompt)\n- Search codebase\n- Call MCP server tools\n\nBest for: code generation, refactoring, debugging, feature implementation.\n\n### Plan Mode\n\nPlanning and documentation mode. Restricted tools:\n- Read files (no write to code files)\n- Write/edit text and markdown files\n- Search codebase\n\nWhen the plan is ready, switch to **agent** mode yourself for full tools and implementation.\n\nBest for: architecture planning, writing specs, design documents, code review.\n\nUse your editor session mode selector (or **`session/set_config_option`**).\n\n## Rules\n\nProject 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)**.\n\nRule files often use Cursor-style frontmatter, for example:\n\n```markdown\n---\ndescription: \"Go coding standards\"\nglobs: [\"**/*.go\"]\nalwaysApply: false\n---\n\nWrite all comments in English.\nUse fmt.Errorf(\"context: %w\", err) for error wrapping.\n```\n\n## Skills\n\nSlash commands and **`SKILL.md`** packs (injected as **`{{.Skills}}`**) extend the agent with domain knowledge and specialized workflows.\n\n**Default directories (lowest → highest priority):**\n\n| Priority | Path | Purpose |\n|----------|------|---------|\n| lowest | `~/.agents/skills/` | Global skills — installed by `npx skills` or `npx skillsbd`, shared with all agents |\n| ↑ | `~/.coddy/skills/` | Coddy-specific skills; may contain symlinks into `~/.agents/skills/` |\n| highest | `${CWD}/.coddy/skills/` | Project-local skills — override anything from higher directories |\n\nLater directories override earlier ones when the same skill name appears in multiple locations.\n\n**Finding and installing skills:**\n\n- **[skills.sh](https://skills.sh)** — community registry, install with `npx skills add \u003cowner/repo@skill\u003e`\n- **[neuraldeep.ru/skills](https://neuraldeep.ru/skills)** — skillsbd registry curated for Coddy, install with `npx skillsbd install \u003cname\u003e`\n- **Settings → Skills** in the web UI (`coddy http`) — browse and install from the skillsbd registry without leaving the browser\n\n**CLI:**\n\n```bash\ncoddy skills list              # list installed skills with enabled/disabled status\ncoddy skills enable \u003cname\u003e     # enable a skill\ncoddy skills disable \u003cname\u003e    # disable without uninstalling\n```\n\nSee **[`docs/skills.md`](docs/skills.md)** for the full reference.\n\n## MCP Server Integration\n\nConnect external tools via MCP servers. Configured globally in `config.yaml` or\npassed per-session by the ACP client.\n\nExample adding a GitHub MCP server in config:\n\n```yaml\nmcp_servers:\n  - name: \"github\"\n    command: \"npx\"\n    args: [\"-y\", \"@modelcontextprotocol/server-github\"]\n    env:\n      - name: \"GITHUB_PERSONAL_ACCESS_TOKEN\"\n        value: \"${GITHUB_TOKEN}\"\n```\n\nSee [MCP Integration Guide](docs/mcp-integration.md) for details.\n\n## Messenger gateway\n\nBuild with **`-tags gateway.telegram`** (Telegram only) or **`-tags gateway`** (all adapters) to enable `coddy gateway`.\n\n```bash\nmake build TAGS=\"gateway.telegram\"\n./build/coddy gateway --config ~/.coddy/config.yaml\n```\n\nMinimal config addition (`config.yaml`):\n\n```yaml\ngateways:\n  telegram:\n    enabled: true\n    token: \"${TELEGRAM_BOT_TOKEN}\"\n    admins: [YOUR_USER_ID]\n    default_access: \"admins\"   # all | admins | group:\u003cname\u003e\n    default_isolation: \"admin\" # individual | shared | admin\n```\n\nEach user or chat gets its own isolated session. In group chats the bot responds only when @mentioned or replied to. `/clear` (no space) starts a fresh session.\n\nFull guide — access levels, group isolation modes, per-chat overrides, and how to write adapters for new messengers: **[docs/gateway.md](docs/gateway.md)**.\n\n## Configuration\n\nFull configuration reference in [docs/config.md](docs/config.md).\n\nKey settings:\n\n```yaml\nproviders:\n  - name: local\n    type: openai\n    api_key: \"${OPENAI_API_KEY}\"\n    api_base: \"${OPENAI_API_BASE}\"\n\nmodels:\n  - model: \"local/gpt-4o\"\n    max_tokens: 8192\n    temperature: 0.2\n\nagent:\n  model: \"local/gpt-4o\"\n  max_turns: 30\n\ntools:\n  require_permission_for_commands: true\n```\n\n## Architecture\n\n```\nACP client (editor / script / CI)        Messenger (Telegram, …)\n        |                                        |\n    JSON-RPC 2.0 over stdio              gateway Hub (per adapter goroutine)\n        |                                        |\n    ACP Server Layer                     session.Manager (shared)\n        |                                        |\n    Session Manager ─────────────────────────────┘\n        |\n    ReAct Agent Loop\n /      |       |      \\\nLLM   Tools    Skills    MCP\n```\n\nSee [Architecture docs](docs/architecture.md) for full details.\n\n## Documentation\n\n- [Build from source](docs/build.md) - prerequisites, **`make build`**, **`TAGS`** vs **`go build -tags`**, **`build/coddy`**\n- [Updating Coddy](docs/update.md) - **`coddy update`**, release assets, **`PATH`** vs **`make install`**\n- [Docker](docs/docker.md) - GHCR image, **`docker compose`**, bundled UI at **`http://127.0.0.1:12345/`**\n- [Architecture](docs/architecture.md) - system design and component overview\n- [ACP Protocol](docs/acp-protocol.md) - protocol reference and message formats\n- [ReAct Agent](docs/react-agent.md) - ReAct loop design and tool specifications\n- [Configuration](docs/config.md) - full config file reference\n- [HTTP API](docs/http-api.md) - REST gateway (**`-tags=http`**) and embedded UI (**`-tags=http,ui`**); includes **`/coddy/config`** for live YAML editing from the SPA (**#/settings**).\n- [Embedded UI](docs/ui.md) - functional spec, Vite dev workflow, build tags\n- [DESIGN.md](DESIGN.md) - UI tokens and layout (English)\n- [AGENTS.md](AGENTS.md) - repo map and contributor notes for automation\n- [Rules](docs/rules.md) - project rules (`.cursor/rules`, `.coddy/rules`, …)\n- [Skills](docs/skills.md) - slash commands and **`skills.dirs`**\n- [MCP Integration](docs/mcp-integration.md) - MCP server integration guide\n- [Messenger Gateway](docs/gateway.md) - Telegram bot adapter, session isolation, ACL, and how to write new adapters\n\n## Examples (ACP over stdio)\n\n[**`examples/acp/acp_e2e_todo.py`**](examples/acp/acp_e2e_todo.py) is a newline-delimited JSON-RPC harness against **`coddy acp`** ( **`stdbuf -oL`**, permission auto-reply, nil-result responses). Use it as reference when building your own minimal client rather than chaining naive **`echo`** lines into a pipe.\n\n[**`examples/acp/acp_e2e_memory.py`**](examples/acp/acp_e2e_memory.py) drives **`build/coddy`**, an isolated **`CODDY_HOME`**, and **`RPA_API_KEY`** to verify recall, persist, and optional prune of markdown under **`$CODDY_HOME/memory`**. See the script docstring for flags. Overview of all harnesses - [**`examples/README.md`**](examples/README.md).\n\n## Persistent sessions\n\nBy default, `coddy acp` and `coddy http` store each session bundle under **`$CODDY_HOME/sessions/\u003csessionId\u003e/`** (default **`~/.coddy/sessions/`**) with `session.json`, `messages.json`, an `assets/` directory, and `todos/active.md` (plus `todos/archive/` when completed lists are replaced). Override the root with **`coddy acp --sessions-dir`**, **`coddy http --sessions-dir`**, or **`sessions.dir`** in **`config.yaml`**. If the sessions directory cannot be created, startup fails with an error.\n\n- **`coddy sessions list`** prints stored sessions (`--sessions-dir` and `--cwd` filters supported).\n- **`coddy acp --session-id \u003cid\u003e`** makes the **next** `session/new` either reopen snapshots for that folder (if present) or create a fresh bundle whose directory name matches that id.\n- **`session/load`** restores history and notifies the client; **`session/list`** lists bundles for ACP-aware clients.\n\nThe coddy todo tools keep the active checklist mirrored to `todos/active.md`. A wholesale **`coddy_todo_plan_replace`** while items are incomplete is rejected until you finish rows or run **`coddy_todo_plan_archive`**; replacing when every row is **`completed`** moves the prior `active.md` into **`todos/archive/`** (`todo-\u003cnanos\u003e.md`). **`coddy_todo_plan_archive`** finishes open rows to **`completed`**, writes **`todos/archive/plan_\u003cunix_seconds\u003e.md`**, then clears the session plan when persistence is on.\n\nWhen the persisted plan is **non-empty**, the agent injects **`### Current todo checklist`** plus rendered markdown checklist lines into the system prompt template (embedded defaults, or files under **`prompts.dir`** using **`prompts.agent_prompt`** and **`prompts.plan_prompt`**, which default to **`agent.md`** and **`plan.md`**) via `{{if .TodoList}}` … `{{end}}`. That block is omitted when there is nothing to track. Before **each** LLM call inside one **`session/prompt`** turn, Coddy refreshes that system message so a todo list created or updated earlier in the same ReAct episode stays visible immediately.\n\n## Development\n\n```bash\n# Run tests\ngo test ./...\nmake test\n\n# Example harnesses (see examples/README.md): ./examples/build_coddy.sh \u0026\u0026 ./examples/test_acp.sh \u0026\u0026 ./examples/test_httpserver.sh\n\n# Full-featured local binary (HTTP + UI + scheduler), same defaults as Docker\nmake build TAGS=\"http ui scheduler memory\"\n\n./build/coddy -v    # same as --version\n\n# Run with debug logging (ACP mode); optional --log-output, --log-file, --log-format\ncoddy acp --log-level debug\n\n# Single-line sanity check only (responses may omit JSON-RPC \"result\" for nil payloads; prefer examples/acp/acp_e2e_todo.py)\necho '{\"jsonrpc\":\"2.0\",\"id\":0,\"method\":\"initialize\",\"params\":{\"protocolVersion\":1,\"clientCapabilities\":{}}}' | coddy acp\n```\n\n## License\n\nThis project is licensed under the MIT License, see the [LICENSE](LICENSE) file in the repository root for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoddy-project%2Fcoddy-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoddy-project%2Fcoddy-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoddy-project%2Fcoddy-agent/lists"}