한 줄 요약: aidreamy/morpheus(옛 이름 Cosh, 저장소 co-sh)는 Rust로 처음부터 짠 터미널 코딩 에이전트입니다. 그런데 스스로를 “기존 에이전트를 대체하려는 게 아니다”라고 소개합니다. 진짜 노리는 자리는 그 위의 오케스트레이션 층이에요. Claude·Codex·Gemini·OpenCode 같은 남의 하네스를 ACP(Agent Client Protocol)로 띄워 한 TUI의 분할 창에 앉히고, 메인 에이전트가 공유 작업 보드로 일을 나눠 주고 보고를 거둡니다. 이 글은 최신 릴리스 v0.3.0(2026-11-17 01:55 KST)과 main 브랜치(cf837a38, 2026-11-21 10:02 KST) 코드를 기준으로 구조를 뜯어봅니다. 이어서 API 키 없이 OpenAI 호환 목(mock) 서버를 붙여 박스에서 자연 종료 게이트·위험 명령 차단·파일 경계를 직접 찔러 본 결과를 정리합니다. 이번에도 문서와 실제 동작이 어긋나는 지점이 나왔습니다. 하나는 지금 README 설치 명령이 실패한다는 것, 다른 하나는 setup.json 훅이 실행되지 않는다는 것입니다.

1. 한눈에 보기
| 항목 | 내용 (2026-11-21 KST 확인) |
|---|---|
| 저장소 | github.com/aidreamy/morpheus. 옛 경로 DiegoZaluski/co-sh, aidreamy/co-sh는 리다이렉트됨. 저작권자 Diego Zaluski |
| 정체 | “general-purpose coding agent for the terminal”: 개발 도구에 더해, GUI 앱을 다루는 computer tools와 외부 에이전트 조율 기능을 갖춤 |
| 릴리스 | 최신 태그 v0.3.0(바이너리 이름은 아직 cosh). CHANGELOG에는 리네임을 담은 1.0.0(2026-11-18)이 적혀 있지만 태그·릴리스는 아직 없음. v0.1.0 태그(2026-10-02 KST 커밋)부터 v0.3.0까지 약 7주에 태그 9개 |
| 언어·빌드 | Rust 2024 에디션, Ratatui TUI. 6개 크레이트 워크스페이스. 박스 집계 *.rs 약 32.7만 줄(테스트 포함), 커밋 1,332개 |
| 라이선스 | 앱 본체 GPL-3.0-only, 라이브러리 크레이트 6종은 Apache-2.0 (이중 구조) |
| 배포 | Linux x64·macOS(arm64/x64)·Windows x64 바이너리. slim(기본)과 로컬 RAG가 들어간 slim-embed(Linux·Windows만) 변형 |
| 규모·관심도 | 스타 15. 2026-06-01 생성. 해커뉴스 “Show HN: Cosh – An open-source AI agent orchestrator”(2026-11-10 21:05 KST, 10포인트·댓글 4개) |
| 성숙도 신호 | README에 “Tested on Linux and Windows. macOS has not been tested yet”. WhatsApp 연동은 “not recommended for use yet” |
2. 왜 지금 이 저장소인가
출발점은 last30days 랭킹입니다. ‘GitHub AI open source’ 쿼리에서 이 저장소의 Show HN 글이 14위에 올랐습니다. 그보다 위에 있던 후보는 모두 걸렀어요. Mastra Factory·AgentRun·GitHub Replica·Octomind·Agav는 최근 2주 안에 이미 다룬 주제였고, 나머지는 단일 저장소가 아닌 목록 기사·토픽 페이지였거나 날짜가 없는 검색 결과였습니다. ‘AI agent repo’ 쿼리 쪽은 상위가 항공사 정책, KPMG 실험처럼 뉴스 위주였고, 저장소 후보는 이미 다룬 db-branch뿐이었습니다. 오늘 GitHub Trending에는 없습니다. 스타 15개짜리 작은 프로젝트예요.
그래도 고른 이유가 있습니다. 지금 코딩 에이전트 시장은 “어느 하네스가 최고냐”에서 “여러 하네스를 어떻게 같이 부리냐”로 질문이 옮겨 가는 중입니다. 앞서 다룬 Octomind·Agav가 단일 하네스를 깎는 쪽이었다면, Morpheus는 ACP라는 공용 규격 위에 조율 층을 얹습니다. 게다가 저장소가 이상할 만큼 문서화가 잘돼 있습니다. 왜 그렇게 고쳤는지를 코드 줄 번호, 다른 프로젝트 PR·이슈 번호와 함께 남겨 둬서, 하네스 설계를 공부하기에 좋은 교재예요. 다만 지금은 리네임 과도기(cosh → morpheus)라 문서와 배포물이 서로 어긋나 있습니다. 실무자라면 이 점을 먼저 알아야 합니다.
3. 구조: 루프 하나, 조율 층 하나, 떼어 쓰는 크레이트 여섯

