Miosa-osa/canopy: AI 에이전트 시스템을 위한 오픈 소스 워크스페이스 프로토콜 및 커맨드 센터

AI 에이전트 (AI agent) 시스템을 위한 오픈 소스 워크스페이스 프로토콜 (workspace protocol) 및 커맨드 센터 (command center). 챗봇이 아닌, 자율적인 AI 기업을 구축하세요.

Canopy는 마크다운 (markdown) 폴더를 완전히 작동하는 AI 기업으로 변환하는 워크스페이스 프로토콜입니다. 일반 파일에 에이전트 (agents), 기술 (skills), 팀 (teams), 예산 (budgets), 거버넌스 (governance)를 정의하세요. 그런 다음 어떤 AI 백엔드 (AI backend) (Claude Code, OSA, Codex, Gemini, Cursor, Aider, Windsurf)든 연결하여 하트비트 스케줄 (heartbeat schedules)에 따라 자율적으로 작동하는 모습을 지켜보세요.

데스크톱 커맨드 센터는 330개 이상의 에이전트 (agents)를 채용하고, 픽셀 아트 (pixel-art) 가상 오피스에서 그들이 협업하는 모습을 지켜보며, 토큰 비용 (token costs)을 실시간으로 모니터링하고, 필요할 때 개입할 수 있는 네이티브 앱을 제공합니다.

프롬프트 (prompts)가 아닌, AI 시스템을 관리하세요.

# 한 번의 명령으로 설치 및 실행
curl -fsSL https://raw.githubusercontent.com/Miosa-osa/canopy/main/install.sh | bash

필수 구성 요소를 설치하고, 리포지토리 (repo)를 클론(clone)하며, 데이터베이스 (database)를 설정하고 앱을 엽니다.

# 이미 클론했나요? 수동 설정
cd canopy && make setup && make dev

# 프로토콜만 필요한가요? 앱은 필요 없습니다
cd canopy/operations/sales-engine
# Claude Code, Cursor, OSA, Codex — 어떤 에이전트 (agent)든 SYSTEM.md를 읽고 작업을 시작합니다

단계	발생하는 일
01	워크스페이스 선택: sales-engine/ , dev-shop/ , content-factory/ , cognitive-os/ 또는 직접 구축
02	에이전트 연결: Claude Code, OSA, Cursor, Codex, Gemini, Aider, Windsurf 또는 OpenClaw
03	실행: 에이전트 (agent)가 SYSTEM.md를 읽고, 기술 (skills)과 전문가 (specialists)를 발견하며, 자율적으로 작동함

마크다운 (markdown)을 읽을 수 있다면, 채용된 것입니다.

워크스페이스 선택 (sales-engine, dev-shop, content-factory, cognitive-os, custom)
|
v
...

레이어 (Layer)	기술 (Technology)
백엔드 (Backend)	Elixir 1.15 + Phoenix 1.8.5
...
Canopy 워크스페이스는 일반 마크다운 (markdown) 파일로 구성된 폴더입니다. 독점적인 서버도, 종속 (lock-in)도 없습니다. 디렉토리 구조 (directory structure)가 곧 아키텍처 (architecture)입니다.

L0 SYSTEM.md + company.yaml 항상 로드됨 (~2K tokens)
L1 agents/ + skills/ 온디맨드 (On-demand) (~항목당 ~2K tokens)
L2 reference/ + workflows/ + spec/ 심층 컨텍스트 (Deep context) (검색을 통한 전체 내용)
...

SYSTEM.md

은 진입점 (entry point)입니다: 정체성 (identity), 부팅 시퀀스 (boot sequence), 코어 루프 (core loop), 기술 목록 (skills list), 에이전트 목록 (agents list), 라우팅 테이블 (routing table), 그리고 핸드오프 프로토콜 (handoff protocol) — 전체 운영 체제 (operating system)를 정의하는 약 120줄의 코드입니다.

company.yaml

은 미션 (mission), 예산 (budget), 거버넌스 규칙 (governance rules), 조직도 (org chart), 그리고 증거 게이트 (evidence gates)가 포함된 목표 계층 구조 (goal hierarchy)를 담고 있습니다.

