SeifBenayed/cloclo: 멀티 에이전트 런타임 (Multi-agent runtime)

멀티 에이전트 런타임 (The multi-agent runtime).

Cloclo는 NDJSON을 통해 함께 생각하고, 조정하며, 실행하는 에이전트들을 위한 런타임 (Runtime) 및 CLI입니다. 이것은 또 다른 채팅 UI가 아닙니다. 이것은 기반(Substrate)입니다: AICL 네이티브 에이전트 오케스트레이션 (Agent orchestration), 공유 도구 (Shared tools), 공유 메모리 (Shared memory), 공유 기술 (Shared skills), 13개의 모델 제공업체 (Model providers), 네이티브 의존성 제로 (Zero native dependencies).

에이전트를 구축하고, NDJSON을 통해 연결하며, 작업에 가장 적합한 모델에서 실행되도록 하세요.

Cloclo는 오픈 소스 **멀티 에이전트 런타임 (Multi-agent runtime)**입니다.

Cloclo는 에이전트에게 공통의 실행 환경을 제공합니다:

NDJSON 브릿지 우선 (NDJSON bridge first): 프로그래밍 방식의 제어를 위한 라인 지향 stdin/stdout 전송
AICL 네이티브 (AICL-native): 에이전트가 공유된 에이전트 간 프로토콜(Inter-agent protocol)로 통신 가능
13개의 제공업체 (13 providers): Anthropic, OpenAI, Gemini, Ollama 등에서 동일한 에이전트 시스템 실행
공유 인프라 (Shared infrastructure): 도구 (Tools), 메모리 (Memory), 기술 (Skills), 권한 (Permissions), 훅 (Hooks), 세션 (Sessions)
단일 파일 런타임 (Single-file runtime): 네이티브 의존성 없이 claude-native.mjs로 제공

터미널 UI가 존재하지만, 그것이 아키텍처의 중심은 아닙니다. 중심은 런타임입니다.

Claude Code가 최종 사용자 제품이라면, Cloclo는 그 아래 계층에 더 가깝습니다: 즉, 많은 에이전트가 공존하고, 협업하며, 더 큰 시스템으로 구성될 수 있는 프로그래밍 가능한 환경입니다.

AICL은 **협력적 노동을 위한 에이전트 인터링구아 (Agent Interlingua for Cooperative Labor)**의 약자입니다.

이는 에이전트 간 통신을 위한 Cloclo의 네이티브 프로토콜입니다. AICL은 에이전트에게 소유권 (Ownership), 의도 (Intent), 증거 (Evidence), 신뢰도 (Confidence), 상태 변경 (State changes), 제약 조건 (Constraints), 그리고 핸드오프 (Handoffs)를 위한 압축된 공유 언어를 제공합니다.

핵심 기호 (Core symbols):

ω — 메시지 소유자 (Who owns the message)
ψ — 목표 / 의도 (Goal / intent)
∂ — 변경 사항 (What changed)
◊ — 가설 (Hypothesis)
⊤ / ⊥ — 검증된 참 / 거짓 (Verified true / false)
σ — 신뢰도 (Confidence)
ε — 증거 (Evidence)
λ — 동작 (Actions)
κ — 제약 조건 (Constraints)
→ — 핸드오프 (Handoff)
∇ — 방향 (Direction)

예시:

ω:planner → coder | ψ:fix(auth.null_ref) | ε:src/auth.js:42 | ◊:missing_guard σ:0.9 | λ:patch→test | ∇:ship

내부적으로 Cloclo는 **NDJSON 전송 (NDJSON transport)**을 사용하며, 에이전트 워크플로우에 AICL 프레이밍 (Framing)을 주입할 수 있어 하위 에이전트 (Sub-agents)가 단순한 산문 형태가 아닌 구조화된 결과 (Structured results)를 반환할 수 있습니다.

멀티 에이전트 시스템 (Multi-agent systems)을 구축하고 있다면, AICL은 전송 계층 (Transport) 상위의 네이티브 언어 계층 (Native language layer)입니다.

설치:

npm install -g cloclo

Cloclo를 **NDJSON 브리지 (NDJSON bridge)**로 실행:

cloclo --ndjson

다른 프로세스에서 메시지 전송:

echo '{"type":"message","content":"hello"}' | cloclo --ndjson

최소한의 Node 예제:

