kcosr/assistant

⚠️ 실험적 소프트웨어
이 소프트웨어는 교육적 목적으로 커뮤니티와 공유되는 개인용 소프트웨어입니다. 질문과 기여는 환영하지만, 안정성이나 기술 지원을 기대하지는 마십시오.

패널 기반의 플러그인 시스템, 멀티 에이전트 CLI 통합, 그리고 텍스트/음성 UI를 갖춘 개인용 AI 어시스턴트입니다. 플러그인은 패널과 동작을 정의하여 에이전트가 목록, 노트, diff 리뷰(diff reviews)에서 협업하거나 사용자가 제공한 커스텀 플러그인으로 앱을 확장할 수 있게 합니다. OpenAI 호환 세션은 현재 기능이 제한적이며, 향후 badlogic/pi-mono 에이전트 SDK와의 통합으로 대체될 예정입니다.

• 주요 기능 (Features)
• 빠른 시작 (Quick Start)
• 저장소 구조 (Repository Layout)
• 문서 (Documentation)
• 외부 통합 (External Integrations)
• 설정 (Configuration)
• 개발 (Development)
• 아키텍처 (Architecture)
• 라이선스 (License)

텍스트 채팅 (Text chat) - 스트리밍 응답 지원
음성 입력 (Voice input) - 브라우저 기반 음성 인식 (Web Speech API) 사용
음성 출력 (Voice output) - OpenAI TTS 또는 ElevenLabs 스트리밍 TTS (선택 사항)를 통해 제공
CLI 에이전트 통합 (CLI agent integrations) - 내장된 프로바이더와 함께 Claude, Codex, Pi 지원
예약된 세션 (Scheduled sessions) - cron 기반의 CLI 실행을 위한 기능
패널 플러그인 (Panel plugins) - 목록, 노트, diff 리뷰 및 커스텀 워크플로우용
도구 통합 (Tool integration) - stdio를 통한 MCP (Model Context Protocol) 활용
내장 세션 도구 (Built-in session tools) – 에이전트가 세션을 목록화, 검색, 생성, 전환, 이름 변경 및 고정(pin)할 수 있음
지속성 세션 (Persistent sessions) – JSONL 이벤트 로그 및 선택적인 이름 지정/고정 기능 포함
멀티 클라이언트 지원 (Multi-client support) – 여러 브라우저 창이 하나의 세션을 공유 가능
테마 + 글꼴 설정 (Theme + font preferences) (자동/라이트/다크 + 프리셋)

# 저장소 복제 (Clone the repository)
git clone https://github.com/kcosr/assistant
cd assistant
...

내장된 설정에는 Claude Code, Codex, Pi CLI 에이전트가 포함되어 있습니다. 모든 옵션이 포함된 전체 설정 예시는 packages/agent-server/data/config.example.json을 참조하십시오.

환경 변수를 사용하여 기본 경로를 재정의할 수 있습니다:

# 커스텀 데이터 디렉토리 사용 (세션, 이벤트, 설정)
export DATA_DIR=/path/to/data
# 특정 설정 파일 사용
...

서버는 기본적으로 ${DATA_DIR}/config.json에서 설정을 찾거나, APP_CONFIG_PATH에서 설정을 찾습니다.

설정되어 있다면.

플러그인은 스킬 (skills)을 지원하는 CLI 에이전트(예: Claude Code, Codex, Pi)에서 사용할 수 있도록 스킬로 내보낼 수 있습니다:

# 모든 플러그인 스킬을 특정 디렉토리로 빌드
npm run build:plugins -- --skills-dir /tmp/skills
# 특정 스킬을 에이전트의 스킬 디렉토리로 복사
...

일부 스킬에는 CLI 바이너리가 포함되어 있습니다. 스킬 디렉토리를 PATH에 추가하거나, AGENTS.md에서 전체 경로로 CLI를 참조하십시오:

# 옵션 1: PATH에 추가 (~/.bashrc 또는 ~/.zshrc)
export PATH="$PATH:$HOME/.pi/skills/notes:$HOME/.pi/skills/lists"
# 옵션 2: AGENTS.md / SKILL.md 문서에서 전체 경로 참조