모든 엔티티 (entity) — 에이전트 (agents), 기술 (skills), 팀 (teams), 프로젝트 (projects), 작업 (tasks) — 는 세 가지 계층 (tiers)으로 자신을 노출합니다. 에이전트는 필요한 시점에 필요한 것만 요청합니다.

Tier 0 (Catalog) 이름 + 한 줄 설명만 포함. 엔티티당 ~100 tokens.
Tier 1 (Activation) 온디맨드 시 전체 매니페스트 (manifest) 본문 로드. 엔티티당 ~2K tokens.
Tier 2 (Full) 모든 참조 자산: 스크립트 (scripts), 연결된 문서 (linked docs), 증거 스키마 (evidence schemas).

카탈로그 (catalog)는 항상 비용이 저렴합니다. 전체 매니페스트 (full manifests)는 실제로 사용될 때만 비용이 발생합니다. 이를 통해 모든 것을 사전에 로드하는 시스템 대비 96%의 컨텍스트 감소 (context reduction)를 달성합니다.

19개 카테고리에 걸쳐 사전 구축된 330개 이상의 에이전트 라이브러리에서 찾아 고용하거나, 마크다운 (markdown) 파일로 직접 정의할 수 있습니다. 에이전트는 바이너리 (binaries)가 아니라 행동 템플릿 (behavioral templates)입니다.

각 에이전트 파일은 역할 (role), 도구 (tools), 조정 규칙 (coordination rules), 에스컬레이션 경로 (escalation path), 그리고 하트비트 동작 (heartbeat behavior)을 정의합니다. 커맨드 센터 (Command Center)에서 클릭 한 번으로 고용하거나 파일을 agents/ 디렉토리에 넣기만 하면 됩니다.

에이전트는 일정에 따라 깨어나고, 작업을 확인하고, 실행하며, 자율적으로 위임합니다. 하트비트 (heartbeat)는 원자적 체크아웃 (atomic checkout), 거버넌스 게이트 체크 (governance gate checks), 그리고 세션 연속성 (session continuity)을 포함하는 9단계 GenServer 사이클입니다:

에이전트 깨어남 (일정, 작업 할당, 또는 멘션)
-> 정체성 및 역할 검색
-> 거버넌스 게이트 확인 (승인 대기 중인 경우 실행 차단)
...

에이전트는 처음부터 새로 시작하는 대신 하트비트를 통해 컨텍스트를 재개합니다:

세션 체인 (Session chains) — parent_session_id 및 sequence_number를 통한 연결된 세션

전체 실행 이력 추적
자동 압축 (Automatic compaction)— 각 하트비트 (heartbeat) 이후, 압축기 (Compactor)가 구조화된 사실 (사용된 도구, 오류, 출력, 결정 사항)을 요약하여 추출합니다.
핸드오프 생성 (Handoff generation)— 미결 항목, 주요 결정 사항, 차단 요소 (blockers), 그리고 지속 상태 (continuation state)를 포함하는 마크다운 (markdown) 핸드오프 문서를 생성합니다.
교차 하트비트 주입 (Cross-heartbeat injection)— 다음 하트비트 시 이전 세션의 핸드오프를 컨텍스트 서문 (context preamble)으로 로드합니다.
체인 쿼리 (Chain queries)— GET /sessions/:id/chain 호출 시 누적 토큰 사용량과 함께 전체 세션 계보 (lineage)를 반환합니다.
수동 압축 (Manual compaction)— POST /sessions/:id/compact 호출 시 요청에 따라 요약을 트리거합니다.

태스크 (Tasks)는 통신 프로토콜입니다. 에이전트 간의 별도 메시징 (agent-to-agent messaging)은 필요하지 않습니다.