import { spawn } from "node:child_process";
const child = spawn("cloclo", ["--ndjson"], { stdio: ["pipe", "pipe", "inherit"] });
child.stdout.on("data", (buf) => {
...

특정 모델/제공자 (Model/Provider)와 함께 실행:

cloclo --ndjson -m opus
cloclo --ndjson -m gpt-5.4
cloclo --ndjson -m gemini-2.5-pro
...

인증 (Auth) 예제:

cloclo --login # Anthropic 구독 / 인증 흐름 (Auth flow)
cloclo --openai-login # OpenAI 구독 / 인증 흐름 (Auth flow)
export GOOGLE_API_KEY=...
...

핵심 아이디어: Cloclo를 사용자가 수동으로 머무르는 REPL이 아니라, 에이전트들이 통신하는 런타임 프로세스 (Runtime process)로 취급하십시오.

Cloclo는 하나의 런타임 계약 (Runtime contract) 뒤에서 **13개의 제공자 (Providers)**를 지원합니다:

제공자 (Provider)	예시 모델 (Example models)
Anthropic	claude-sonnet-4-6 , claude-opus-4-6
...

이것이 중요한 이유:

• 에이전트들은 **기본적으로 제공자 불가지론적 (Provider-agnostic)**입니다 - 모델 라우팅 (Model routing)은 작업, 비용, 속도 또는 능력에 따라 달라질 수 있습니다.
• 동일한 런타임을 사용하여 호스팅된 프런티어 모델 (Frontier models)과 로컬 모델 (Local models)을 혼합할 수 있습니다.
• 제공자별 특이 사항 (Quirks)이 런타임 계층에서 정규화 (Normalized)됩니다.

Cloclo는 인증 (Auth), 기본 URL (Base URLs), 도구 호출 (Tool calling), 지침 배치 (Instruction placement)의 차이점을 처리하므로, 여러분의 에이전트 시스템이 이를 직접 처리할 필요가 없습니다.

Cloclo는 단순한 단일 어시스턴트 채팅이 아닌, **다중 에이전트 실행 (Many-agent execution)**을 위해 구축되었습니다.

런타임에는 다음 사항에 대한 지원이 포함됩니다:

• 부모 에이전트로부터 실행되는 하위 에이전트 (Sub-agents)
• 공유 레지스트리 (Shared registry)를 통한 도구 호출 (Tool invocation)
• 위험한 동작에 대한 권한 및 보안 규칙 (Permissions and security rules)
• 세션, 재개 가능성 (Resumability), 체크포인트 (Checkpoints), 히스토리 압축 (History compaction)
• 외부 도구 서버를 위한 MCP 통합 (MCP integration)
• 핵심 에이전트 로직의 이식성을 유지하면서 수행되는 제공자 인식 실행 (Provider-aware execution)

내장된 기능에는 파일 도구 (file tools), 셸 실행 (shell execution), 검색 (search), 웹 페치 (web fetch), 브라우저 자동화 (browser automation), 메모리 액세스 (memory access), 그리고 에이전트 생성 (agent spawning)이 포함됩니다. 스킬 (Skills)과 훅 (hooks)을 사용하면 핵심 루프 (core loop)를 다시 작성하지 않고도 런타임 (runtime)을 확장할 수 있습니다.

실제로 이는 한 에이전트는 계획을 세우고, 다른 에이전트는 코드를 패치하며, 또 다른 에이전트는 검증하고, 다른 에이전트는 문서를 검색하는 시스템을 구축할 수 있으며, 이들 모두가 동일한 런타임 계약 (runtime contract) 내에서 작동함을 의미합니다.

Cloclo는 **사용자 범위 (user scope)**와 프로젝트 범위 (project scope) 모두를 위한 지속성 메모리 (persistent memory)를 제공합니다.

이는 단순한 채팅 기록이 아닙니다. 에이전트가 다음 사항들을 유지하기 위해 사용할 수 있는 런타임 메모리입니다:

• 사용자 선호도 (user preferences)
• 프로젝트 컨텍스트 (project context)
• 이전 결정 사항 (prior decisions)
• 참조 포인터 (reference pointers)
• 재사용 가능한 피드백 (reusable feedback)

메모리 시스템은 파일 기반 (file-backed)이며, 검사 가능하고, 장기적인 협업을 위해 설계되었습니다. 에이전트는 매 세션마다 모든 것을 다시 유도하는 대신 메모리를 읽고, 쓰고, 업데이트하고, 잊을 수 있습니다.

멀티 에이전트 시스템 (multi-agent systems)에서 메모리는 공유된 내구성이 있는 컨텍스트 (shared durable context) 역할을 합니다. 즉, 반복은 줄어들고, 연속성은 향상되며, 더욱 일관된 조정 (coordination)이 가능해집니다.

스킬 (Skills)은 에이전트가 할 수 있는 일을 확장하는 재사용 가능한 기능 패키지 (capability packages)입니다.

스킬은 반복되는 워크플로 (workflows)를 이름이 지정된 조합 가능한 동작 (composable behaviors)으로 변환하는 런타임의 방식입니다. 예시는 다음과 같습니다:

• 디버깅 흐름 (debugging flows)
• PR 리뷰 (PR review)
• 문서 및 PDF 처리 (document and PDF handling)
• 스프레드시트 작업 (spreadsheet work)
• 프론트엔드 생성 (frontend generation)
• 커밋 도우미 (commit helpers)
• 코드 단순화 (code simplification)

스킬은 가공되지 않은 도구 (raw tools) 상위에 위치합니다. 도구는 기본 요소 (primitives)이며, 스킬은 패턴 (patterns)입니다.

이를 통해 Cloclo는 에이전트 팀을 위한 공유 기질 (shared substrate)로서 유용하게 사용될 수 있습니다. 즉, 각 에이전트가 워크플로를 매번 새로 만드는 대신, 모든 에이전트가 동일한 운영 어휘 (operational vocabulary)를 상속받을 수 있습니다.

Gogeta는 Cloclo가 가능하게 하는 시스템의 한 예입니다.

Gogeta를 런타임 위에 구축된 융합 레이어 (fusion layer)라고 생각하십시오:

• 한 모델은 계획 (planning)에 강점이 있고
• 다른 모델은 코드 수정 (code edits)에 강점이 있으며
• 다른 모델은 검증 (verification)에 강점이 있고
• 또 다른 모델은 검색 (retrieval)이나 요약 (summarization)을 위해 저렴하고 빠릅니다

Cloclo는 이러한 구성을 실용적으로 만드는 런타임 구성 요소들을 제공합니다:

• NDJSON 전송 (transport)
• AICL 조정 (coordination)
• 프로바이더 추상화 (provider abstraction)
• 공유 도구 (shared tools)
• 공유 메모리 (shared memory)
• 공유 기술 (shared skills)
• 하위 에이전트 실행 (sub-agent execution)

따라서 Gogeta는 런타임 그 자체가 아닙니다. 그것은 런타임 위에서 (on top of) 무엇을 구축할 수 있는지 보여주는 예시입니다: 즉, 구조화된 협업을 갖춘 멀티 모델, 멀티 에이전트 시스템입니다.

어떤 AI 에이전트든 Cloclo를 자신의 몸체 (body)로 사용할 수 있습니다. 에이전트가 생각하면, Cloclo가 행동합니다.

예시: Claude Code (Opus)가 Cloclo에 위임함

Claude Code는 파일을 읽고, 코드를 작성하고, 검색하고, 추론할 수 있지만, 전화를 걸거나, 브라우저를 열거나, 스프레드시트를 만들거나, 데스크톱을 제어할 수는 없습니다. Cloclo는 할 수 있습니다.

# Claude가 전화 통화를 위임함
node delegate.mjs --task "Call +33645555422 and reserve a table for 2 tonight, speak French"
# Claude가 브라우저 작업을 위임함
...

흐름 (flow):

에이전트 (두뇌) → NDJSON → Cloclo (몸체) → 전화, 브라우저, 데스크톱, 문서, 음성
↓
에이전트 ← NDJSON ← Cloclo ← 결과

네오 (Neo)가 쿵푸를 다운로드하는 것처럼 — 에이전트는 Twilio 전화를 거는 '방법 (HOW)'을 알 필요가 없습니다. 그저 원하는 것을 말하면, Cloclo가 실행합니다.

기능 (Capability)	도구 (Tools)
전화 (Phone)	PhoneCall, PhoneCallLive, SendSMS, PhoneStatus
...

브릿지 스크립트 (The bridge script). 셸 명령 (shell command)을 실행할 수 있는 모든 에이전트는 Cloclo에 위임할 수 있습니다:

// 모든 Node.js 에이전트로부터
import { execSync } from "child_process";
const result = JSON.parse(
...

# 모든 Python 에이전트로부터
import subprocess, json
result = json.loads(subprocess.check_output([
...

Cloclo는 /remote를 지원합니다.

— 원격 머신에서 작업을 실행합니다.

사용자 머신 (Your machine)  원격 머신 (Remote machine) (파리, SF, 어디든)
↓                         ↓
Claude Code → NDJSON → Cloclo local → /remote → Cloclo remote
...

하나의 두뇌, 어디에나 있는 몸체들. Cloclo를 실행하는 모든 머신은 당신이 제어할 수 있는 노드 (node)가 됩니다:

• 원격 서버에서 코드 실행
• 원격 데스크톱 제어
• 원격 Twilio 인스턴스에서 전화 걸기
• 다른 IP/위치에서 웹 브라우징
• 로컬 세션이 종료되어도 유지되는 장시간 실행 작업 (long-running tasks) 실행

에이전트는 Cloclo가 어디에서 실행되는지 상관하지 않습니다. NDJSON은 신경계이며, AICL은 언어이고, 네트워크는 신체입니다.

다음과 같은 경우 Cloclo를 사용하세요:

• 단순한 챗봇이 아닌 런타임 (runtime)
• 깔끔한 CLI 경계를 통한 멀티 에이전트 오케스트레이션 (multi-agent orchestration)
• 어떤 언어에서도 가능한 NDJSON 우선 통합 (NDJSON-first integration)
• 에이전트 간의 AICL 네이티브 조정 (AICL-native coordination)
• 13개의 제공업체(providers)에 걸친 이식 가능한 실행 (portable execution)
• 도구, 메모리 및 기술을 위한 공유 인프라 (shared infrastructure)

git clone https://github.com/SeifBenayed/claude-code-sdk.git
cd claude-code-sdk
npm install
...

src/

— 수정 가능한 런타임 소스
claude-native.mjs

— 번들링된 단일 파일 CLI 출력
AICL_ONBOARDING.md

— 런타임에 진입하는 에이전트를 위한 온보딩 문서
test-suite.mjs

— 런타임 및 E2E 테스트

MIT