coddy-agent

Desktop (1920×1080)	Mobile (390×844)
Start screen	Mobile start

Coddy는 **하우징(harness)**입니다. 동일한 에이전트 코어는 콘솔 TUI를 통해 터미널에서, Agent Client Protocol을 통해 편집기에서, HTTP를 통해 브라우저나 모든 OpenAI 클라이언트에서, 메시지 게이트웨이를 통해 Telegram에서, 스케줄러를 통해 cron에서 접근할 수 있습니다. 모든 표면(surface)은 ~/.coddy 아래의 세션을 공유하므로, 채팅에서 시작된 대화는 브라우저에서도 실시간으로 활성화되어 어느 쪽에서든 계속 이어갈 수 있습니다. 이는 scratch 및 distroless 이미지로 읽기 전용 루트 파일 시스템에서 실행되며, 런타임이 필요 없고, 단일 노트북부터 컨테이너 플릿까지 모두 구축할 수 있도록 설계되었습니다.

설치 (Install)

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

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

설치 프로그램은 coddy를 PATH에 배치하고, 누락된 경우 릴리스의 config.example.yaml로부터 ~/.coddy/config.yaml을 생성하며, Linux 및 macOS에서는 man 페이지와 셸 자동 완성 기능을 설치합니다. 또한 모든 릴리스는 .deb 및 .rpm 패키지, Homebrew cask, Linux, macOS, Windows 및 Termux를 통한 Android용 아카이브, 그리고 docker compose up -d를 위한 이미지 ghcr.io/coddy-project/coddy-agent도 게시합니다. 이 패키지와 cask는 터미널을 초월하는 콘솔 세션을 위해 tmux를 권장하지만, 설치하지는 않습니다. 각 경로에 대한 자세한 내용은 설치와 Docker에 있으며, 소스에서 빌드하려면 git clone 후 make build TAGS="http ui scheduler memory cli gateway swarm metrics"를 사용하십시오. 소스에서 빌드를 참조하세요.

그런 다음 모델을 지정해 주십시오. ~/.coddy/config.yaml에 제공업체 키(provider key)를 넣거나, OPENAI_API_KEY를 내보내어 기본 설정이 이를 가져가도록 하세요:

providers:
  - name: openai
    type: openai
...

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

coddy-agent

coddy -t는 파일을 확인하고, coddy --dry-run은 해당 파일이 가리키는 것을 테스트합니다. Anthropic, NeuralDeep, ChatGPT는 Codex 백엔드를 통해 로그인하며, 브라우저를 통해 로그인한 Devin 계정(Devin), Ollama, llama.cpp 및 기타 모든 OpenAI 호환 서버가 설정(Configuration)에서 다루어집니다. 모든 환경에서 처음 5분은 빠른 시작(Quickstart)에 있습니다. 업그레이드는 coddy update -y로 진행되며, 이 과정에서 건너뛴 모든 버전의 릴리스 노트가 표시됩니다(Update).

Surfaces (환경)

• 세 가지 작동 모드: 모든 도구를 사용하는 agent 모드, 계획 수립 및 텍스트 파일 처리를 위한 plan 모드, 읽기 전용 리서치에 사용되는 ask 모드가 있으며, 어떤 표면(surface)에서든 전환 가능합니다 (작동 모드).

• 규칙 및 프로젝트 파일: .coddy/rules, .agents/rules, .cursor/rules, .claude/rules, .codex/rules 중 가장 먼저 발견되는 것이 규칙을 담고 있으므로, 다른 에이전트를 위해 미러가 로드되어도 두 번 로드되지 않습니다. 또한, 중첩된 AGENTS.md는 캐시된 시스템 프롬프트를 이동하지 않고 에이전트가 작업할 때 가져와 사용합니다. 사용자 자신의 ~/.coddy/AGENTS.md, ~/.coddy/DESIGN.md, 그리고 ~/.coddy/rules는 모든 워크스페이스에 적용됩니다 (규칙 및 지침).