위임 (Delegation)— 어댑터 인지 라우팅 (adapter-aware routing)을 통해 보고서에 할당된 하위 태스크를 생성합니다.
상태 (Status)— 태스크 필드를 수정합니다.
에스컬레이션 (Escalation)— 오케스트레이터 (orchestrator)까지 상위 체인을 따라 올라갑니다.
원자적 체크아웃 (Atomic checkout)— 한 번에 오직 하나의 에이전트만 태스크를 작업합니다 (409 오류 발생 시 다음으로 이동).

태스크 계층 구조: 이니셔티브 (Initiatives) → 프로젝트 (Projects) → 마일스톤 (Milestones) → 이슈 (Issues) → 하위 이슈 (Sub-issues). 모든 태스크는 회사의 목표로 거슬러 올라갑니다.

하나의 오케스트레이터가 태스크 내용에 따라 서로 다른 런타임 (runtimes)으로 작업을 배정합니다. 디스패치 라우터 (dispatch router)는 3단계 우선순위 폭포 (three-tier priority waterfall) 방식을 사용합니다:

1. 태스크 어댑터 오버라이드 (Task adapter_override) (태스크별 명시적 지정)
2. 콘텐츠 기반 라우팅 (Content-based routing) (레이블 + 정규 표현식 매칭)
3. 에이전트 기본 어댑터 (Agent default adapter) (폴백/fallback)

콘텐츠 패턴에 따라 자동으로 라우팅됩니다:

/delegate "API 명세서를 작성해줘" → Claude Code (심층 추론)
/delegate "50개 파일 리팩토링해줘" → Codex (대량 코드 변경)
/delegate "스크린샷을 분석해줘" → Gemini (멀티모달)
...

위임 시스템은 자동 어댑터 선택을 통해 하위 태스크를 생성하며, 추론된 어댑터 유형과 일치하는 유휴 에이전트를 찾습니다. 드라이 런 (dry-run) 라우팅을 위해 POST /dispatch/preview 프리뷰 엔드포인트를 사용할 수 있습니다.

세 가지 단계 — 가시성 (visibility), 소프트 알림 (soft alert), 하드 천장 (hard ceiling):

임계값 (Threshold)	동작 (Behavior)
항상 (Always)	대시보드에 에이전트, 태스크 (task), 프로젝트 (project), 목표 (goal)별 지출 표시
...	토큰 (tokens) 및 달러 ($) 추적. 모든 레벨 (에이전트, 팀, 부서, 본부, 조직)에서 롤업 (Rollup) 가능. 스케줄러 (scheduler), 수동 호출 (manual invoke), 태스크 체크아웃 (task checkout) 등 모든 실행 경계에서 강제 적용. 잠금 없는 (lock-free) 성능을 위한 ETS 원자적 카운터 (atomic counters) 사용.

컨트롤러 파이프라인 (controller pipeline)에 통합된 승인 강제 사항:

생성 게이트 (Spawn gate)— 승인 없이 에이전트를 생성할 수 없음 (워크스페이스별 설정 가능)
삭제 게이트 (Delete gate)— 에이전트 종료 시 권한 필요
예산 초과 게이트 (Budget override gate)— 한도 초과 시 명시적 승인 필요
전략 게이트 (Strategy gate)— 제안 사항은 실행 전 이사회 검토 필요
하트비트 차단 (Heartbeat blocking)— 승인 대기 중인 에이전트는 실행이 차단됨
자동 실행 (Auto-execution)— 승인된 작업은 Executor를 통해 자동으로 재실행됨
멱등성 (Idempotent)— 중복된 승인 대기 항목은 중복 제거됨

거버넌스 (Governance)는 Phoenix 플러그인 (CanopyWeb.Plugs.Governance)으로, 작업에 승인이 필요한 경우 HTTP 202 응답과 함께 중단됩니다. 워크스페이스의 governance 설정은 어떤 작업에 승인이 필요한지, 어떤 역할 (role)이 자동 승인되는지를 결정합니다.

POST /spawn → Governance 플러그인 → Gate.check(:spawn_agent)
|
requires_approval? → yes → 202 {pending_approval}
...

계층적 예산 (cascading budgets)을 가진 5계층 구조:

