Kocoro-lab/Kocoro

A Mac-native AI agent with memory, local computer access, browser control, IM channels, and MCP-native integrations. Built on Shannon.

Kocoro – Mac에 설치된 AI 동료

무엇인가요 – Kocoro는 macOS용 로컬 실행형 AI 에이전트 프레임워크입니다. 프로젝트의 오픈소스 부분(‘shan’ 런타임)은 파일 읽기/쓰기, 앱 제어, 쉘 명령 실행, 브라우저 자동화, Slack/LINE/Feishu/Telegram에서 채팅이 가능한 ‘에이전트’를 제어하는 데몬입니다. 별도로 개발된 폐쇄형 GUI 앱(Kocoro Desktop)이 이 데몬과 통신하지만, 데몬 자체는 명령줄, TUI, 또는 HTTP API를 통해 직접 사용할 수 있습니다.

왜 중요한가요 – 언어 모델에 전체 컴퓨터 접근 권한을 부여하면서도, 무거운 처리는 자신의 기기에서 수행할 수 있게 해줍니다. 에이전트 루프, 권한 검사, 도구 목록, 메모리 관리는 모두 데몬에 통합되어 있어, 파일이나 화면 데이터를 제3자 서비스에 전송하지 않고도 동일한 AI 기반 워크플로우를 실행할 수 있습니다.

핵심 기능

영역	Kocoro가 할 수 있는 일
에이전트 런타임	지속 메모리가 있는 이름 붙은 에이전트, 구성 가능한 도구, 작업별 승인 기능.
로컬 도구	파일 읽기/쓰기/편집, glob/grep, 아카이브 검사/추출, PDF/DOCX/XLSX/PPTX 텍스트 추출, 쉘(`bash`), macOS AppleScript, 접근성/컴퓨터 사용 UI 자동화, 클립보드, 알림, Playwright를 통한 브라우저 자동화(ChromeDP로 백업).
권한 엔진	세밀한 승인(`yes`로 자동 승인, 도구별 프롬프트, 또는 `--dangerously-skip-permissions`로 테스트용으로 건너뛰기).
상호작용 모드	• 인터랙티브 TUI(`shan`), • CLI 단일 명령, • 데몬 HTTP API(포트 7533), • MCP(Message-Control-Protocol) 서버/클라이언트, • macOS용 실시간 음성 프론트브레인(`shan koe`).
팀 통합	Shannon Cloud 게이트웨이를 통해 Slack, LINE, Feishu, Telegram으로 메시지 전송/수신.
메모리 및 동기화	세션 기록은 로컬에 저장, 옵션으로 Kocoro Cloud를 통해 클라우드 동기화로 다기기 연속성 제공.
스케줄링 및 감시자	로컬 스케줄된 작업, 파일 시스템 감시자, 주기적 점검용 허트비트 모드.
확장성	훅, 사용자 정의 명령, 각 도구용 플러그인 스타일 `Info()` 스키마.

시작하기 (README에 설명됨)

데몬 설치

# npm (권장 – 시작 시 자동 업데이트)
npm install -g @kocoro/kocoro

# 또는 스크립트
curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Kocoro/main/install.sh | sh

# 또는 소스에서 빌드 (Go 1.25+ 필요)
git clone https://github.com/Kocoro-lab/Kocoro.git
cd Kocoro
go build -o $(go env GOPATH)/bin/shan .
ln -sf shan $(go env GOPATH)/bin/kocoro   # 선택적 별칭

LLM 게이트웨이 설정 – Shannon Cloud API 키 또는 자체 호스팅된 Shannon 게이트웨이, 또는 로컬 모델용 Ollama 중 하나를 선택.
```
shan --setup   # 엔드포인트와 API 키 입력 프롬프트
```
에이전트 실행
- 인터랙티브 TUI: shan
- 단일 쿼리: shan "who was Ada Lovelace"
- 이름 붙은 에이전트 사용: shan --agent ops-bot "check prod health"
- 모든 도구 사용 자동 승인: shan -y "open Safari and navigate to github.com"
옵션 GUI – 동일한 데몬과 통신하는 Kocoro Desktop (macOS DMG)을 다운로드.

아키텍처 개요

shan 바이너리 – 데몬/런타임. 다음을 제공:
- TUI/CLI 프론트엔드.
- 프로그래밍 제어용 HTTP API(기본 포트 7533).
- 외부 서비스와의 스트리밍 메시지용 MCP 서버/클라이언트.
도구 – internal/tools/ 아래의 Go 패키지. 각각 Info() 스키마(이름, 승인 모드, 입력/출력)를 구현. 데몬 시작 시 로드됨.
권한 엔진 – 도구 호출에 사용자 확인이 필요한지 결정. -y 또는 위험 플래그로 건너뛸 수 있음.
메모리 계층 – 로컬 세션 로그에 더해, Kocoro Cloud를 통한 클라우드 동기화로 지속적 에이전트 메모리 제공.
음성 프론트브레인 (shan koe) – WebRTC를 통해 OpenAI 또는 Qwen로 오디오를 라우팅하고, 인식된 요청을 동일한 에이전트 루프에 전달하는 실시간 음성 인터페이스.

누구에게 적합한가요?

파워 유저 – LLM이 macOS의 반복 작업(파일 정리, 코드 린팅, 데이터 추출, UI 탐색)을 자동화하고 싶지만, 모델에 전체 원격 접근 권한을 주고 싶지 않은 사람.
개발자 – 맞춤형 AI 기반 워크플로우를 개발하고 싶은 사람. 새로운 도구를 추가하거나 HTTP API에 연결 가능.
팀 – Slack/Telegram에 통합된 공유 ‘AI 동료’를 즉시 사용하고 싶은 사람.

라이선스

리포지토리는 MIT 라이선스로 배포됩니다 (LICENSE 파일 참조). 데몬/런타임만 오픈소스이며, 동반되는 Kocoro Desktop GUI는 프로퍼라이어터리입니다.

빠른 참조 치트시트

# 인터랙티브 UI 시작
shan

# 단일 쿼리 (도구 승인 프롬프트)
shan "list all TODO comments in this project"

# 모든 도구 자동 승인 (주의해서 사용)
shan -y "open Calendar and show me today's events"

# 이름 붙은 에이전트 실행
shan --agent research-bot "summarize the latest AI papers"

# MCP 서버 시작 (외부 클라이언트용)
shan mcp serve

# 반복 작업 스케줄링
shan schedule create "daily backup" "shan \"run backup.sh\"" --cron "0 2 * * *"

결론 – Kocoro의 오픈소스 shan 데몬은 macOS 사용자에게 파일 읽기/쓰기, GUI 제어, 쉘 명령 실행, 팀 채팅 서비스와의 대화가 가능한 완전 기능의 로컬 실행형 AI 에이전트 플랫폼을 제공하며, 무거운 LLM 추론은 Shannon 클라우드 또는 로컬 Ollama 서버에서 처리됩니다.