데스크톱 펫, 플러그인, 그리고 선택적인 로컬 에이전트 연동을 지원하는 데스크톱 컴패니언 플랫폼.
OpenPets는 데스크톱에 움직이는 컴패니언을 띄워 주며, 플러그인을 통해 집중 도우미, 알림 시스템, 미니 게임, 런처, 또는 코딩 에이전트 조수 등으로 다양하게 변신시킬 수 있습니다.
by Boring Dystopia Development
다른 언어로 읽기: English | 日本語 | 한국어 | 简体中文 | 繁體中文 | Português (Brasil) | Español (LatAm)
---
## Download OpenPets
**[최신 OpenPets 데스크톱 릴리스 다운로드](https://github.com/alvinunreal/openpets/releases/latest)** 후 실행해 보세요. 에이전트 설정 없이도 펫이 즉시 나타납니다.
- **데스크톱 펫**: 대기, 배회, 반응 등의 모션으로 작업 공간을 심심하지 않게 채워주는 움직이는 컴패니언입니다.
- **공식 플러그인**: 집중 타이머, 알림, 감정 상태 체크인, 미니 게임, 실행 바로가기, 수분 섭취 미리 알림, 가상 펫 스탯 기능을 제공합니다.
- **플러그인 SDK v3**: 권한(permissions), 쿼터(quotas), 스토리지, 스케줄러, 명령어, 패널, 이벤트, 오디오, 알림 기능 등을 사용하여 새로운 펫 능력을 개발할 수 있는 샌드박스화된 JavaScript/TypeScript 런타임입니다.
- **선택적인 에이전트 레이어**: Claude Code, OpenCode, Cursor, Pi 및 MCP 클라이언트가 프롬프트, 코드, 경로, 로그, 보안 비밀번호(secrets) 등을 말풍선에 노출하지 않고도 로컬 펫의 반응을 트리거할 수 있도록 지원합니다.
---
## Star OpenPets
OpenPets가 개발 환경이나 데스크톱 작업 공간을 더 즐겁게 만들어 주었다면 저장소에 스타(Star)를 눌러 주세요.
---
## For Users: Getting Started
OpenPets를 즐기기 위해 개발자이거나 AI 에이전트를 연결할 필요는 없습니다. 데스크톱 앱은 공식 플러그인 라인업과 함께 설치 즉시 완벽하게 작동합니다.
### 1. Install OpenPets Desktop
[OpenPets 릴리스](https://github.com/alvinunreal/openpets/releases/latest)에서 운영체제에 맞는 패키지를 다운로드하세요:
- **macOS Apple Silicon**: `OpenPets-*-mac-arm64.dmg`
- **macOS Intel**: `OpenPets-*-mac-x64.dmg`
- **Windows**: `OpenPets-*-win-x64-setup.exe`
- **Linux**: `OpenPets-*-linux-x86_64.AppImage`
> 참고: 현재 빌드는 서명되지 않았을 수 있습니다. macOS에서 보안 경고로 실행을 차단하는 경우, 터미널에서 아래 명령어를 실행하여 격리(quarantine) 플래그를 제거해 주세요:
> ```bash
> xattr -dr com.apple.quarantine /Applications/OpenPets.app
> ```
### 2. Manage and Customize Pets
내장된 **펫 갤러리(Pet Gallery)**에서 설치된 펫을 둘러보고, 애니메이션 프레임을 미리 보며, 각 작업 공간이나 에이전트 창을 모니터링할 펫을 설정할 수 있습니다.
### 3. Enable Official Plugins
OpenPets v3는 모듈형 **공식 플러그인 카탈로그(Official Plugin Catalog)**와 함께 제공됩니다. 데스크톱 컨트롤 센터(Control Center)에서 플러그인을 활성화하거나 설정하여 집중 타이머, 알림, 인터랙티브 미니 게임 등을 추가할 수 있습니다.
#### 기본 탑재된 공식 라인업
- **Day Routine**: 습관을 추적하고 스트레칭을 하거나 자리에서 일어나도록 상기시켜 줍니다.
- **Focus Buddy**: 작업 주기를 관리할 수 있는 포모도로 스타일의 집중 타이머입니다.
- **Fortune Cookie**: 무작위로 오늘의 조언과 지혜가 담긴 문구를 보여줍니다.
- **Launch Buddy**: 단축키 명령어를 등록하여 로컬 폴더, 프로젝트 또는 애플리케이션을 빠르게 열 수 있도록 지원합니다.
- **Magic 8 Ball**: 질문을 던지면 펫이 장난스럽고 무작위적인 답변을 건넵니다.
- **Mood Check-in**: 정기적으로 기분 상태를 확인하여 정서적 웰빙을 돕습니다.
- **Reminders**: 사용자 지정 오디오 알림음과 함께 다시 알림(snooze)이 가능한 벨소리 알림을 띄워줍니다.
- **Virtual Pet**: 데스크톱 컴패니언을 다마고치 스타일의 펫으로 변신시킵니다. 실시간 상태 핀을 통해 포만감, 친밀도, 에너지 레벨이 추적됩니다.
- **Water Reminder**: 설정 가능한 주기적인 물 마시기 알림으로 수분 섭취를 유지하도록 도와줍니다.
---
## Plugin Platform & SDK v3
OpenPets 플러그인 시스템은 커스텀 컴패니언 동작을 개발할 수 있도록 안전하고 개발자 친화적인 SDK(`@open-pets/plugin-sdk`)를 제공합니다.
### 보안 및 아키텍처
- **샌드박스화된 런타임**: 각 JS 플러그인은 샌드박스 처리된 BrowserWindow 호스트 환경 내부에서 실행됩니다.
- **호스트 렌더링 UI**: 플러그인은 액션, HUD, 알림을 정의하고 데스크톱 호스트가 이를 직접 렌더링합니다. HTML/JS 코드가 raw HTML을 렌더링하거나 펫 창 내부에서 임의의 스크립트를 실행할 수 없습니다.
- **권한 모델(Permissions Model)**: 권한은 매니페스트에 선언되어야 하며 설치 시 사용자의 승인을 받아야 합니다. 민감한 API(예: `voice:listen`, `clipboard`, `pet:speak:dynamic`)는 명시적으로 동의를 토글해야 합니다.
- **SSRF 및 프라이빗 호스트 방어**: 네트워크 fetch 요청은 개발자가 선언한 호스트네임으로 제한되며 로컬 SSRF로부터 보호됩니다.
### SDK 인터페이스 (`ctx`)
플러그인은 `ctx` 객체를 통해 데스크톱 환경에 연결되며 아래와 같은 기능을 노출합니다:
- `ctx.pets` / `ctx.pet`: 기본 및 생성된 펫 인스턴스를 관리합니다: 생성, 이동, 애니메이션 및 반응 제어.
- `ctx.ui`: 경고창, 임시/고정 말풍선, 커스텀 메뉴, 패널 및 상태 HUD. 고정된 미니 HUD 말풍선은 Virtual Pet 스탯과 같이 진행 상황 표시줄이 포함된 조밀한 2x2 그리드 레이아웃을 지원합니다.
- `ctx.audio`: 호스트가 관리하는 경고음 또는 사용자가 가져온 커스텀 오디오를 트리거합니다.
- `ctx.schedule`: 정밀한 타이머 훅을 설정합니다 (`once`, `every`, `daily`, `cron`, `at`).
- `ctx.ai` / `ctx.secrets`: 플러그인 소스 코드에 API 키를 노출하지 않고 사용자가 호스트에 설정한 AI 제공자(Anthropic, OpenAI, Ollama)와 연결합니다.
- `ctx.storage`: 변경 구독 기능이 포함된 간단한 JSON 키-값(key-value) 저장소입니다.
- 기타 API: `events`, `assets`, `bus`, `net`(스트리밍 지원 포함), `notify`, `voice`(TTS 및 push-to-talk STT), `auth`(PKCE 브라우저 플로우), `files`(보안 처리된 OS 파일 선택 다이얼로그), `system`, `commands`, `status`, `log`.
### 개발자 도구 & 명령어
공식 CLI를 사용하여 플러그인을 생성, 검증 및 테스트할 수 있습니다.
#### 1. 새 플러그인 뼈대(Scaffold) 생성
공식 레이아웃(`blank`, `reminder`, `ambient`, `ai-chat`, `tamagotchi`, `calendar`) 중 하나를 템플릿으로 삼아 생성합니다:
```bash
npx @open-pets/cli plugin new "My Plugin" --template tamagotchi
```
#### 2. 검증(Validate)
패키징 전에 매니페스트 레이아웃, 권한 및 설정 스키마를 검증합니다:
```bash
npx @open-pets/cli plugin validate ./my-plugin
```
#### 3. 테스트 하네스(Test harness)
데스크톱 앱을 실행하지 않고도 결정론적(deterministic) 테스트를 작성할 수 있습니다. `@open-pets/plugin-sdk/testing`의 `createTestHarness`를 사용하여 호스트를 모킹(mock)하고, 시각을 앞으로 넘기고, 액션을 트리거하여 반응을 검증할 수 있습니다:
```javascript
import { createTestHarness } from "@open-pets/plugin-sdk/testing";
import { register } from "./index.js";
const h = createTestHarness(register, { permissions: ["pet:speak", "schedule"] });
await h.start();
h.expectScheduled("decay");
await h.clock.advance("30m");
h.expectSpoke(/need attention/i);
```
플러그인 프로젝트에서 플러그인 테스트를 실행합니다:
```bash
npm test
```
---
## Advanced: Agent Integrations
개발 에이전트가 데스크톱 컴패니언을 제어하도록 하려면 OpenPets가 제공하는 선택적인 로컬 MCP (Model Context Protocol) 연동 레이어를 사용할 수 있습니다.
### 동작 방식
에이전트를 구성하면 OpenPets가 표준 MCP 도구를 노출합니다. 에이전트는 로컬에서 애니메이션을 트리거하고, 상태를 변경하고, 말풍선을 띄울 수 있습니다:
1. **Claude Code**: OpenPets MCP, `~/.claude/CLAUDE.md` 내의 메모리 지침, 그리고 `~/.claude/settings.json` 내의 훅을 설치합니다.
2. **OpenCode**: OpenPets MCP, 커스텀 프로젝트 지침 파일, 그리고 `@open-pets/opencode` 자동 훅 플러그인을 설치합니다.
3. **Cursor / 기타 MCP 클라이언트**: OpenPets를 표준 stdio 또는 TCP MCP 서버로 등록합니다.
### MCP 서버 설정
OpenPets를 MCP 도구로 실행하려면 에이전트 설정에 서버를 추가하세요:
```json
{
"mcpServers": {
"openpets": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@open-pets/mcp@latest"]
}
}
}
```
*팁: 특정 펫을 지정하려면 `--pet ` 인자를 전달하세요.*
### 사용 가능한 MCP 도구
- `openpets_status`: 대상 펫 ID를 가져오고 런타임 연결 상태를 확인합니다.
- `openpets_react`: 펫 반응 애니메이션을 설정합니다 (예: `thinking`, `editing`, `testing`, `success`, `error`).
- `openpets_say`: 짧은 말풍선을 표시합니다.
### 로컬 프라이버시 및 보안
- 모든 자동화 반응은 정적인 로컬 트리거(예: 명령어 실행 또는 파일 쓰기)를 기반으로 작동합니다.
- 대화 내용은 민감한 변수, 경로, 비밀번호(secrets) 또는 여러 줄의 코드 스니펫이 유출되는 것을 방지하기 위해 유효성 검사를 거칩니다.
- 실시간 상호작용은 로컬 디스커버리 토큰 쓰기/읽기를 필요로 하므로, 외부 네트워크 트리거로부터 IPC 브릿지를 보호합니다.
---
## Development Workspace
OpenPets 코드베이스에 기여하거나, 변경 사항을 테스트하거나, 로컬에서 데스크톱 패키지를 빌드하기 위한 방법입니다.
### 사전 요구사항
- **Node.js**: 버전 20 이상
- **pnpm**: 버전 11 이상
- **TypeScript**: 컴파일러 지원
### 명령어
프로젝트 워크스페이스 의존성 설치:
```bash
pnpm install
```
로컬 개발 모드에서 Electron 애플리케이션 실행:
```bash
pnpm dev:desktop
```
라이브 상태의 공식 플러그인들을 로드하고 모니터링하며 실행:
```bash
pnpm dev:desktop:plugins
```
워크스페이스 타입 검사, 코드 적합성 검증 및 테스트 실행:
```bash
pnpm check
pnpm typecheck
pnpm test
```
데스크톱 애플리케이션 패키징:
```bash
# Build & package into target OS directory
pnpm package:desktop:dir
# Build & package into final installer / setup archives
pnpm package:desktop
```
### 워크스페이스 구조
```text
apps/desktop Electron 데스크톱 애플리케이션
packages/client @open-pets/client (IPC 헬퍼 라이브러리)
packages/mcp @open-pets/mcp (Model Context Protocol stdio 서버)
packages/claude @open-pets/claude (Claude 연동, 메모리 및 훅)
packages/opencode @open-pets/opencode (OpenCode 플러그인 및 지침 설정)
packages/pi @open-pets/pi (Pi CLI 확장 프로그램 연동)
packages/agent-events 공유 새니타이저(sanitizers) 및 이벤트 헬퍼 패키지
packages/cli @open-pets/cli (설정 및 스캐폴딩용 사용자 엔트리 포인트 CLI)
packages/sdk @open-pets/plugin-sdk (플러그인 SDK v3 선언 및 테스트 하네스)
packages/pet-format @open-pets/pet-format (펫 매니페스트 및 스키마 타입)
plugins/official 공식 퍼스트 파티 플러그인 워크스페이스 (호스트 카탈로그에 번들됨)
docs/ 기술 사양 및 아키텍처 문서
```
---
## Documentation
`docs/` 폴더 안의 상세한 아키텍처 및 플랫폼 문서를 확인해 보세요:
- [`docs/plugins.md`](docs/plugins.md) - 플러그인 플랫폼 SDK v3 매니페스트, 권한 및 테스트 키트.
- [`docs/claude-integration.md`](docs/claude-integration.md) - Claude Code 연동 (메모리, 훅, MCP).
- [`docs/opencode.md`](docs/opencode.md) - OpenCode 워크스페이스 연동.
- [`docs/wsl-ipc.md`](docs/wsl-ipc.md) - WSL-Windows TCP 브릿지 설정.
- [`docs/testing.md`](docs/testing.md) - 워크스페이스 테스트 및 적합성 전략.
- [`docs/release.md`](docs/release.md) - 애플리케이션 패키징 및 릴리스 프로세스.
- [`docs/workflow.md`](docs/workflow.md) - 코어 개발 및 기여 워크플로우.
---
## Safety and Privacy
- **로컬 전용(Local-Only)**: OpenPets IPC는 로컬 소켓/네임드 파이프(named pipe)를 사용하여 작동하며, 실행 시마다 임의로 생성되는 보안 토큰으로 보호됩니다.
- **SSRF 방어**: 플러그인의 네트워크 연결은 승인된 도메인으로 제한되며, 로컬 네트워크 및 사설 IP 주소로의 접근은 차단됩니다.
- **동적 콘텐츠 정화(Sanitization)**: AI가 말하는 임의의 텍스트는 로컬 필터를 거치며 경로, URL, 비밀번호(secrets) 또는 여러 줄의 코드 스니펫이 가려집니다.
- **민감한 권한 동의**: 클립보드, 마이크 또는 동적 AI 응답에 접근하는 기능은 기본적으로 꺼져 있으며, 사용자의 명시적인 동의를 필요로 합니다.