조직 (Organization, 청구 엔티티, 거버넌스 설정)
└── 본부 (Division, 사업 단위, 헤드 에이전트, 예산)
    └── 부서 (Department, 기능 영역, 헤드 에이전트, 예산)
    ...

모든 레벨에서 완전한 CRUD 지원. GET /hierarchy?organization_id=X는 평면 쿼리 (flat queries)로부터 조립된 전체 트리를 반환합니다. 팀 멤버십은 역할 할당이 포함된 조인 테이블 (join table)을 통해 추적됩니다.

7가지 단계 유형을 가진 DAG 기반 워크플로 실행:

단계 유형 (Step Type)	설명 (Description)
agent_task	특정 에이전트에게 작업 할당
approval	사람이 승인할 때까지 차단
condition	이전 단계의 출력 결과에 따라 분기
transform	단계 간 데이터 형태 변환
webhook	외부 HTTP 엔드포인트 호출
delay	지정된 시간 동안 대기
parallel	여러 단계를 동시에 실행

워크플로 (Workflows) 지원 사항:

• 의존성 해결을 위한 위상 정렬 (Topological sort)

• 구성 가능한 백오프 (backoff) 전략을 포함한 재시도 (constant, linear, exponential)

• Canopy.Workflows.Scheduler를 통한 Cron 기반 예약 실행

• 단계 수준의 상태 추적 (pending → running → completed/failed/skipped)

• 결함 허용 (fault tolerance)을 위한 OTP 감독 (supervision)

에이전트들이 물건을 구매할 수 있게 됩니다. Stripe의 머신 결제 프로토콜 (Machine Payments Protocol, MPP)을 통해 에이전트가 자율적으로 거래할 수 있습니다. 즉, API 비용을 지불하거나, 컴퓨팅 자원을 구매하거나, 다른 에이전트 워크스페이스로부터 서비스를 구매할 수 있습니다.

Canopy의 예산 집행 (budget enforcement) 기능은 MPP를 감싸는 형태로 작동합니다:

임계값 미만 (Under threshold) — 에이전트가 자율적으로 결제하며, 예산에 기록됨
임계값 초과 (Over threshold) — 결제가 사람의 승인을 위해 대기열에 추가됨
예산 초과 (Over budget) — 강제 중단, 결제 승인 불가

기능별 클러스터로 구성된 56페이지:

클러스터 (Cluster)	페이지 (Pages)
Daily	대시보드 (Dashboard), 받은 편지함 (Inbox), 채팅 (Chat), 가상 오피스 (Virtual Office)
Work	이슈 (Issues), 프로젝트 (Projects), 목표 (Goals), 작업 결과물 (Work Products), 워크플로 (Workflows)
Agents	에이전트 명단 (Agent Roster), 에이전트 상세 (Agent Detail), 생성 (Spawn), 세션 (Sessions), 일정 (Schedules)
Data	메모리 (Memory), 문서 (Documents), 데이터셋 (Datasets), 시그널 (Signals), 템플릿 (Templates)
Observe	활동 (Activity), 로그 (Logs), 분석 (Analytics), 비용 (Costs), 보고서 (Reports), 알림 (Alerts), 감사 (Audit)
Automate	기술 (Skills), 통합 (Integrations), 웹훅 (Webhooks), 플러그인 (Plugins), 게이트웨이 (Gateways)
Library	에이전트 마켓플레이스 (Agent Marketplace), 기술 (Skills), 회사 (Companies), 팀 (Teams) (상세 페이지 포함)
System	조직 (Organizations), 계층 구조 (Hierarchy), 부문 (Divisions), 부서 (Departments), 팀 (Teams), 사용자 (Users), 액세스 (Access), 설정 (Config), 비밀값 (Secrets), 환경 (Environment)

책상에 앉아 있는 에이전트들을 보여주는 픽셀 아트 (Pixel-art) 2D 그리드 뷰와 선택 가능한 3D 장면 (Threlte를 통한 Three.js)을 제공합니다. 에이전트는 활성화되었을 때 빛이 나고, 작업 중일 때는 위아래로 움직이며, 말풍선에 현재 작업을 표시합니다. 클릭하여 조사하거나 개입할 수 있습니다.

