ErlichLiu/Proma

Proma는 로컬 우선(Local-first) AI 데스크톱 애플리케이션으로, 멀티 모델 Chat, 범용 Agent, 워크스페이스(Workspace), Skills, MCP, 원격 로봇 및 기억 능력을 하나의 오픈 소스 클라이언트 안에 담았습니다.

단순히 잡담을 위한 채팅창이 아니라, 개인의 워크플로우(Workflow)를 장기적으로 축적할 수 있는 Agent 작업대입니다. 간단한 질문은 Chat을 사용하고, 복잡한 작업은 Agent에게 맡기며, 데이터와 설정은 최대한 로컬에 남겨둡니다.

English README | 초보자 튜토리얼 | 오픈 소스 버전 다운로드 | 상용 버전 다운로드

Chat 모드: 멀티 모델 대화, 첨부 파일 분석, 이미지 입력, Markdown / Mermaid / KaTeX / 코드 하이라이트, 병렬 대화, 시스템 프롬프트(System Prompt), 컨텍스트(Context) 관리. Agent 모드: @anthropic-ai/claude-agent-sdk를 기반으로 한 범용 Agent로, 워크스페이스 격리, 권한 모드, 파일 조작, 긴 작업의 스트리밍 출력, 계획 확인 및 사용자 추가 질문을 지원합니다. SubAgent / Tasks: 복잡한 작업은 Claude Agent SDK의 Agent 도구를 통해 하위 Agent / Task로 분해할 수 있으며, 메시지 흐름 내에서 호출 과정과 결과를 보여줍니다. Skills & MCP: 각 워크스페이스는 독립적으로 Skills, MCP Server 및 워크스페이스 파일을 구성할 수 있어 재사용 가능한 능력을 축적하기에 적합합니다. 원격 로봇: Feishu / Lark 로봇 브릿지를 지원하며, DingTalk, WeChat 브릿지 입구도 제공하여 휴대폰이나 그룹 채팅을 통해 로컬 Agent 워크플로우를 트리거할 수 있습니다. 기억 및 도구: Chat과 Agent는 기억 능력을 공유할 수 있으며, 웹 검색, 내장 Chat 도구, Agent 추천 등의 보조 기능을 지원합니다. 로컬 우선: 세션, 워크스페이스, 첨부 파일, 설정, Skills 등은 기본적으로 ~/.proma/에 저장되며, JSON / JSONL 파일을 사용하여 조직하고 로컬 데이터베이스에 의존하지 않습니다. 데스크톱 경험: 자동 업데이트, 프록시 설정, 파일 미리보기, 글로벌 단축키, 빠른 작업 창, 음성 입력, 라이트 모드 / 다크 모드 / 시스템 테마 따르기를 지원합니다.

GitHub Releases에서 오픈 소스 버전을 다운로드하세요. 현재 릴리스 노트는 v0.9.12를 기준으로 하며, macOS Apple Silicon, macOS Intel 및 Windows 설치 패키지를 제공합니다.

설치 후 즉시 사용하기를 원하거나 API 설정 비용을 줄이고 싶다면 Proma 상용 버전을 사용할 수도 있습니다. 상용 버전과 오픈 소스 버전은 병행 운영되며, 주요 차이점은 상용 버전이 내장 채널과 구독 플랜을 제공한다는 점입니다.

• Proma를 열고 먼저 환경 검사를 완료하세요. Agent 모드는 로컬 기본 환경, 특히 Git, Node.js / Bun 및 사용 가능한 Shell에 의존합니다.

• 설정 > 채널로 이동하여 최소 하나 이상의 AI 공급업체 채널을 추가하고 Base URL, API Key 및 모델 목록을 입력하세요. - Chat 모드는 OpenAI, Anthropic, Google 또는 OpenAI 호환 프로토콜 채널을 사용할 수 있습니다.

• Agent 모드는 Anthropic 프로토콜 또는 Anthropic 호환 프로토콜 채널(예: Anthropic, DeepSeek, Kimi API, Kimi Coding Plan)이 필요합니다.

• 설정 > Agent로 이동하여 기본 Agent 채널, 모델 및 워크스페이스를 선택하세요. - 기억, 웹 검색, Feishu / DingTalk / WeChat 브릿지가 필요한 경우 설정 페이지의 해당 탭에서 계속 구성하세요.

• 일상적인 질의응답, 설명, 번역, 윤문, 가벼운 코드 토론.

• 첨부 파일 내용을 읽은 후 요약, 개작, 비교.

• 웹 검색 또는 기억 도구를 사용하여 일회성 대화 강화.