단축키	동작
Ctrl/Cmd + K	명령 팔레트 (command palette) 열기
Ctrl/Cmd + ] / Ctrl/Cmd + [	패널 간 포커스 전환
Ctrl + P	레이아웃 탐색 모드 (layout navigation mode) 토글
Ctrl + H	헤더 패널 탐색 모드 (header panel navigation mode) 토글
Ctrl + Shift + S	활성 패널 분할 (배치 모드)
Ctrl + I	텍스트 입력 포커스 토글
Ctrl + A/C/D/F/L/N/S/T	마지막으로 사용된 아티팩트/채팅/diff/파일/리스트/노트/세션/타임 트래커에 포커스 (없을 경우 모달 오픈)
Ctrl + R	음성 녹음 토글 (사용 가능한 경우)
Cmd + Shift + S (macOS)	세션 사이드바 (sessions sidebar) 토글
Cmd/Ctrl + Shift + C	채팅 패널 토글
Cmd/Ctrl + Shift + ↑/↓	채팅의 맨 위/맨 아래로 이동
Ctrl + Shift + Cmd + W (macOS) / Ctrl + Shift + Alt + W (기타)	패널 닫기 (플레이스홀더로 대체)
Ctrl + Shift + Cmd + X (macOS) / Ctrl + Shift + Alt + X (기타)	레이아웃에서 패널 제거
Enter	활성 빈 패널 대체
Shift + Enter	모달 폼 제출 (예: 노트/리스트의 태그 입력창에서)
Cmd + Click (macOS) / Ctrl + Click (기타)	채팅이 아닌 패널에 포커스 (채팅 패널은 일반 클릭으로 포커스됨)
Tab / Shift + Tab	사이드바와 입력창 사이의 포커스 전환 (입력창이 비어 있을 때)
Esc	활성 작업 취소 (모바일에서는 사이드바가 열려 있으면 닫음; 고정되거나 모달 형태의 채팅 패널에서는 대신 패널을 닫음)

레이아웃 탐색 모드(layout navigation mode)에서: 화살표 키로 패널 간 이동, Enter

선택, Esc

종료, Tab

탭 순환, m

분할 보기 (split view) 전환, 1-9

가시적 패널 선택, 0

페이지 순환.

헤더 탐색 모드 (header navigation mode)에서: ←/→

(또는 A/D) 헤더 패널 순환, Enter

/↓

활성화, Esc

종료, 1-9

가시적 패널 선택, 0

페이지 순환.

분할 배치 모드 (split placement mode)에서: 화살표 키 또는 WASD로 영역 선택, Enter

확인, Esc

취소.

세션 사이드바 (포커스 시):

Arrow Up/Down (위/아래 화살표)

– 세션 간 이동 (선택 영역은 포커스를 따름) Enter

– 입력창 포커스 t

– 고정 (pin) 토글 d

/Delete

/Backspace

– 세션 삭제 (확인 절차 포함) c

– 기록 삭제 (확인 절차 포함)

리스트 패널 항목 선택:

Click (클릭)

– 항목 선택 (설정 메뉴에서 활성화된 경우) Shift + Click

– 마지막 선택 항목부터 클릭한 항목까지 범위 선택 Cmd + Click (macOS) / Ctrl + Click (기타) – 개별 항목 선택 토글 Double-click (더블 클릭)

– 항목 편집 Arrow Up/Down (위/아래 화살표)

– 선택 이동 Shift + Arrow Up/Down (Shift + 위/아래 화살표)

– 선택 범위 확장 Enter

– 포커스된 항목 편집 Space

– 선택 항목의 완료 상태 토글 n

– 항목 추가 a

– AQL 모드 토글 w

/s

– 포커스된 항목을 위/아래로 이동 t

/b

– 포커스된 항목을 맨 위/맨 아래로 이동 p

– 고정 (pin) 토글 Cmd/Ctrl + C

/X

/V

– 리스트 항목 복사 / 잘라내기 / 붙여넣기 (리스트 간 이동 가능) d

– 선택 항목 삭제 (확인 절차 포함) Esc

– 선택 해제

리스트/노트 브라우저 (컬렉션 뷰):

Arrow keys (화살표 키)

– 포커스 이동 Enter

– 포커스된 항목 열기 p

– 고정 (pin) 토글

커맨드 팔레트 (Command palette, 열려 있을 때):

Arrow Up/Down (위/아래 화살표)

– 포커스 이동 Enter

– 선택 항목 실행 Shift + Enter

– 활성 패널 교체 (가능한 경우) →

– 액션 메뉴 열기 Esc

– 팔레트 또는 메뉴 닫기

팔레트 명령어:

/pinned

– 고정된 리스트 및 노트 표시 /favorites

– 즐겨찾는 리스트 및 노트 표시

노트 패널: 텍스트를 드래그하여 선택한 후, Shift를 누른 상태로 떼면 선택 영역을 에이전트 컨텍스트 (agent context)에 추가합니다.

ElevenLabs 스트리밍 텍스트 음성 변환 (text-to-speech)을 활성화하려면 (참고: 비용이 많이 발생할 수 있음):

export TTS_BACKEND=elevenlabs
export ELEVENLABS_API_KEY=<key>
export ELEVENLABS_TTS_VOICE_ID=VUGQSU6BSEjkbudnJbOj
...

Git 버전 관리 (Git versioning)는 리스트, 노트, 타임 트래커 (time-tracker) 플러그인에 대해 기본적으로 활성화되어 있습니다. 이는 정기적인 간격으로 플러그인의 데이터 디렉토리에 변경 사항을 자동으로 커밋하여 버전 기록을 제공합니다.

플러그인의 Git 버전 관리를 비활성화하려면, gitVersioning 키에서 enabled: false를 설정하거나 삭제하십시오.

{
"plugins": {
"lists": {
...

기본 간격은 1분입니다. intervalMinutes를 통해 조정할 수 있습니다.

AI 에이전트가 어시스턴트 기술 (assistant skills)을 이해하고 사용할 수 있도록 프로젝트 또는 사용자 수준의 AGENTS.md에 다음 내용을 추가하십시오:

## Assistant Workspace
사용자는 노트, 리스트, 시간 추적 등을 위한 패널이 포함된 개인용 어시스턴트 워크스페이스를 실행합니다. **사용자가 명시적으로 "assistant"를 언급하거나 어시스턴트 워크스페이스를 참조할 때만 이 기술들을 사용하십시오.** 그렇지 않으면 표준 파일 및 셸 (shell) 작업을 사용하십시오.
### Skills
...

npm 워크스페이스 (npm workspaces)로 관리되는 모노레포 (Monorepo):

패키지	설명
packages/agent-server/	Node.js 백엔드 – WebSocket 서버, OpenAI 연동, TTS, MCP 도구
packages/web-client/	브라우저 클라이언트 – 채팅 UI, 음성 입력, 오디오 재생
packages/assistant-cli/	플러그인 CLI 생성을 위해 사용되는 내부 런타임 (runtime)
packages/shared/	공유 타입 (types), 프로토콜 정의, 오디오 프레임 헬퍼
packages/plugins/	플러그인 패키지 (코어, 공식, 예시)
packages/coding-executor/	코드 실행 도구 (bash, read, write, edit, grep, find)
packages/coding-sidecar/	샌드박스 (sandboxed) 코드 실행을 위한 컨테이너 사이드카 (sidecar)
packages/desktop/	Tauri 데스크톱 앱 래퍼 (wrapper)
packages/mobile-web/	Capacitor 모바일 앱 래퍼 (wrapper)
packages/notify-proxy/	푸시 알림 프록시 서버
packages/push-cli/	푸시 알림 전송을 위한 CLI
docs/	설계 문서 및 사양서

전체 문서 맵은 docs/index.md를 참조하십시오.

문서	설명
UI Specification (UI 사양서)	모든 클라이언트 구현체(web, Android, iOS)에 대한 공통 UI 동작 및 레이아웃 요구사항. 패널 레이아웃, 반응형 동작, 툴바 컨트롤 및 상호작용 패턴을 다룹니다.
...
문서	설명
---	---
Agents (에이전트)	에이전트 아키텍처 및 설정. 에이전트 정의, 세션, 도구 허용 목록(allowlists), 그리고 에이전트와 대화 간의 관계를 다룹니다.
...
문서	설명
---	---
Agent Server (에이전트 서버)	서버 설정, 플러그인 시스템 및 MCP 도구 호스팅.
...
서비스	API
---	---
OpenAI	Chat Completions (streaming)
OpenAI	Audio Speech
ElevenLabs	WebSocket Streaming TTS
MCP Server	JSON-RPC 2.0 over stdio

환경 변수 및 config.json 스키마(CLI 에이전트 제공자 포함)에 대해서는 docs/CONFIG.md를 참조하십시오.

전체 예제는 data/config.example.json에 있습니다.

# 테스트 실행
npm test
# Lint
...

┌─────────────────────────────────────────┐
┌─────────────────┐ WebSocket + HTTP │ Agent Server │
│ Web Client │◄──────────────────►│ (Node.js) │
...

클라이언트와 서버는 다음을 사용하여 WebSocket을 통해 통신합니다:

JSON messages (JSON 메시지): 제어, 텍스트 및 메타데이터용
Binary frames (이진 프레임): 오디오 데이터 (TTS 출력)용

메시지 타입 정의에 대해서는 packages/shared/src/protocol.ts를 참조하십시오.

Sessions index (세션 인덱스): ${DATA_DIR}/sessions.jsonl

Session event logs (세션 이벤트 로그): ${DATA_DIR}/sessions/<sessionId>/events.jsonl

이벤트 로그는 사용자 메시지, 어시스턴트 출력, 도구 호출/결과 및 에이전트 콜백을 포함하는 추가 전용(append-only) ChatEvent 레코드입니다.

MIT