57개의 모의 API (mock API) 모듈은 백엔드 연결 없이도 완전한 프론트엔드 기능을 제공합니다. 모든 API 엔드포인트에는 실제와 유사한 데이터를 가진 대응하는 모의 핸들러 (mock handler)가 있어, 오프라인 개발 및 데모 모드가 가능합니다.

완전한 워크스페이스 (workspace) — B2B 영업 엔진 (sales engine)을 예로 들면:

sales-engine/
|
| L0 — 항상 로드됨
...

** TEAM.md** — 조직 하위 트리 (org subtree)를 정의합니다. 팀 (Teams)은 에이전트 (agents)를 그룹화하고, 공유 예산의 일부를 소유하며, 자체적인 조정 프로토콜 (coordination protocol)을 선언합니다.

** PROJECT.md** — 마일스톤 (milestones), 예산 할당 및 리소스 할당이 포함된 계획된 작업을 정의합니다. 명시적인 증거 게이트 (evidence gates)를 포함합니다.

** TASK.md** — 휴대 가능하고 재사용 가능한 작업 정의 (task definition)입니다. 에이전트에게 할당되며, 작업 계층 구조 (task hierarchy)를 통해 추적됩니다.

19개 카테고리에 걸친 330개 이상의 사전 구축된 에이전트 (pre-built agents):

카테고리	예시
엔지니어링 (Engineering)	백엔드 (backend), 프론트엔드 (frontend), 데브옵스 (devops), 보안 (security), 성능 (performance), 데이터베이스 (database)
...

커맨드 센터 (Command Center)에서 라이브러리를 찾아보거나, 어떤 에이전트 파일이라도 agents/ 폴더에 넣으세요.

Canopy는 연결된 모든 런타임 (runtime)으로 작업을 전달합니다. 11개의 어댑터 (adapters) — 5개는 완전한 기능 제공, 6개는 베타 (beta) 버전:

어댑터	상태	설치
OSA	작동 가능 (Functional)	`curl -fsSL https://raw.githubusercontent.com/Miosa-osa/OSA/main/install.sh
Claude Code	작동 가능 (Functional)	npm install -g @anthropic-ai/claude-code
Codex	작동 가능 (Functional)	npm install -g @openai/codex
Bash / HTTP	작동 가능 (Functional)	내장됨 (Built-in)
Cursor	베타 (Beta)	cursor.sh
Gemini	베타 (Beta)	ai.google.dev
OpenClaw	베타 (Beta)	npm install -g openclaw
Aider	베타 (Beta)	pip install aider-chat
JidoClaw	베타 (Beta)	`curl -fsSL https://raw.githubusercontent.com/robertohluna/jido_claw/main/install.sh
Windsurf	베타 (Beta)	codeium.com/windsurf

커맨드 센터는 설치된 어댑터를 자동 감지하고 원클릭 설정 마법사를 제공합니다. 제공자 자격 증명 (Provider credentials)은 Tauri의 보안 저장소 (secure store)를 통해 OS 키체인 (OS keychain)에 저장됩니다.

모든 어댑터는 Canopy.Adapter 동작을 구현합니다: execute/2, stream/2, health/1, capabilities/0.

워크스페이스 (Workspace)	설명 (Description)
sales-engine	B2B 파이프라인: 잠재 고객 발굴 (prospecting), 자격 검증 (qualification), 데모 (demos), 계약 체결 (close)
dev-shop	소프트웨어 에이전시: 기획 (planning), 코딩 (coding), 리뷰 (review), 배포 (deployment)
content-factory	콘텐츠 제작: 전략 (strategy), 작성 (writing), 편집 (editing), 발행 (publishing)
cognitive-os	개인용 제2의 뇌 (Personal second brain): 수집 (capture), 처리 (process), 연결 (connect), 검색 (retrieve)
custom	전체 스캐폴딩 (scaffolding)이 포함된 빈 슬레이트 (Blank slate)