• 여러 모델의 출력을 동시에 비교하거나, 서로 다른 시스템 프롬프트를 사용하여 탐색.

• 로컬 파일 수정, 생성, 정리.

• 조사, 보고서 작성, 다단계 작업 처리.

• MCP, Skills, Shell, Git, 프로젝트 파일 등 외부 컨텍스트 사용.

• 권한 확인, 계획 모드, 백그라운드 작업 또는 원격 로봇의 지속적인 후속 조치가 필요한 작업.

간단히 말해: 답변이 필요할 때는 Chat을 사용하고, 행동과 결과물이 필요할 때는 Agent를 사용하세요.

Chat으로 가볍지만 실제적인 분석 작업을 처리합니다: 독자의 관심사를 정리하고, 비교표를 생성하며, 첫 화면의 카피라이팅을 빠르게 확정합니다.

Agent는 워크스페이스 내에서 파일을 읽고, 작업을 진행하며, 표 형식의 결론을 출력하고, 재사용 가능한 파일을 우측 워크스페이스 패널에 보관합니다.

각 워크스페이스에는 전용 Skills를 축적할 수 있습니다. 스크린샷의 feedback-synthesis는 사용자 피드백, 인터뷰 기록 및 issue를 주제, 증거 및 우선순위 제안으로 통합하는 데 사용됩니다.

동일한 워크스페이스에서 stdio / HTTP MCP Server를 관리할 수 있으며, 필요에 따라 활성화 또는 비활성화하여 Agent가 서로 다른 프로젝트에서 서로 다른 외부 컨텍스트를 얻을 수 있도록 합니다.

Proma는 Doubao의 스트리밍 음성 입력 기능을 지원하며, Proma 내부 및 외부에서 모두 사용할 수 있습니다:

• Proma 내부 사용: Ctrl + `로 인식을 트리거하며, 다시 누르면 인식이 종료되고 Proma 내부의 해당 입력창으로 자동 입력됩니다.
• Proma 외부 사용: Ctrl + `로 인식을 트리거하며, 다시 누르면 인식이 종료되고 현재 커서가 있는 위치로 자동 입력됩니다. 커서가 없는 경우 기본적으로 클립보드에 기록됩니다.

공급업체	Chat	Agent	프로토콜 설명
Anthropic	지원	지원	Anthropic Messages API
...

Agent 모드는 하부에서 Claude Agent SDK를 사용하므로, 현재 채널(Channel)에서 Anthropic 또는 Anthropic 호환 프로토콜을 제공해야 합니다. Chat 모드는 @proma/core의 Provider Adapter를 통해 서로 다른 프로토콜을 통합하여 접속합니다.

Proma는 백업, 마이그레이션 및 문제 해결을 용이하게 하기 위해 로컬 파일 저장 방식을 채택합니다.

~/.proma/
├── channels.json
├── conversations.json
...

API Key는 Electron의 safeStorage를 통해 암호화된 후 channels.json에 기록됩니다. Proma는 로컬 데이터베이스를 사용하지 않으며, 핵심 데이터 구조는 JSON 설정과 JSONL 추가 로그(append log)를 중심으로 구성됩니다.

Proma는 Bun workspace monorepo입니다.

proma-v2/
├── packages/
│ ├── shared/ # 공유 타입, IPC 상수, 설정, 유틸리티 함수
...

현재 주요 패키지 버전:

패키지	버전	역할
@proma/electron	0.9.12	Electron 데스크톱 애플리케이션
@proma/shared	0.1.17	공유 타입, IPC 상수, 설정 및 유틸리티
@proma/core	0.2.9	Provider Adapter, SSE, Shiki 하이라이팅
@proma/ui	0.1.3	공유 React UI 컴포넌트

자주 사용하는 명령:

# 의존성 설치
bun install
# 개발 모드: Vite + Electron + Hot Reload 자동 실행
...

Electron 서브 애플리케이션 내에서도 더 세분화된 스크립트를 제공합니다:

cd apps/electron
bun run dev:vite
bun run dev:electron
...

계층	기술
런타임	Bun
...

Proma의 핵심 통신 경로는 다음과 같습니다:

shared 타입 및 IPC 상수
-> main/ipc.ts에서 핸들러 등록
-> preload/index.ts에서 window.electronAPI 노출
...

메인 프로세스 서비스는 apps/electron/src/main/lib/에 집중되어 있습니다:

• agent-orchestrator.ts: Agent 오케스트레이션, 환경 변수, SDK 호출, 이벤트 스트림, 에러 처리.
• agent-session-manager.ts: Agent 세션 인덱싱 및 JSONL 메시지 영속화.
• agent-workspace-manager.ts: 워크스페이스, MCP, Skills 및 워크스페이스 파일 관리.
• chat-service.ts: Chat 스트리밍 호출, Provider Adapter, 도구 활동.
• conversation-manager.ts: Chat 세션 인덱싱 및 메시지 저장.
• channel-manager.ts: 채널 CRUD, API Key 암호화, 연결 테스트, 모델 가져오기.
• feishu-bridge.ts / dingtalk-bridge.ts / wechat-bridge.ts: 원격 봇 브릿지.
• memory-service.ts, chat-tool-*, document-parser.ts, workspace-watcher.ts: 메모리, 도구, 문서 파싱 및 파일 감시.

렌더러 프로세스는 Jotai를 사용하여 상태를 관리하며, 주요 atoms는 apps/electron/src/renderer/atoms/에 위치합니다. Agent IPC 리스너는 애플리케이션 최상단에 전역으로 마운트되어, 페이지 전환 시 스트리밍 이벤트, 권한 요청 또는 백그라운드 작업 상태가 유실되는 것을 방지합니다.

@anthropic-ai/claude-agent-sdk는 0.2.113+ 버전부터 플랫폼 네이티브 바이너리(native binary) 방식으로 배포됩니다. Proma의 esbuild 설정은 해당 SDK를 external로 표시하며, electron-builder.yml

SDK 메인 패키지와 플랫폼별 서브 패키지를 함께 설치 패키지에 포함합니다.

패키징 설정을 수정할 때는 다음 사항을 특별히 확인하십시오:

• 메인 프로세스 (Main Process) esbuild 설정에서 --external:@anthropic-ai/claude-agent-sdk를 유지해야 합니다.
• apps/electron/package.json의 optionalDependencies에 대상 플랫폼의 SDK 서브 패키지가 포함되어 있어야 합니다.
• apps/electron/electron-builder.yml의 files에 SDK 메인 패키지와 플랫폼별 서브 패키지가 포함되어 있어야 합니다.
• 기타 일반적인 npm 의존성 (dependencies)은 보통 esbuild를 통해 main.cjs에 포함되어야 하며, 임의로 external로 설정하지 마십시오.

더 완전한 엔지니어링 규약은 AGENTS.md를 참조하십시오.

버그 수정, 문서 보완, 테스트 추가, 사용자 경험 개선을 환영하며, 실제 시나리오를 바탕으로 새로운 Skills, MCP 설정 또는 Agent 워크플로우를 제출하는 것도 환영합니다.

PR (Pull Request)을 제출하기 전에 다음 사항을 먼저 확인하는 것을 권장합니다:

• 스크립트 실행 시 Bun을 사용하며, npm / pnpm lockfile을 혼용하지 마십시오.
• 상태 관리 (State Management)에는 Jotai를 사용합니다.
• 가능한 한 로컬 우선 (Local-first) 방식을 유지하며, 설정 파일과 JSON / JSONL 사용을 우선시합니다.
• TypeScript 사용 시 any를 사용하지 않으며, 객체 구조는 interface 사용을 우선합니다.
• IPC (Inter-Process Communication)를 새로 추가할 때는 shared 타입, main handler, preload bridge 및 renderer 호출을 동시에 수정해야 합니다.
• 패키지 동작에 영향을 줄 경우 해당 패키지의 patch 버전을 올립니다.
• 테스트로 커버할 수 있는 동작은 최대한 테스트를 보완하십시오. 특히 공유 로직, IPC 계약 (contract) 및 지속성 (persistence) 포맷이 중요합니다.

Proma는 현재 PR 보상 계획을 운영하고 있습니다. PR 제출 시 설명란에 이메일을 남겨주시면 추후 지급이 용이합니다.

• Shiki: 코드 하이라이팅 (Code Highlighting).
• Beautiful Mermaid: Mermaid 다이어그램 렌더링.
• Cherry Studio: 다양한 공급업체의 데스크톱 AI 제품으로부터 얻은 영감.
• Lobe Icons: AI / LLM 브랜드 아이콘.
• Craft Agents OSS: Agent SDK 통합 패턴 참조.
• MemOS: 메모리 능력 참조 및 통합.

현재 workspace 패키지는 package.json에 Apache-2.0으로 선언되어 있습니다. 루트 디렉토리의 라이선스 파일이 아직 모두 갖춰지지 않았을 경우, 저장소의 실제 배포 내용과 각 패키지의 선언을 기준으로 삼으십시오.