코드를 열면 경계가 분명합니다. harness는 “에이전트 하나가 한 턴을 돈다”만 책임지고, coordinator는 “누가 언제 어떤 도구로 도는지, 턴이 어떻게 끝났다고 분류할지”를 맡습니다. 모듈 주석에는 import 방향 규칙이 아예 계약처럼 적혀 있어요. 루프는 자신을 조립하고 구동하는 층에 의존하면 안 된다는 원칙입니다.
| 층 | 위치 | 책임 | 설계 포인트 |
|---|---|---|---|
| TUI(바이너리) | src/tui |
세션 화면, /agents 분할 창, 설정 라우터 |
모든 층에 의존할 수 있는 유일한 층 |
| 조율 | src/coordinator |
패널 도구 정책, 턴 입력 합성, 실효 cwd(워크트리), 종료 분류 | tui를 import하지 않음. 미래 GUI가 같은 라이브러리를 쓰도록 분리 |
| 조립 | src/assembly |
하네스 인스턴스 구성(모드·도구·MCP·LSP) | TUI·WhatsApp이 같은 조립 경로를 공유 |
| 하네스 | src/harness |
에이전트 루프, 컨텍스트, 압축, 가드레일, 서브에이전트 | agent_loop.rs 2,613줄, 반복 상한 MAX_ITERATIONS 100 |
| 세션 | src/session |
JSONL 저장, 분기(Fork)·되돌리기(Revert)·/undo |
“덧붙이기만 한다”. 기존 바이트를 고치지 않음 |
| 라이브러리 | crates/* |
도구·SDK·TUI 위젯·회상·WhatsApp·ONNX 판정 | Apache-2.0로 따로 배포. 앱(GPL)과 분리해 재사용 가능 |
크레이트 분리는 마케팅 문구가 아닙니다. morpheus-tools(약 4.9만 줄)에 bash·fs·find·web·plan·skills·computer 도구가 통째로 들어 있고, morpheus-sdk(약 3.1만 줄)는 패치 엔진·도구 호출 파싱·LSP 클라이언트·tree-sitter AST를 담습니다. 앱은 GPL이지만 이 크레이트들은 Apache-2.0이에요. 자기 하네스에 도구 계층만 떼어 넣고 싶은 팀에게는 이쪽이 더 쓸모 있을 수 있습니다.
4. 핵심 기능 ①: ACP로 남의 에이전트를 창 하나에 앉히기
/agents 모드에서는 외부 에이전트가 분할 창(pane)마다 하나씩 뜹니다. 각 창은 자기 세션·모델·(선택) git 워크트리를 따로 갖고, 메인 에이전트가 일을 나눠 주고 보고를 거둡니다. 연결 방식은 예전처럼 CLI 출력을 긁는 게 아니라 ACP입니다. 하네스를 ACP 서버 모드로 띄우고, JSON-RPC over stdio로 initialize → (authenticate) → session/new → session/prompt를 진행하며, session/update 스트림을 실시간으로 받습니다. 문서에 따르면 예전의 에이전트별 input_flag 표는 “CLI가 업데이트될 때마다 깨져서” 버렸고, ACP를 지원하지 않는 cursor·aider·interpreter는 목록에서 뺐습니다.
| 이름 | ACP 실행 방식(문서 기준) | 비고 |
|---|---|---|
| gemini | gemini --experimental-acp |
실험 플래그 |
| goose | goose acp |
인증 메서드를 광고하면 첫 번째 것으로 인증 |
| opencode / kilo | opencode acp / kilo acp |
kilo는 ACP 기본 모델이 유료 등급이라 모델 지정 필요 사례를 문서화 |
| cline / devin | cline --acp / devin acp |
네이티브 ACP |
| claude | npx -y @agentclientprotocol/claude-agent-acp@latest |
네이티브 아님. 공식 어댑터 경유(npx 필요) |
| codex | npx -y @agentclientprotocol/codex-acp@latest |
상동 |
| copilot / qwen | 도구 스키마 enum에 존재(v0.3.0 실측) | 문서 표에는 아직 없음 |
v0.3.0에서 들어온 공유 작업 보드가 조율의 중심입니다. 코디네이터가 설명·의존성을 붙여 작업을 만들고, 창들이 그것을 claim합니다. 의존 작업이 끝나지 않은 작업은 blocked 상태라 claim할 수 없어요. 창은 자기가 가진 작업의 상태와 산출물만 바꿀 수 있고, 담당자 재배정과 전체 목록 조회는 코디네이터만 합니다. 코디네이터 컨텍스트에는 관련도 높은 작업 5개만 보입니다. 창마다 사용자 큐가 따로 있어서, 사람이 넣은 요청을 에이전트들의 RPC 큐보다 먼저 처리합니다.
실무에서 짚을 점: 문서에 따르면 ACP 턴 도중 하네스가 보내는 session/request_permission 요청은 자동 승인(첫 번째 옵션, YOLO 방식)됩니다. 헤드리스 호출이 멈추지 않게 하려는 설계예요. 결국 외부 에이전트 창의 안전은 그 에이전트 자신의 권한 설정, 그리고 창을 워크트리에 묶는 것에 달려 있습니다. 메인 창의 승인 대화상자가 그 창까지 지켜 주지는 않습니다.
모드 다섯 가지와 패널 정책
| 모드 | 동작 | 언제 |
|---|---|---|
| Build(기본) | 전체 도구. 권한이 필요한 도구는 승인 대화상자를 띄움 | 일반 개발 |
| Ask | 도구 스키마를 걸러 낸 질의 위주 모드. MCP 도구 디스패치 제외 | 코드 설명·탐색 |
| Yolo | 승인 없이 실행 | 격리된 워크트리·컨테이너 안에서만 권장 |
| Command | 입력을 그대로 bash로 보냄. LLM 호출 없음. 기록은 남지만 모델에게는 숨김 | TUI를 터미널처럼 쓸 때 |
| Manager | 파일 쓰기 도구 4종(fs_write·fs_edit·fs_edit_lines·fs_ast_edit)을 숨기고, bash에서도 리다이렉트·rm/cp·sed -i·인라인 인터프리터를 차단 |
계획·위임·관찰만 하는 조율자 |
coordinator/policy.rs의 주석은 흥미로운 버그 수정 기록입니다. 예전엔 창 턴마다 Manager보다 더 넓은 금지 목록을 덮어씌워서, 정작 제품이 비용과 컨텍스트를 통제하는 morpheus 자체 창만 구현을 못 하는 역설이 있었다고 합니다. 지금 창은 사용자의 모드를 그대로 쓰고, 헤드리스라서 빠지는 것만 뺍니다. 사람에게 묻는 ask_questions, 포커스가 보장되지 않는 computer_act·computer_control, 보고가 곧 산출물이라 의미가 없는 stop_agent_loop가 그렇습니다.
5. 핵심 기능 ②: “응답이 끝났다 ≠ 일이 끝났다”, 자연 종료 게이트
이 저장소에서 가장 공들인 문서는 docs/harness-natural-stop-gate.md입니다. 출발점은 에이전트가 일하다 말고 조용히 멈추는 문제였습니다. 원인 분석이 정확해요. finish_reason: "stop"이나 end_turn은 응답이 끝났다는 신호지 작업이 끝났다는 신호가 아닌데, 게이트가 이를 작업 완료로 받아들였다는 겁니다. 문서는 같은 문제를 겪은 opencode PR #14973, Codex 이슈 #5264·PR #7923을 근거로 듭니다.
| 멈춤 유형 | 증상 | Morpheus의 처리 | 이유 |
|---|---|---|---|
| 추론만 있는 스트림 | thinking/reasoning만 흐르고 본문 0토큰, finish=stop | 추론 원문을 한 턴만 조향 입력으로 되돌려 주고 계속 | 다시 추론하면 토큰 낭비에 같은 멈춤이 반복될 위험. Anthropic 서명 thinking 블록은 위조할 수 없어서 컨텍스트 항목이 아닌 조향 텍스트로 전달 |
| 빈 응답 | 토큰도 추론도 없음 | 한 번 재요청 | 공급자 일시 오류 흡수 |
| 도구 뒤 상태 문장 | “이제 테스트를 돌리겠습니다.”에서 멈춤 | 도구 디스패치 뒤 붙이던 “Please continue with your response…” 사용자 턴을 삭제 | tool 결과로 끝나는 꼬리 자체가 표준 계속 신호. 가짜 사용자 턴은 “응답”을 요구해 멈춤을 부르고, 접두 캐시도 깸 |
| 잘린 스트림 | 전송은 정상 종료, 내용은 JSON 중간에서 끊김 | last_stream_unfinished면 “잘렸다” 분기로 보냄 |
finish 프레임만 믿으면 안 됨 |
| 과잉 거부 방지 | 계속 멈추려는 모델 | 조용한 거부 예산 3회. 전체 반복 상한 100과 별도 | 무한 루프(opencode #11153) 반대쪽 실패 방지 |
박스에서 목 서버로 이 동작을 그대로 재현했습니다. 목 서버는 요청마다 미리 짠 응답을 돌려줍니다. 1번은 빈 스트림, 2번은 추론만, 3번은 bash_run 호출, 4번은 완료 보고입니다. 하네스가 실제로 보낸 요청을 가로채 보니 문서와 정확히 일치했습니다.

로그(/tmp/cosh/log/laya.log)에도 natural-stop gate: reasoning-only stream (finish reason stop) — continuing, reasoning promoted for one turn (59 bytes)가 남았습니다. 4번 요청의 메시지 배열은 system, user, assistant(tool_calls), tool 넷뿐이었어요. 1~3번에 주입한 문장이 기록되지 않았다는 뜻이고, 조향은 한 회차만 산다는 설계가 지켜진 것입니다.
문서와 코드가 갈라진 곳 하나. 게이트 문서의 Fix 3은 “TODO 계획에 열린 항목이 있으면 멈춤을 거부한다”라고 설명합니다. 그런데 현재 코드(harness/core/guards.rs)는 다릅니다. 메인 채팅 루프는 보고 의무가 없으므로 다시 돌지 않고, 보고 의무가 있는 서브에이전트·/agents 창만 이어서 돕니다. 메인 쪽은 대신 TUI가 루프 종료 뒤 “깨우기”(wake_main_agent_if_pending_todos)로 새 턴을 하나 엽니다. 그 문구도 “열린 항목이 있다고 꼭 계속하라는 뜻은 아니다, 맥락으로 판단하라”로 한결 부드러워졌어요. 박스에서 계획 도구로 TODO 2개를 만든 뒤 상태 문장으로 멈추게 했더니, 깨우기는 정확히 1회 일어났습니다. 같은 목록으로는 다시 깨우지 않습니다. 다만 v0.3.0에서는 깨우기 요청에 이전 대화가 실리지 않고 시스템 프롬프트와 노트 2개 메시지만 갔습니다(로그 items=1, prefix cache probe: seeded). 목 서버 기준 관찰이라 의도된 동작인지 결함인지는 단정하지 않겠습니다. 다만 “맥락으로 판단하라”는 지시와 맥락 없는 요청은 서로 어울리지 않습니다.
6. 컨텍스트·캐시: 접두는 건드리지 않는다
압축 설계에는 원칙이 하나 일관되게 흐릅니다. 정확한 접두(exact prefix)를 지켜 프롬프트 캐시를 살린다는 것입니다. 세션 JSONL이 유일한 원본이고, 압축 체크포인트는 원본을 바꾸지 않고 덧붙이는 요약입니다. 도구 결과 가리기(mask_tool_result)는 모델이 명시적으로 요청할 때만, 그것도 꼬리에서만 일어납니다. 중간 위치 k를 고치면 그 뒤 모든 캐시가 무효가 되지만, 꼬리를 고치면 캐시에 영향이 없기 때문입니다. 하네스는 요청마다 prefix cache probe 로그로 접두가 깨졌는지 스스로 점검합니다(verdict=append / tail_change, full_breaks=0).

대신 접두 자체가 무겁습니다. 첫 요청을 가로채 재 보니 시스템 프롬프트 27,252바이트, 도구 28개 스키마가 압축 JSON 기준 약 55KB였습니다. 그중 약 50%(27.6KB)가 데스크톱 제어용 computer_* 7종이에요. 캐시가 잘 맞으면 비용은 줄지만, 캐시 쓰기 비용과 컨텍스트 창 점유는 남습니다. GUI가 없는 서버나 CI에서 쓴다면 /tools로 computer 도구를 끄는 것이 첫 튜닝 포인트입니다.
| 설정(setup.json) | 기본값 | 의미 |
|---|---|---|
cache.anthropic_ttl_min |
0 | 0이면 5분 캐시, 5 초과면 1시간 캐시(쓰기 비용 상승) |
cache.openai_retention_min |
0 | 0 초과면 24시간 보존 선택 |
routing.fallbacks |
내장 체인 | 비었으면 nvidia → openrouter(deepseek-v4-pro) → groq(gpt-oss-120b) → charm 순 |
routing.summarization_models |
[] | 압축 요약 전용 모델 체인. 비우면 현재 모델 사용 |
tools.tool_call_mode |
native | inline이면 JSON 텍스트를 Morpheus가 파싱(도구 호출이 약한 로컬 모델용) |
tools.disabled |
[] | 모델에게 숨길 도구 이름 |
7. 핵심 기능 ③: 접근성 트리로 GUI를 다루는 컴퓨터 도구
README가 차별점으로 내세우는 두 번째 축입니다. 화면을 스크린숏으로만 보는 대신 앱의 접근성 트리를 구조화된 개요로 읽고, 필요할 때만 이미지로 넘어갑니다. 이미지를 덜 처리하니 토큰도 덜 듭니다. 모든 도구가 button[name='Export'], list_item:nth(3) 같은 CSS 비슷한 셀렉터 문법을 공유해서, 스냅숏 한 줄을 그대로 행동 호출로 옮길 수 있습니다.
| 단계 | 도구 | 역할 |
|---|---|---|
| 보기 | computer_snapshot / computer_screenshot |
접근성 트리(구조화된 사실) / 픽셀(사람이 보는 화면). 스크린숏은 요소에 상자를 그리고 셀렉터 범례를 붙일 수 있음 |
| 찾기 | computer_apps / computer_windows |
실행 중 앱, 포커스 요소, 창 목록·조작 |
| 행동 | computer_act |
요소의 의미 행동(press·toggle·set_value). 보이고 활성화될 때까지 자동 대기 |
| 입력 | computer_control |
실제 OS 클릭·타이핑. 키보드 포커스를 옮기는 확실한 방법 |
| 기다리기 | computer_wait |
상태·값("100%")·이벤트(window_opened)가 올 때까지 블록. 시간 초과 시 진단을 돌려줌 |
“보기 → 찾기 → 행동 → 기다리기” 루프를 도구 설계 자체에 박아 둔 게 핵심이에요. 폴링 반복으로 토큰을 태우는 대신 wait로 블록합니다. 오류 메시지도 “다음에 할 일”을 알려 주도록 설계했다고 문서에 적혀 있습니다. 박스는 헤드리스 서버라 GUI 시나리오는 돌리지 않았습니다. 이 부분은 문서 기준 설명입니다.
8. 안전장치: 무엇이 지켜 주고, 무엇이 안 지켜 주나
| 장치 | 범위 | 박스 확인 | 한계 |
|---|---|---|---|
| bash 위험 패턴 | rm -rf /…, sudo rm, fork bomb, mkfs·dd of=/dev/, /etc/passwd 쓰기, curl|sh, shutdown, nc -e 등 정규식 |
curl … | sh, rm -rf /tmp/x 차단. rm -rf ./junk는 허용 |
문서 스스로 “샌드박스가 아니라 사고 방지 철사줄”이라고 명시. 두 단계로 나눈 curl -o x && bash x는 못 잡음 |
| 절대 경로 명령 금지 | 명령이 절대 경로면 거부 | 도구 설명에 명시 | 우회는 쉬움 |
| fs 경로 가드 | fs_* 도구는 프로젝트 루트 밖 거부 | /etc/hostname 읽기 거부 |
bash는 이 가드 밖. cat /etc/hostname은 그냥 됨 |
| 해시 앵커 편집 | 기존 파일 덮어쓰기는 fs_read가 준 file_hash 필요 |
미열람 덮어쓰기 거부 메시지 확인 | 모델 실수 방지용이지 보안 경계는 아님 |
| 교정 이력 | 차단된 패턴을 “Correction History”로 다음 요청에 주입 | 차단 2건이 누적 표시됨 | 꼬리 주입이라 캐시엔 중립 |
| PreToolUse/PostToolUse 훅 | 문서상 도구 호출 전후 셸 명령, exit 2=거부, 49=턴 중단 | 실행 흔적 없음(아래) | 현재 릴리스에서 정책 강제 수단으로 쓸 수 없음 |
훅이 돌지 않는다
문서(docs/usage/hooks.md)대로 setup.json에 PreToolUse 훅 두 개를 넣었습니다. 하나는 문서 예시처럼 환경 변수를 보고, 하나는 stdin JSON에서 curl을 찾아 exit 2로 거부하는 스크립트입니다. 그 상태로 목 서버가 bash_run으로 curl을 시켰더니, 훅 로그 파일은 생기지 않았고 curl은 그대로 실행돼 notes.html이 만들어졌습니다. 원인은 코드에 있었습니다. 훅 실행기 HookRunner는 Harness::with_hooks()로만 만들어지는데, v0.3.0과 main(cf837a38) 모두 이 메서드를 호출하는 곳이 정의 말고는 없습니다. 설정 파싱, TUI 편집 화면, 단위 테스트는 다 있는데 정작 조립 경로에 배선이 빠진 상태예요. 덤으로 문서 예시 훅도 $MORPHEUS_TOOL_NAME(도구 이름, 예: bash_run)에서 rm -rf를 찾고 있어서, 배선이 고쳐지더라도 그대로는 아무것도 막지 못합니다. 명령 내용은 stdin JSON의 tool_input에 있습니다.
9. 설치와 실행: 지금은 README 원라이너가 안 된다
main의 download.sh는 이미 새 이름 morpheus-v0.3.0-linux-x64-slim.tar.gz를 찾습니다. 그런데 실제 최신 릴리스(v0.3.0)의 자산 이름은 아직 cosh-v0.3.0-…입니다. 박스에서 README 명령을 그대로 돌리면 404로 끝납니다(exit 1). 1.0.0이 정식 릴리스되기 전까지는 직접 받는 쪽이 확실합니다.
# 1) 릴리스 자산 직접 받기 + 체크섬 확인 (Linux x64)
V=v0.3.0
curl -fLO https://github.com/aidreamy/morpheus/releases/download/$V/cosh-$V-linux-x64-slim.tar.gz
curl -fLO https://github.com/aidreamy/morpheus/releases/download/$V/cosh-$V-linux-x64-slim.tar.gz.sha256
sha256sum cosh-$V-linux-x64-slim.tar.gz; cat cosh-$V-linux-x64-slim.tar.gz.sha256
tar xzf cosh-$V-linux-x64-slim.tar.gz # cosh, cosh-uninstall
# 2) 텔레메트리는 기본 ON(opt-out). 먼저 끄고 시작
export COSH_TELEMETRY=off # 1.0.0부터는 MORPHEUS_TELEMETRY
./cosh --version && ./cosh paths
# 3) 실행 (프로젝트 디렉터리에서)
./cosh # 새 세션
./cosh -c # 이 디렉터리의 최근 세션 이어서
OpenAI 호환 엔드포인트(vLLM·LiteLLM·사내 게이트웨이·로컬 서버)는 custom_providers로 붙입니다. 키는 setup.json에 넣지 않고 <이름 대문자>_API_KEY 환경 변수나 OS 키링에서 읽어요. 박스 실측에 쓴 설정은 아래와 같습니다.
// ~/.config/cosh/setup.json (1.0.0부터 ~/.config/morpheus/)
{
"custom_providers": [
{"name": "mockai", "base_url": "http://127.0.0.1:18080/v1", "family": "open-ai-compatible"}
],
"model": {"provider": "mockai", "model": "mock-coder", "reasoning": null},
"mode": {"mode": "build"},
"telemetry": false,
"lsp": false,
"tools": {"disabled": ["computer_act", "computer_control", "computer_screenshot"]}
}
# 실행: MOCKAI_API_KEY=... ./cosh
| 환경 변수(v0.3.0 / 1.0.0) | 용도 |
|---|---|
COSH_CONFIG_DIR / MORPHEUS_CONFIG_DIR |
setup.json 위치 |
COSH_DATA_DIR / MORPHEUS_DATA_DIR |
세션·캐시 저장 위치 |
COSH_TELEMETRY / MORPHEUS_TELEMETRY |
off로 텔레메트리 끄기(CI 감지 시 자동 off) |
*_PROVIDER, *_MODEL, *_REASONING |
저장된 선택이 없을 때 초기 모델 |
*_LSP |
off·0·false로 LSP 끄기 |
MORPHEUS_VARIANT |
설치 스크립트 변형(slim / slim-embed) |
업데이트는 morpheus update [version] [--yes] 하나로 통일됐습니다. Windows에서 실행 중인 exe 잠금 문제 때문에, 이제 설치기를 띄운 뒤 재실행 없이 종료합니다. 리네임 이후 cosh update가 새 자산 이름을 어떻게 따라가는지는 1.0.0 릴리스가 나와야 확인할 수 있습니다.
10. 박스 실측: 무엇을, 어떻게 확인했나
환경은 Debian 13 x86-64 박스, 격리한 HOME, COSH_TELEMETRY=off입니다. 모델 대신 파이썬으로 만든 OpenAI 호환 목 서버를 127.0.0.1:18080에 띄웠어요. 목 서버는 /v1/models와 스트리밍 /v1/chat/completions에 응답하고, 요청 본문을 모두 기록합니다. TUI는 tmux 안에서 실제로 띄워 프롬프트를 입력했습니다. 시나리오는 세 가지였습니다. ① 게이트(빈 응답·추론만·도구·완료), ② TODO와 훅, ③ 가드(위험 bash 2건, 상대 경로 삭제, 루트 밖 읽기, 미열람 덮어쓰기).

| 관찰 | 값 |
|---|---|
| 릴리스 자산 | tar.gz 52.6MB → cosh 실행 파일 229MB(+ cosh-uninstall 12.9MB). 동적 의존은 libc·libm·libgcc_s·libxkbcommon 정도 |
| 첫 요청 구성 | model, messages, stream, stream_options, tools. 도구 28개, 시스템 27,252B |
| 보조 요청 | 도구 없는 비스트리밍 요청 1건(시스템 582B). 세션 제목 생성용으로 보임 |
| 컨텍스트 창 탐지 | 목 모델이라 실패 → 기본 예산 100,000토큰으로 표시 |
| 연결 실패 시 | 요청 오류가 나면 간격을 늘려 가며 최대 3회 재시도(첫 두 간격 약 4초·7초 관찰) |
| 세션 저장소 경고 | ctx_ids mapping skipped … 4 item groups vs 3 display messages. 되돌리기·분기에 쓰는 컨텍스트–화면 매핑을 건너뛰었다는 경고. 도구를 쓴 턴에서 반복 관찰 |
| Yolo 모드 표시 | 입력창 하단에 모드·공급자·모델 표시, Tab으로 모드 순환 |

11. 비슷한 도구와 비교
같은 “여러 에이전트를 함께 부린다”라도 층이 다릅니다. Morpheus는 스스로도 하네스이면서 남의 하네스를 ACP로 부르는 조율자라는 점에서 독특합니다.
| 도구 | 층 | 멀티 에이전트 방식 | 강점 | Morpheus 대비 |
|---|---|---|---|---|
| Morpheus | 하네스 + 조율 | ACP 분할 창, 공유 작업 보드, 창별 워크트리, Manager 모드 | 이기종 에이전트를 한 화면에 · 접근성 트리 GUI 도구 · 크레이트 재사용 | – |
| Claude Code | 단일 하네스 | 자체 서브에이전트 | 모델 통합도, 훅·권한 생태계 성숙 | Morpheus는 Claude Code를 창 하나로 부를 수 있음(어댑터 경유) |
| OpenAI Codex CLI | 단일 하네스(Rust) | 자체 루프 중심 | 접두 캐시를 지키는 루프 설계, 샌드박스 | Morpheus 게이트 문서가 Codex 루프를 직접 참고 |
| OpenCode | 단일 하네스(TUI) | 에이전트·서브에이전트 | TUI UX, 다수 공급자 | Morpheus TUI가 “OpenCode UX에서 영감”이라고 밝힘. ACP로 창에 띄울 수 있음 |
| Goose | 단일 하네스(Rust) | 레시피·확장 | MCP 확장 생태계 | goose acp로 Morpheus 창에 들어감 |
| Octomind · Agav(앞선 글) | 단일 하네스 | – | 토큰 효율·가드레일·검증 강제 | “하네스를 깎는” 쪽. Morpheus는 “하네스를 묶는” 쪽 |
| 설계 선택 | Morpheus | 트레이드오프 |
|---|---|---|
| 외부 에이전트 연결 | ACP만 지원(CLI 출력 긁기 폐기) | 안정적 계약 ↔ ACP 미지원 도구(aider 등)는 못 씀 |
| 외부 창 권한 | ACP 권한 요청 자동 승인 | 헤드리스 진행 ↔ 메인 창 승인 정책이 외부 창엔 안 미침 |
| 종료 판단 | 결정적 게이트(+ 선택 ONNX 판정 모델 Laya) | 모델 없이도 동작 ↔ 배포 slim 바이너리엔 ONNX 판정이 빠져 있음 |
| 도구 세트 | computer 도구 기본 노출 | GUI 자동화 가능 ↔ 헤드리스에선 스키마 절반이 무게만 차지 |
| 라이선스 | 앱 GPL-3.0 / 크레이트 Apache-2.0 | 앱 포크·재배포는 GPL 의무 ↔ 도구 계층만 가져다 쓰기는 자유로움 |
12. 한계와 주의점
| 항목 | 내용 | 대응 |
|---|---|---|
| 리네임 과도기 | 코드·문서는 morpheus, 최신 릴리스는 cosh. README 설치 명령 404 | 자산 직접 다운로드 + sha256 확인, 1.0.0 릴리스 후 재검토 |
| 훅 미배선 | 설정·UI는 있으나 실행되지 않음(v0.3.0, main cf837a38) | 정책 강제는 OS 샌드박스·컨테이너·워크트리로. 훅에 기대지 말 것 |
| 텔레메트리 기본 ON | 세션 종료 시 집계 요약을 Supabase 함수 엔드포인트로 전송. 문서상 대화·코드·경로·키는 미수집 | 사내 사용 전 COSH_TELEMETRY=off 또는 설정에서 끄기 |
| bash는 샌드박스 아님 | 정규식 철사줄뿐. fs 경로 가드도 bash엔 미적용 | Yolo·Manager 위임 작업은 컨테이너/VM 안에서 |
| ACP 자동 승인 | 외부 에이전트 창의 권한 요청을 첫 옵션으로 승인 | 각 에이전트 자체 권한 설정을 보수적으로, 창은 워크트리에 고정 |
| 성숙도 | 스타 15, 사실상 1인 주도, macOS 미검증, WhatsApp 실험 단계 | 팀 표준 도구보다는 개인·소규모 실험용 |
| 무거운 바이너리 | slim도 229MB | CI 이미지 캐시 고려 |
| TODO 깨우기 | v0.3.0 박스에서 이전 대화 없이 요청이 나감(목 서버 관찰) | 열린 계획이 많은 긴 작업은 결과를 사람이 확인 |
13. 도입 판단 체크리스트
| 상황 | 판단 |
|---|---|
| 이미 Claude Code·Codex·Gemini CLI를 섞어 쓰며 창을 오가는 게 피곤하다 | 시도할 가치 있음. ACP 창 + 작업 보드가 정확히 이 문제를 겨냥 |
| 훅으로 사내 정책(명령 차단·감사 로그)을 강제해야 한다 | 보류. 현재 훅이 동작하지 않음 |
| 헤드리스 CI에서 무인 에이전트를 돌리고 싶다 | v0.3.0 CLI 도움말 기준 비대화형 실행 명령이 없음(TUI·WhatsApp 중심). 다른 도구가 적합 |
| GUI 앱 자동화(데스크톱 QA 등)를 에이전트에 맡기고 싶다 | 접근성 트리 기반 도구가 흥미로운 선택지. 단 macOS 미검증 |
| 자체 하네스를 만드는 중이다 | Apache-2.0 크레이트(morpheus-tools·morpheus-sdk)와 게이트·압축 문서를 설계 참고서로 강력 추천 |
마무리: “갈아타기”에서 “같이 부리기”로
Morpheus는 아직 작고 거칠어요. 설치 명령이 깨져 있고, 훅은 배선이 빠졌고, 이름도 막 바뀌는 중입니다. 그런데도 볼 만한 이유는 방향이 맞기 때문입니다. 모델과 하네스가 몇 주마다 뒤집히는 지금, 하나에 올인하는 대신 ACP라는 공용 플러그 위에 조율 층을 얹는 접근은 갈아타기 비용을 크게 줄여 줍니다. 그리고 “finish_reason은 응답의 끝이지 작업의 끝이 아니다” 같은 문장을 코드 줄 번호와 함께 남겨 두는 저장소는 흔하지 않아요. 당장 팀에 들일 도구라기보다는, 다음 하네스를 고르거나 직접 만들 때 옆에 펴 둘 교재로 먼저 권합니다. 1.0.0 정식 릴리스에서 훅 배선과 설치 경로가 바로잡히면 다시 점검해 보겠습니다.