• 기술(Skills): SKILL.md 패키지는 슬래시 명령어(slash commands)가 됩니다. 바이너리 내부에 6개의 기능이 포함되어 있으며, 첫 실행 시 사용 가능합니다: /rpa-init, /rpa-feat, /rpa-bugfix, /rpa-gen-rules, /configure-coddy 및 /crossreview (외부 코드 에이전트 CLI와 내부 검토자 간의 쿼럼 코드 리뷰) 등이며, skills.sh, skillsbd 레지스트리 또는 모든 저장소에서 추가 설치할 수 있습니다 (기술).

• 하위 에이전트(Subagents): spawn_agent는 자체 컨텍스트, 세션, 도구 및 권한을 가진 자식 에이전트에게 제한된 작업을 위임합니다. 자식 에이전트는 연결이 끊긴 제공자(provider)를 처리할 수 있으며, resume은 처음부터 다시 시작하는 대신 자신의 세션에서 중단된 실행을 계속 진행합니다 (하위 에이전트).

• 세션 목표: /goal <objective>는 에이전트가 작업하는 것을 두 번째 모델에게 맡겨, 에이전트의 주장보다는 도구 결과를 판단하여 목적 달성 여부를 확인하고 읽기 전용 검증자(read-only verifier)가 파일에서 이를 확정할 때까지 작동하게 합니다. 또한, 감시견(watchdog)은 멈추거나 루프를 반복하는 과정을 차단하며, 목표는 웹 UI와 콘솔에 표시됩니다 (세션 목표 및 감독관).

• Feature worktrees: worktree_create는 origin에서 기본 브랜치를 가져와 피처(feature) 작업 트리를 생성하고 활성 세션을 그 안으로 이동시킵니다. 웹 컴포저와 히스토리에는 이 브랜치가 메인 프로젝트 아래에 표시됩니다 (Git worktrees).

• Hooks: 클로드 코드(Claude Code)의 hooks.json 형태를 사용하여 라이프사이클의 모든 지점에서 자신만의 명령을 실행할 수 있으며, 도구 호출을 거부하거나 승인하거나 재작성할 수 있습니다 (Hooks).

• MCP servers: 전역 및 프로젝트 mcp.json 파일 또는 에디터에서 stdio, 스트리밍 HTTP, SSE를 통해 MCP 서버를 지원하며, 체크아웃 시 도착하는 내용에 대한 신뢰 게이트가 있습니다; 이 모든 것이 한 번에 연결되고 콘솔에서 첫 프레임 이후에 사용 가능합니다 (MCP servers).

• Mentions: @는 디스크상의 임의 파일, 라인 범위, 폴더, 다른 세션, 규칙, 서브 에이전트 또는 웹 페이지를 가리키며, 콘솔과 브라우저에서 동일한 퍼지 완성(fuzzy completion) 기능을 제공합니다. 각 항목은 메시지에 이름으로 읽히므로, 프로바이더의 프롬프트 캐시가 유지됩니다 (Mentions).

• Documentation built in: 이 문서는 바이너리 내에 포함되어 배포됩니다 – 웹 UI에서 리더를 통해, 콘솔에서 F1 키로, 셸에서 coddy docs 명령어로 접근할 수 있으며 오프라인 검색이 가능합니다. 또한 에이전트는 자체 coddy_docs_search 및 coddy_docs_read 도구 또는 @coddy:<페이지> 언급을 통해 문서를 조회할 수 있습니다 (Built-in documentation).

• Message queue: 실행 중인 턴(turn)의 다음 단계로 유도하거나, 이미지를 첨부하여 별도의 턴을 대기열에 추가할 수 있습니다. 브라우저와 콘솔에서 세션을 보는 모든 사람이 동일한 대기열을 확인합니다 (Message queue).

• Background tasks: 웹 UI의 Tasks 패널과 콘솔의 /tasks에서 완료될 때 에이전트를 깨우는 분리된 명령 및 서브 에이전트 실행입니다 (Background tasks).

• 프리뷰 서버 (Preview server): 웹 서버에서 실행하여 직접 사용해 볼 수 있습니다. 에이전트가 프로젝트 디렉토리를 무료 로컬호스트 포트로 서비스하고 링크를 제공하므로, python -m http.server 명령어가 필요하지 않습니다 (Preview server).

