Cratos - AI-Powered Personal Assistant cargo build # 빌드# 최적화 빌드 (thin LTO, ~5분)# 배포 빌드 (full LTO, ~10분)test --workspace # 전체 테스트 (1,200+ tests)# 린트# 빠른 타입 체크# 대화형 설정 마법사# 서버 시작 (기본 포트 19527)# 대화형 TUI 채팅 cp target/dev-release/cratos /usr/local/bin/ # 설치 (dev-release)# 설치 (release)> /tmp/cratos-server.log 2>&1 & # 백그라운드 서버 Cratos는 Telegram/Slack/Discord에서 자연어로 명령을 내리면 AI 에이전트가 이해하고, 정보를 모으고, 실행하고, 결과를 보고하는 Rust 기반 AI 어시스턴트 입니다.
기능
설명
경량 설치 Docker/PostgreSQL 불필요, SQLite 내장, 단일 바이너리
자동 스킬 생성 사용 패턴 학습 → 자동 스킬 생성
리플레이 (되감기) 타임라인 + 재실행 + dry-run
모델 라우팅 작업별 자동 모델 선택, 비용 최적화
원격 개발 E2E Issue → PR 완전 자동화 (cratos develop)
Tool Doctor 자기 진단 + 해결 체크리스트
비용/할당량 모니터링 CostTracker + QuotaTracker, 프로바이더별 사용량 추적
TUI 채팅 ratatui 기반 대화형 터미널 인터페이스 (설정 모달 F5)
스케줄러 ProactiveScheduler (Cron/Interval/OneTime)
REST API + WebSocket 51개 REST 엔드포인트, /ws/chat, /ws/events 실시간 통신
음성 어시스턴트 STT(Whisper) + TTS, 실시간 음성 대화
브라우저 제어 Chrome 확장 + CDP 통합, 탭/스크린샷 제어
디바이스 페어링 PIN 기반 E2E 암호화 디바이스 연동
ACP/MCP 브릿지 IDE 통합 (stdin/stdout JSON-lines)
네이티브 앱 제어 app_control — macOS AppleScript/JXA 자동화 (Notes, Reminders 등)
언어 : Rust 1.88+ (#![forbid(unsafe_code)])런타임 : Tokio (비동기)웹 : Axum 0.7DB : SQLite (sqlx, 내장), Redis (세션용, 선택)채널 : teloxide (Telegram), slack-morphism (Slack), serenity (Discord), matrix-sdk (Matrix)LLM : 13개 프로바이더 (OpenAI, Anthropic, Gemini, DeepSeek, Groq, Fireworks, SiliconFlow, GLM, Qwen, Moonshot, Novita, OpenRouter, Ollama)임베딩/검색 : tract-onnx (pure Rust ONNX 임베딩), usearch (벡터 인덱스)오디오 : cpal, rodio, hound + candle 0.8.x (로컬 Whisper STT)Web UI : Leptos (WASM), Tailwind CSSTUI : ratatui 0.29, tui-textarea 0.7, tui-markdown =0.3.5
cratos/
├── apps/
│ ├── web/ # Leptos Web UI (WASM)
│ ├── android/ # Android 앱
│ ├── ios/ # iOS 앱
│ └── desktop/ # 데스크톱 앱
├── assets/
│ ├── chrome-extension/ # Chrome 확장 (CDP 통합, WebSocket Gateway)
│ └── a2ui/ # UI 자산
├── config/
│ ├── default.toml # 기본 설정 (수정 금지)
│ ├── local.toml # 사용자 오버라이드 (gitignored)
│ ├── pantheon/ # 페르소나 TOML (14개)
│ └── decrees/ # 율법, 계급, 개발 규칙
├── crates/ # Rust workspace (11개 크레이트)
│ ├── cratos-core/ # 오케스트레이션, 보안, 자격증명, 이벤트버스
│ ├── cratos-channels/ # 채널 어댑터 (Telegram, Slack, Discord, Matrix)
│ ├── cratos-tools/ # 도구 레지스트리, 샌드박스, exec/bash
│ ├── cratos-llm/ # LLM 프로바이더 13개, 임베딩, 쿼터 추적
│ ├── cratos-replay/ # 리플레이 엔진 (SQLite 이벤트 스토어)
│ ├── cratos-skills/ # 자동 스킬 생성, 시맨틱 라우팅
│ ├── cratos-search/ # 벡터 검색, 시맨틱 인덱싱
│ ├── cratos-memory/ # Graph RAG 대화 메모리
│ ├── cratos-crypto/ # E2E 암호화, 키 관리
│ ├── cratos-audio/ # 음성 제어 (STT/TTS)
│ └── cratos-canvas/ # 캔버스 (future)
├── src/
│ ├── main.rs # 엔트리포인트
│ ├── cli/ # CLI 모듈 (17개 서브커맨드)
│ │ ├── mod.rs # Commands enum 정의
│ │ ├── setup/ # cratos init (대화형 마법사)
│ │ ├── tui/ # TUI 채팅 (app, event, ui, settings)
│ │ ├── config.rs # cratos config {list,get,set,reset,edit}
│ │ ├── skill/ # cratos skill {list,show,enable,disable}
│ │ ├── data.rs # cratos data {stats,clear}
│ │ ├── develop.rs # cratos develop (Issue → PR)
│ │ ├── voice.rs # cratos voice (음성 어시스턴트)
│ │ ├── browser_ext.rs # cratos browser {extension,tabs,open,screenshot}
│ │ ├── pair.rs # cratos pair {start,devices,unpair}
│ │ ├── security.rs # cratos security audit
│ │ ├── doctor.rs # cratos doctor
│ │ ├── quota.rs # cratos quota
│ │ ├── pantheon.rs # cratos pantheon
│ │ ├── chronicle.rs # cratos chronicle
│ │ └── decrees.rs # cratos decrees
│ ├── api/ # REST API (17개 모듈, 51개 엔드포인트)
│ │ ├── config/ # GET/PUT /api/v1/config
│ │ ├── executions/ # /api/v1/executions/*
│ │ ├── sessions/ # /api/v1/sessions/*
│ │ ├── scheduler/ # /api/v1/scheduler/*
│ │ ├── skills.rs # /api/v1/skills/*
│ │ ├── browser.rs # /api/v1/browser/*
│ │ ├── pairing.rs # /api/v1/pair/*
│ │ ├── graph.rs # /api/v1/graph/*
│ │ ├── pantheon.rs # /api/v1/pantheon/*
│ │ ├── auth.rs # /api/auth/google/*
│ │ ├── health.rs # /health, /metrics
│ │ └── ...
│ ├── server/ # 서버 초기화 (8개 파일로 모듈화)
│ ├── acp/ # ACP/MCP 브릿지 (IDE 통합)
│ ├── middleware/ # 인증, 레이트 리미팅
│ └── websocket/ # /ws/chat, /ws/events
├── migrations/ # DB 마이그레이션
└── PRD.md # 상세 요구사항
~/.cratos/ # 데이터 디렉토리 (자동 생성)
├── cratos.db # SQLite: 이벤트, 실행 기록
├── skills.db # SQLite: 스킬, 패턴
├── memory.db # SQLite: Graph RAG 대화 메모리
├── vectors/memory/ # HNSW 벡터 인덱스
└── chronicles/ # 페르소나별 전공 기록
설정 우선순위: .env > config/local.toml > config/default.toml
cratos config list # 카테고리별 설정 조회# 단일 값 조회set llm.default_provider glm # config/local.toml에 저장# 기본값 복원# $EDITOR로 편집 .env 변수명 규칙: CRATOS_LLM__DEFAULT_PROVIDER (이중 언더스코어 __로 중첩 구분)
TUI에서 F5로 설정 모달 열기/닫기 가능.
명령어
설명
/cratos-setup프로젝트 초기 설정
/develop원격 개발지시 (Issue → PR)
/replay실행 기록 조회/재실행
명령어
설명
cratos init통합 대화형 설정 마법사
cratos serve서버 시작 (기본 포트 19527)
cratos doctor시스템 진단
cratos tui [--persona NAME]대화형 TUI 채팅
cratos quota [--json] [--watch]프로바이더 할당량/비용 조회
cratos config {list,get,set,reset,edit}설정 관리
명령어
설명
cratos develop <issue> [--repo URL] [--dry-run]Issue → PR 자동화
cratos skill {list,show,enable,disable}스킬 관리
cratos data stats데이터 통계 (레코드 수, 파일 크기)
cratos data clear [sessions|memory|history|chronicles|vectors|skills]데이터 삭제
cratos security audit [--json]보안 감사
명령어
설명
cratos voice [--lang ko]음성 어시스턴트
cratos browser extension {install,path}Chrome 확장 관리
cratos browser {tabs,open,screenshot}브라우저 제어
cratos pair {start,devices,unpair}디바이스 페어링 (PIN 기반)
cratos acp [--token T] [--mcp]ACP/MCP 브릿지 (IDE 통합)
명령어
설명
cratos pantheon {list,show,summon,dismiss}페르소나 관리
cratos pantheon skill {list,show,claim,release}페르소나-스킬 바인딩
cratos pantheon skill {leaderboard,summary,sync}스킬 숙련도 조회/동기화
cratos decrees show {laws,ranks,warfare,alliance,...}율법/규칙 조회
cratos decrees validate규칙 준수 검증
cratos chronicle {list,show,log,promote,clean}전공 기록 관리
그리스/북유럽 신화 기반 3-레이어 에이전트 조직 체계:
Layer
이름
목적
WHO
Pantheon 에이전트 페르소나
HOW
Decrees 율법, 계급, 개발 규칙
WHAT
Chronicles 전공 기록 및 평가
코어 : Cratos (Orchestrator, Lv255), Athena (PM), Sindri (Dev), Heimdall (QA), Mimir (Researcher)
확장 : Odin (PO), Hestia (HR), Norns (BA), Apollo (UX), Freya (CS), Tyr (Legal), Nike (Marketing), Thor (DevOps), Brok (Dev)
@mention 라우팅: @athena 이번 스프린트 계획해줘, @sindri API 구현해줘
Method
Path
설명
GET
/health헬스체크
GET
/health/detailed상세 헬스체크 (DB/Redis 상태)
GET
/metricsPrometheus 형식 메트릭
GET/PUT
/api/v1/config설정 조회/변경 (카테고리별)
GET
/api/v1/tools도구 목록
GET
/api/v1/quota프로바이더 할당량
Method
Path
설명
GET
/api/v1/executions실행 목록
GET
/api/v1/executions/:id실행 상세
GET
/api/v1/executions/:id/replay리플레이 이벤트
POST
/api/v1/executions/:id/rerun재실행
GET
/api/v1/executions/stats실행 통계
Method
Path
설명
GET/POST
/api/v1/sessions세션 목록/생성
POST
/api/v1/sessions/:id/messages메시지 송신
POST
/api/v1/sessions/:id/cancel실행 취소
POST
/api/v1/sessions/init-e2eE2E 암호화 초기화
POST
/api/v1/sessions/decrypt메시지 복호화
Method
Path
설명
GET
/api/v1/skills스킬 목록
GET/DELETE
/api/v1/skills/:id스킬 조회/삭제
POST
/api/v1/skills/:id/enable스킬 활성화
POST
/api/v1/skills/:id/disable스킬 비활성화
GET
/api/v1/skills/:id/export스킬 내보내기
POST
/api/v1/skills/export/bundle번들 내보내기
POST
/api/v1/skills/import스킬 임포트
GET
/api/v1/registry/search레지스트리 검색
POST
/api/v1/registry/install레지스트리에서 설치
Method
Path
설명
GET/POST
/api/v1/scheduler/tasks스케줄러 작업 관리
GET
/api/v1/pantheon페르소나 목록
GET
/api/v1/pantheon/:name페르소나 상세
GET
/api/v1/graphGraph RAG 데이터
GET
/api/v1/graph/stats그래프 통계
GET/POST/DELETE
/api/v1/pair/*디바이스 페어링
GET/POST
/api/v1/browser/*브라우저 제어
GET
/api/v1/dev/sessions개발 세션 목록
GET
/api/auth/google/loginGoogle OAuth 로그인
Path
설명
/ws/chat대화형 채팅
/ws/events이벤트 스트림 (실시간 알림)
#![forbid(unsafe_code)] — unsafe 금지Result<T, E> 명시적 에러 처리tracing 기반 구조화 로깅Conventional Commits 형식
1,000줄 초과 파일 금지 (모듈 분리)
#![warn(missing_docs)] — 모든 pub 항목에 doc comment 필수 (cratos-core, cratos-channels)
빌드 프로필 : --release는 full LTO + codegen-units=1로 ~10분. 일상 테스트는 --profile dev-release 사용 (~5분, thin LTO)tui-markdown 버전 : 반드시 =0.3.5 사용. 0.3.7은 ratatui-core 0.1.0 의존 → ratatui 0.29와 타입 불일치환경변수 구분자 : CRATOS_LLM__DEFAULT_PROVIDER (이중 언더스코어 __). config-rs의 Environment::with_prefix("CRATOS").separator("__") 사용UTF-8 자르기 : &text[..max_len]은 한글 등 멀티바이트 중간에서 패닉. char_indices() 사용 필수candle 0.8.x : 최신 문서와 API 차이 있음. VarBuilder::from_buffered_safetensors 사용 (0.9의 from_safetensors 없음)DuckDuckGo 웹 검색 : reqwest(rustls)는 JA3 핑거프린팅으로 차단됨. tokio::process::Command로 시스템 curl 사용Gemini thought_signature : Gemini 3 모델은 FunctionCall에 thoughtSignature 반환 → 다음 요청에 반드시 보존config/local.toml : config-rs가 File::with_name("config/local")로 자동감지하므로 .json 파일이 있으면 TOML 설정을 오염시킴도구 추가/제거 시 동기화 필수 : builtins/mod.rs 등록 + builtins/mod.rs 테스트 카운트 + tests/integration_test.rs expected_tools 배열 및 카운트 — 3곳 모두 업데이트cratos-tools Error 변형명 : Execution (not ExecutionFailed), PermissionDenied (not SecurityViolation), InvalidInput — crates/cratos-tools/src/error.rs 참조ToolDoctor Alternative.tool_name : Option<String> 타입 — .as_str() 아니라 .as_deref() 사용is_tool_refusal 테스트 위치 : sanitize.rs 함수지만 테스트는 orchestrator/tests.rs에 있음도구 설명 품질 = 자율성 : LLM이 도구 설명만 보고 자율 판단하므로, 모든 도구 설명 150자 이상 유지. 사용 시점/제약/예시 포함 필수to_llm_tools() risk 프리픽스 : RiskLevel::High 도구는 자동으로 [risk: high] 프리픽스 추가됨 (registry.rs)Tool Doctor _diagnosis 필드 : 소프트 실패 시 output JSON에 _diagnosis 힌트 자동 주입 → LLM이 대안 도구 인식 (tool_execution.rs)반성(Reflection) 프롬프트 : 연속 2회 도구 실패 시 [reflection] 시스템 메시지 자동 주입 (process.rs)app_control 보안 : BLOCKED_PATTERNS로 do shell script, System Preferences, password 등 차단. 새 패턴 추가 시 app_control.rs 상수 수정도구 설명에 차단+대안 명시 : LLM은 도구 설명만 보고 판단 → 차단되는 명령어 카테고리, "do NOT use X, use Y instead" 대안 안내, 올바른 파라미터 예시를 반드시 포함. 미명시 시 LLM이 차단된 명령어를 반복 시도함exec args 따옴표 : Command::new()는 셸 없이 실행 → LLM이 보내는 셸 스타일 따옴표("arg", 'arg')가 리터럴로 전달됨. strip_shell_quotes()가 자동 스트리핑 처리 (exec/tool.rs)Orchestrator 내부 메시지 영어 필수 : process.rs의 Message::user()/Message::system() (nudge, reflection 등)는 LLM 프로바이더에 전달되므로 반드시 영어로 작성. 사용자 응답 언어와 무관Orchestrator continuation nudge : LLM이 다단계 작업 중 텍스트만 반환(is_final)하면 continuation_nudged 플래그로 1회 재촉 후 계속 진행 (process.rs). 기존 nudge: tool refusal(1st iteration), empty response after toolsdocs/ 전체 동기화 : 기능 추가/제거 시 docs/ 하위 26개 문서(ko+en) 모두 확인 필수. SETUP_GUIDE 도구 수, USER_GUIDE 기능 섹션, TEST_GUIDE_DEV 테스트 구조, BROWSER_AUTOMATION 액션 목록, SKILL_AUTO_GENERATION 카테고리 등절대경로 커밋 금지 : .claude/agents/, .cratos/skills/ 등 커밋 대상 파일에 ~/.claude/projects/-Volumes-... 같은 사용자별 절대경로 사용 금지. 프로젝트 내 참조는 .serena/memories/ 상대경로 사용서버 재시작 플로우 : cargo build --profile dev-release -p cratos → cp target/dev-release/cratos /usr/local/bin/ → pkill -f "cratos serve" → sleep 2 → nohup cratos serve > /tmp/cratos-server.log 2>&1 & → sleep 5 → curl localhost:19527/health (5초 미만이면 exit code 7)GitHub Actions 사용량 주의 : Free tier 월 2,000분. release 빌드(full LTO x 4플랫폼)는 1회 ~60분 소모. CI 실패 시 반복 재트리거 금지 — 로그 확인 후 코드 수정하고 한 번만 재시도release-please 설정 : release-please-config.json + .release-please-manifest.json 사용 (v4). release-type: simple (rust 타입은 version.workspace = true와 호환 안 됨). include-component-in-tag: false로 v* 태그 생성워크스페이스 버전 관리 : 루트 Cargo.toml의 workspace.package.version이 단일 진실 소스. 서브 크레이트 간 의존성은 path = "../crate-name"만 사용 (버전 핀 금지 — 범프 시 깨짐)릴리스 흐름 : main push → release-please가 PR 생성 → PR 머지 → v* 태그 → release.yml이 4플랫폼 빌드 → GitHub Release에 바이너리 첨부. cratos update는 이 Release 바이너리를 다운로드다른 머신 배포 (CI 없이) : git pull && cargo build --profile dev-release -p cratos && cp target/dev-release/cratos /usr/local/bin/ && cratos restart