• 컨텍스트 압축 및 장기 메모리 (Context compaction and long-term memory): /compact 명령어와 임계값에 따른 자동 요약, keep_result를 이용한 결과 제거, 턴(turn)마다 백그라운드에서 실행되는 메모리 서브 에이전트가 노트의 내용을 상기하고 사용자가 보존하라고 요청하는 내용을 저장합니다 (Compaction, Memory).

• 셀프 구성 (Self-configuration): 에이전트는 단계별 config_* 도구를 통해 자체 YAML 파일을 편집하며, 사용자가 커밋을 승인하기 전까지는 아무것도 적용되지 않습니다 (config.yaml reference).

• 모든 환경에서의 세션 (Sessions everywhere): 디스크에 번들링하고, 어떤 표면(surface)에서도 재개할 수 있으며, 메시지 편집 시 히스토리 되감기 기능과 /export를 통해 Markdown, HTML 또는 JSON으로 내보내기 할 수 있습니다 (Sessions, Session export).

• 모든 모델 (Any model): OpenAI, Anthropic, NeuralDeep, Codex를 통한 ChatGPT, Devin 계정의 모델 (Devin), Ollama, llama.cpp, vLLM 및 모든 OpenAI 호환 API와 함께 사용 가능하며, 모델별 추론 수준과 멀티모달 첨부 파일, 그리고 Retry-After를 준수하는 재시도 기능까지 지원합니다 (Configuration).

• 사용량 및 제한 (Usage and limits): 콘솔 푸터와 웹 UI에서 현재 모델의 할당량을 확인할 수 있으며(NeuralDeep, Codex, Devin이 오늘 제공), 한계에 도달한 턴은 리셋을 기다리며 스스로 재개할 수 있습니다 (Console, config.yaml reference).

• 설정 확인(Config check), 드라이 런(dry run) 및 핫 리로드(hot reload): coddy -t는 임베디드 스키마를 사용하여 config.yaml을 검증하며, 파일 위치와 줄 번호(file:line:col) 및 수정 라인을 제공합니다. --dry-run은 시작하기 전에 경로, 프로바이더(providers) 및 모델, 포트, MCP 서버, Telegram 토큰, 원격지(remotes) 및 스웜 참여 여부를 점검하고, 실행 중인 coddy serve는 재시작 없이 편집된 파일을 반영합니다(Configuration, coddy serve).

• 플릿(Fleets): 스웜 릴레이(swarm relay)가 여러 노드를 목록화하고 도달하며, 해당 세션을 하나의 목록에 마운트하고, 링을 가로질러 라우팅하며, 리버스 터널을 통해서만 다이얼 아웃할 수 있는 노드까지 끌어옵니다. --remote는 콘솔, 에디터 또는 브라우저에서 다른 장치에 coddy serve를 구동합니다(Swarm, 원격 모드(Remote mode)).

• 브라우저 내 기능: 7가지 테마, 영어 및 러시아어 지원, 작성기(composer)에서의 @ 언급 및 멀티모달 첨부 파일, 태그와 고정(pins), 아카이브로 그룹화된 폴더별 히스토리, 계획 문서 카드, 작업(Tasks) 패널, 문서 리더, 스케줄러 에디터, 그리고 토폴로지(topology)가 표시되는 스웜 맵을 제공합니다. 이는 앱으로 설치되며, 에이전트가 완료되거나 대기할 때 알림을 보냅니다(Web UI).

• 네트워크에 연결된 상태에서의 보안: 베어러 토큰(bearer token)이 클라이언트의 API를 보호하며, 선택적 비밀번호 로그인 기능이 브라우저를 보호합니다. coddy serve set-password를 사용하거나, ~/.coddy/.env 파일에 CODDY_HTTP_USER / CODDY_HTTP_PASSWORD를 설정하여, 0.0.0.0에서 실행되는 coddy serve가 포트를 발견하는 누구에게나 읽히지 않도록 합니다(Remote mode, 보안 및 신뢰(Security and trust)).

프로젝트의 신뢰성은 MCP 서버, 훅(hooks) 및 서브 에이전트(subagents)에 대한 결정 사항이며, 이들은 레포지토리와 함께 제공됩니다. 체크아웃된 것 중 어떤 것도 사용자가 해당 파일을 승인하기 전까지는 실행되지 않습니다(Security and trust).

문서화 (Documentation)