Metadata-Version: 2.4
Name: cluxion-os
Version: 1.0.1
Requires-Dist: typer>=0.12
Requires-Dist: textual>=0.80
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: langchain-core>=0.3
Requires-Dist: langgraph>=0.2
Requires-Dist: aiohttp>=3.9
Requires-Dist: keyring>=25.0
Requires-Dist: rich>=13.0
Requires-Dist: psutil>=5.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: toml>=0.10
Requires-Dist: pillow>=10.0
Requires-Dist: python-docx>=1.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: python-pptx>=0.6
Requires-Dist: text-unidecode>=1.3,<2
Requires-Dist: reportlab>=4.2
Requires-Dist: pillow>=10.0 ; extra == 'content'
Requires-Dist: build>=1.2 ; extra == 'dev'
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.26 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3 ; extra == 'dev'
Requires-Dist: ruff>=0.8 ; extra == 'dev'
Requires-Dist: mypy>=1.10 ; extra == 'dev'
Requires-Dist: maturin>=1.5 ; extra == 'dev'
Requires-Dist: weasyprint>=62 ; extra == 'docs'
Requires-Dist: vllm>=0.6.0 ; extra == 'local'
Requires-Dist: mlx>=0.20.0 ; extra == 'local'
Requires-Dist: mlx-lm>=0.20.0 ; extra == 'local'
Requires-Dist: python-telegram-bot>=21 ; extra == 'messaging'
Requires-Dist: discord-py>=2.3 ; extra == 'messaging'
Requires-Dist: slack-bolt>=1.18 ; extra == 'messaging'
Requires-Dist: mlx>=0.20.0 ; extra == 'mlx'
Requires-Dist: mlx-lm>=0.20.0 ; extra == 'mlx'
Requires-Dist: maturin>=1.5 ; extra == 'rust'
Requires-Dist: pytest>=8.0 ; extra == 'test'
Requires-Dist: pytest-asyncio>=0.26 ; extra == 'test'
Requires-Dist: pytest-cov>=4.0 ; extra == 'test'
Requires-Dist: pytest-timeout>=2.3 ; extra == 'test'
Requires-Dist: vllm>=0.6.0 ; extra == 'vllm'
Provides-Extra: content
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: local
Provides-Extra: messaging
Provides-Extra: mlx
Provides-Extra: rust
Provides-Extra: test
Provides-Extra: vllm
License-File: LICENSE
Summary: Open-source multi-model coding agent OS with Rust safety gates, TUI, and local model routing.
Keywords: ai-agent,coding-agent,multi-model,local-llm,tui,terminal,rust,pyo3,automation
Home-Page: https://github.com/cluxion/cluxion-os
Author-email: kimtaekyu <aisamdasu1204@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/cluxion/cluxion-os
Project-URL: Issues, https://github.com/cluxion/cluxion-os/issues
Project-URL: Repository, https://github.com/cluxion/cluxion-os

<p align="center">
  <h1 align="center">⚡ Cluxion-OS</h1>
  <p align="center"><strong>어떤 AI 모델이든, 코드 변경 없이 연결하는 오픈소스 멀티모델 코딩 에이전트 OS</strong></p>
  <p align="center">
    <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="Apache-2.0"/></a>
    <img src="https://img.shields.io/badge/Python-3.12-3776AB?logo=python&logoColor=white" alt="Python 3.12"/>
    <img src="https://img.shields.io/badge/Rust-PyO3-000000?logo=rust&logoColor=white" alt="Rust"/>
    <img src="https://img.shields.io/badge/Tests-11K%2B-brightgreen" alt="Tests 11K+"/>
    <img src="https://img.shields.io/badge/Coverage-73.44%25-yellow" alt="Coverage"/>
    <img src="https://img.shields.io/badge/RC-12%2F12_Gate_통과-success" alt="RC 12/12"/>
  </p>
  <p align="center">
    <a href="#설치">설치</a> ·
    <a href="#빠른-시작">빠른 시작</a> ·
    <a href="#주요-기능">기능</a> ·
    <a href="#아키텍처">아키텍처</a> ·
    <a href="#문서">문서</a> ·
    <a href="#contributing">기여</a>
  </p>
</p>

---

> **For non-Korean speakers:** Cluxion-OS is an open-source OS-level coding agent platform that orchestrates any AI model (200+), parallel agent teams, persistent memory, and Rust-powered security — all from your terminal.

---

Cluxion-OS는 Anthropic, OpenAI, Ollama, Gemini, OpenRouter 등 200+ 모델을 코드 변경 없이 전환하며 쓸 수 있는 오픈소스 코딩 에이전트 플랫폼이다. V1은 터미널 TUI에 집중한다. TUI 하나로 에이전트 팀을 병렬 실행하고, 검증 하네스와 메모리, 외부 CLI handoff를 운영한다. 인프라 비용은 $0 — 내 컴퓨터가 서버다.

**현재 상태:** V1 범위는 CLI/TUI 전용이다. Desktop 앱과 Mobile 앱은 V1 공개 범위에서 보류하고, TUI 디자인·기능·사용자 경험을 먼저 완성한다. Desktop 앱 소스와 release gate는 별도 `cluxion/cluxion-Desktop` 레포지토리로 분리한다. V1.0.1은 PyPI와 GitHub Release에 공개된 TUI/Core 배포판이다.

---

## 설치

**요구사항:** Python 3.12+, macOS 또는 Linux (WSL2)

```bash
pip install cluxion-os==1.0.1
cluxion-os
```

소스에서 직접 확인하거나 기여하려면 배포 스냅샷 저장소를 사용한다.

```bash
git clone https://github.com/algocean1204/cluxion-official.git
cd cluxion-official
uv sync --extra dev
uv run maturin develop --release
uv run cluxion-os
```

공개 배포 스냅샷은 `algocean1204/cluxion-official`에서 제공한다. 개발,
버그 수정, 기능 기여는 업스트림 `cluxion/cluxion-os`에서 진행한다.

릴리스 설치 스크립트는 CLI/TUI를 먼저 설치하고, 사용자가 명시적으로 켠 경우
로컬 런타임 의존성까지 이어서 준비한다.

```bash
# 기본: CLI/TUI만 설치, 로컬 런타임은 안내만 표시
curl -fsSL https://raw.githubusercontent.com/algocean1204/cluxion-official/main/scripts/install.sh | sh

# 전체 로컬 런타임까지 자동 준비: HF CLI, Qwen3.6 MLX, vllm-metal, Gemini CLI, Ollama
curl -fsSL https://raw.githubusercontent.com/algocean1204/cluxion-official/main/scripts/install.sh \
  | CLUXION_INSTALL_RUNTIME_DEPS=1 CLUXION_RUNTIME_PROFILE=all sh
```

설치 후 런타임 점검은 같은 계약을 CLI에서 직접 실행할 수 있다.

```bash
cluxion-os setup deps --profile all
cluxion-os setup deps --profile all --apply --yes
```

첫 실행 시 대화형 설정 마법사가 모델 연결, 프로바이더 API 키, 선택적 기능을 안내한다.

> PyPI V1.0.1 배포는 활성화되어 있다. 향후 PyPI 승격은 토큰이 아니라 Trusted Publisher 기반의 수동 workflow를 기본으로 사용한다. Desktop 설치 채널과 앱 소스는 `cluxion/cluxion-Desktop`에서 별도 릴리스로 보류하고, Mobile은 별도 미래 릴리스로 둔다.

---

## 빠른 시작

```bash
# TUI 대화형 모드
uv run cluxion-os

# 모델 지정은 config.toml의 [spectrum]/[model] 슬롯에서 관리
cluxion-os --version

# 원라인 실행 (CI/CD, pre-commit 등)
cluxion-os exec "Fix the failing tests in src/api/"
cluxion-os exec --use-codex "Add error handling to all endpoints"
```

### Claude/Codex/Gemini에서 Cluxion 켜기

Cluxion은 설치 시 사용자의 `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`를 자동으로
수정하지 않는다. 외부 공식 CLI에서 Cluxion의 메모리, 하네스, MoE 라우팅,
서브에이전트, handoff를 적극 사용하려면 프로젝트 단위로 명시적으로 켠다.

```bash
# 선택: Claude/Gemini 공식 slash command 파일 설치
cluxion-os context install-commands --agent all

# Claude Code 공식 interactive session에서 Cluxion overlay 켜기
cd ~/projects/my-app
cluxion-os context on --agent claude --project .
claude

# 작업이 끝나면 원래 context 파일로 복원
cluxion-os context off --agent claude --project .
```

TUI 안에서는 같은 동작을 slash command로 수행한다.

```text
/override on claude
/override status claude
/override off claude
```

적용 파일은 에이전트별로 다르다. Claude override는 `CLAUDE.md`와 공유
`AGENTS.md`, Codex override는 `AGENTS.md`, Gemini override는 `GEMINI.md`,
`AGENTS.md`, `AGENT.md`를 세션 범위로만 overlay한다. 복원 전에 사용자가 파일을
수정하면 자동 덮어쓰기를 멈추고 사용자 편집본을 보존한다.

```
  ⚡ Cluxion-OS
  Model: anthropic:claude-sonnet-4-20250514
  Project: ~/projects/my-app

  > Refactor the auth module to use JWT tokens

  Working...
  ├─ Reading src/auth/ (3 files)
  ├─ Editing src/auth/handler.py
  ├─ Creating src/auth/jwt.py
  ├─ Running pytest tests/auth/
  └─ 4 files changed, all tests passing

  > 새 JWT 모듈 테스트 작성을 별도 워커로 분리해줘
  Worker queued (isolated worktree: feature/jwt-tests)
```

---

## 지원 프로바이더

코드 변경 없이 전환 가능하다. `config.toml`에서 엔드포인트만 지정하면 된다.

| 구분 | 프로바이더 |
|------|-----------|
| Cloud | Anthropic, OpenAI, Google Gemini |
| 추론 서비스 | OpenRouter (200+ 모델), NovitaAI, NVIDIA NIM |
| 특수 모델 | Xiaomi MiMo, z.ai/GLM, Kimi/Moonshot, MiniMax |
| 로컬 | Ollama, LM Studio, HuggingFace 캐시 |
| 커스텀 | OpenAI-compatible 엔드포인트 |

---

## 주요 기능

### TurnPipeline — 9단계 에이전트 루프

Settings → State → Context → Shape → Model → Dispatch → Permission → Execute → Stop 의 단계를 거쳐 모든 에이전트 액션이 리더 파이프라인을 통과한다. 자율 이탈이 구조적으로 차단된다.

### Spectrum MoE — 작업별 최적 모델 자동 선택

판단·설계는 Opus, 코드 작성은 Sonnet, 반복 작업은 로컬 Qwen — 작업 유형을 분류해 모델 티어를 자동 배정한다. 동일 품질 기준에서 비용이 최대 75% 줄어든다.

```
Judgment → claude-opus-4          (방향이 틀리면 모든 게 잘못됨)
Execution → claude-sonnet-4       (계획된, 검증된 작업)
Simple    → claude-sonnet-4       (기계적, 저위험 작업)
None      → Rust                  (LLM 불필요)
```

### Worker 3모드 — 병렬 에이전트

```bash
> API 인증 구현을 3개 워커로 나눠 병렬 처리해줘
  Plan:
  ├─ Agent 1 (Claude): API endpoints + auth middleware
  ├─ Agent 2 (Qwen):   Test suite
  └─ Agent 3 (GPT):    API documentation

  All agents working in parallel...
  ├─ agent-1: feature/api-auth (3 files changed)
  ├─ agent-2: feature/tests (5 test files)
  └─ agent-3: feature/docs (README + OpenAPI spec)

  All branches merged. No conflicts.
```

- **WORKER**: 리더 컨텍스트 공유, 기본 모드
- **TEAMMATE**: 독립 실행, 결과 합류 — 각자 isolated git worktree에서 작업
- **FORK**: ~1000토큰, read-only 탐색, 즉시 해체 — 불확실한 접근법을 안전하게 검증

### KAIROS 메모리 — 세션을 넘어 지속

```
> 메모리 상태 알려줘
  KAIROS Memory Status
  ├─ Project: FastAPI + PostgreSQL + Redis
  ├─ Patterns: async/await, Pydantic models, pytest
  ├─ Last autoDream: 2h ago (3 contradictions resolved)
  └─ Size: 142 lines / 18KB
```

- **autoDream**: 유휴 시간에 관찰을 합치고, 모순을 해결하고, 추측을 사실로 승격
- **Self-Healing**: 메모리와 현재 코드베이스 사이 충돌을 감지하고 자동 교정
- **Skeptical Memory**: 메모리를 힌트로만 취급하고 실제 코드를 확인한 뒤 행동

### 5단계 컨텍스트 압축

Budget → Snip → MicroCompact → Collapse → AutoCompact 체인으로 컨텍스트 비용을 65% 절감한다. 압축 중에도 Plan Pad, Tool Cards, User Fitting은 절대 압축되지 않는다.

### 보안 — Rust 기반 5층 방어

| 층 | 방어 |
|----|------|
| Rust 패턴 매칭 | 위험 명령 47패턴 + 별도 시크릿 13패턴, 마이크로초 감지, 토큰 비용 0 |
| OS 샌드박스 | bubblewrap(Linux) / Seatbelt(macOS) 프로세스 격리 |
| 데이터 출처 추적 | 8종 출처 태그, untrusted + EXECUTION_TOOLS → 실행 차단 |
| Security Invariants | ~100토큰 불변 접두어, 37개 프롬프트에 주입, 압축 불가 |
| jailbreak 5경로 방어 | sanitizer.rs가 사용자 입력·파일·웹·MCP·메모리 5경로 차단 |

추가 보안 모듈은 `src/cluxion_os/safety/`와 `cluxion_os_rust/src/`에서 관리한다. README에는 코드·문서로 재현 가능한 보안 주장만 적는다.

### 문서 생성

PPTX, DOCX, XLSX, PDF, HWP/HWPX, Obsidian, Markdown, HTML을 에이전트 작업 결과에서 직접 생성한다.

```bash
> JWT 리팩터링 결과를 발표용 PPTX로 만들어줘
  pptx_worker #1 → slides 1-4
  pptx_worker #2 → slides 5-8
  jwt-refactoring.pptx saved
```

### 보류된 표면: Desktop / Mobile / 원격 제어

V1에서는 TUI를 1급 제품 표면으로 둔다. Desktop 앱은 별도
`cluxion/cluxion-Desktop` 레포지토리로 분리했고, 이 레포지토리에는 Desktop 앱
소스와 release script를 두지 않는다. Mobile 앱, 모바일 웹 bridge, 메시징 원격
제어도 공개 기능으로 홍보하지 않는다.

Desktop/Mobile을 다시 여는 기준은 별도 UX 라운드, signing/notarization,
모바일 보안/페어링 검증, 독립 릴리즈 게이트가 모두 닫힌 뒤다.

### 마이그레이션

Claude Code의 `CLAUDE.md`와 Codex의 `AGENTS.md`를 그대로 가져온다.

```bash
cluxion-os migrate from-claude --dry-run
  Found: CLAUDE.md, .claude/settings.json
  ├─ CLAUDE.md → Cluxion-OS.md
  ├─ Memory → KAIROS format (23 entries)
  └─ Skills → 4 compatible skills loaded
```

---

## 빌트인 에이전트 팀

현재 TeamSpawner에 정식 등록되는 팀은 코어 팀 17개와 스킬 팀 23개다. 디렉토리 수가 아니라 `register_all_teams()` 등록 경로를 기준으로 계산한다.

| 팀 | 역할 |
|----|------|
| Planning | 요구사항 분석, 가정 검증, 범위 결정 |
| Strategy | 실행 전략, 범위 조정, 리스크 우선순위 |
| Architecture | 데이터 플로우, 상태 머신, 테스트 매트릭스 |
| Development | 백엔드/프론트엔드/풀스택 구현 |
| Review | 코드 리뷰, 자동 수정, 검증 |
| Test | Unit/Integration/E2E 테스트 및 회귀 테스트 |
| Refactor | 복잡도 감소, 의존성 인식 리팩터링 |
| Research | 웹·문서 리서치, 비교 보고서 |
| Efficiency | 토큰·캐시·모델 경로 최적화 (항상 실행) |
| Docs | README, API 문서, 기술 문서 |
| Documents | PPTX, DOCX, XLSX, PDF, HWPX 등 범용 문서 산출 |
| Content | 블로그, 소셜, 비주얼 콘텐츠 |
| Obsidian | 노트 작성, 백링크, 지식 동기화 |
| Security | OWASP, STRIDE, 위협 모델링 |
| Release | 배포, 도큐멘트 갱신, 카나리 |
| Design | 다이어그램, UI/UX, 디자인 산출물 |
| File Guardian | 파일 무결성, 백업, 삭제 안전 확인 |

**별도 스킬 팀 23개**는 아래 카테고리로 등록·라우팅된다:

| 카테고리 | 스킬 |
|---------|------|
| 개발 | Frontend Developer, Backend Architect, Database Specialist, DevOps Engineer |
| 설계 | UI/UX Designer, Design Consultant, Design→HTML, Design Shotgun |
| 품질 | Code Quality, Browser QA, Canary Monitor, Benchmark |
| 문서/콘텐츠 | Technical Writer, Marketing Strategist, Codebase to Course |
| 전문화 | Prompt Engineering, Memory Management, Scientific Research, Compliance Auditor |
| 운영 | Sprint Pipeline, DevEx Review, Frontend Design, Retro |

스킬과 팀 활성화 정책은 레지스트리/설정 파일에서 관리한다. TUI의 `/agent ...` 계열은 확장 카탈로그에 있으나 직접 핸들러 연결 전까지 배포 기능으로 표기하지 않는다.
네이티브 ToolGate 실행 워커가 아직 연결되지 않은 스킬 팀은 `not_implemented`로 실패하며, 등록만으로 성공 완료를 만들지 않는다.

---

## 아키텍처

```
┌──────────────────────────────────────────────────────┐
│                    Textual TUI                       │
│       (페인, 스트리밍, 슬래시 커맨드, 사이드바)          │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│               LangGraph StateGraph                    │
│        (TurnPipeline 9단계, 체크포인팅)                 │
├──────────┬────────────┬────────────┬─────────────────┤
│ Providers│   Tools    │   Memory   │   Sub-agents    │
│ (Claude, │ (shell,    │ (KAIROS,   │ (Coordinator,   │
│  GPT,    │  edit,     │ autoDream, │  worktree,      │
│  Qwen)   │  MCP, LSP) │ 모순 해결) │  FORK mode)     │
└──────────┴─────┬──────┴────────────┴─────────────────┘
                 │
┌────────────────▼─────────────────────────────────────┐
│                  Rust Core (PyO3)                     │
│  (명령 패턴 47개, 시크릿 패턴 13개, 파일 감시,           │
│   DataProvenance, sanitizer, agent_supervisor)        │
└──────────────────────────────────────────────────────┘
```

Python이 *무엇을 할지* 결정하고, Rust가 *어떻게 할지* 실행한다.

**규모(현재 `src/` + Rust core 기준)**: Python 97K+줄 / Rust core 15K+줄, pytest 11K+ 통과 release suite.
전체 저장소에는 테스트, 데스크톱 앱, 보고서 산출물, 설치 자산이 별도로 포함된다.

---

## 명령 빠른 참조

현재 README에는 런타임 핸들러가 연결된 명령만 작동 명령으로 적는다.
`src/cluxion_os/tui/slash.py`의 확장 카탈로그에는 자동완성/계획형 항목도 포함되지만, 직접 핸들러가 붙기 전까지는 배포 기능으로 계산하지 않는다.

### TUI 직접 처리 명령

| 커맨드 | 설명 |
|--------|------|
| `/observe` | 관찰 패널 토글 |
| `/map`, `/rts` | 에이전트 맵 토글 |
| `/lang [code]`, `/language [code]` | 표시 언어 변경 |
| `/history [query]` | 대화 히스토리 검색 화면 |
| `/help` | 도움말 |
| `/clear` | 대화 화면 지우기 |
| `/steer [message]` | 실행 중인 작업에 방향 수정 전달 |
| `/files [path\|--modified\|--related file]` | 프로젝트 파일 트리/관련 파일 표시 |
| `/launch [init\|show\|suggest]` | 프로젝트별 launch.toml 관리 |
| `/evolve [status\|suggest\|promote]` | 자기 진화 후보와 품질 상태 확인 |

### CLI 명령

| 명령 | 설명 |
|------|------|
| `cluxion-os` | TUI 실행 |
| `python -m cluxion_os` | 모듈 진입점으로 TUI 실행 |
| `cluxion-os exec "..."` | 비대화형 실행 |
| `cluxion-os exec --detach "..."` | 백그라운드 작업 시작 |
| `cluxion-os attach <job_id>` | 백그라운드 작업 연결 |
| `cluxion-os jobs` | 백그라운드 작업 목록 |
| `cluxion-os serve` | 보류된 모바일 bridge/API/WebSocket 서버 개발 경로 |
| `cluxion-os migrate from-claude` | Claude Code 설정 마이그레이션 |
| `cluxion-os migrate from-codex` | Codex 설정 마이그레이션 |
| `cluxion-os context on --agent claude --project .` | Claude/Codex/Gemini 공식 CLI용 context overlay 켜기 |
| `cluxion-os context off --agent claude --project .` | context overlay 복원 |
| `cluxion-os context install-commands --agent all` | Claude/Gemini 공식 slash command 파일 설치 |

---

## 설정

```toml
# ~/.cluxion_os/config.toml
# 최소 시작 예시입니다. 전체 설정은 저장소의 config.toml과 src/cluxion_os/config/config_schema.py를 기준으로 확인하세요.

[cluxion-os]
version = "1.0.1"
project_name = "cluxion-os"
data_dir = "~/.cluxion_os"

[spectrum]
judgment = "subscription/codex"
execution = "local/unsloth/Qwen3.6-35B-A3B-UD-MLX-4bit"
verification = "subscription/codex"
simple = "local/unsloth/Qwen3.6-35B-A3B-UD-MLX-4bit"

[model]
brain = "subscription/codex"
execute = "local/unsloth/Qwen3.6-35B-A3B-UD-MLX-4bit"
verify = "subscription/codex"
simple = "local/unsloth/Qwen3.6-35B-A3B-UD-MLX-4bit"

[codex]
enabled = true
auth_modes = ["subscription"]
mode = "exec"
binary = "codex"

[claude]
enabled = true
auth_modes = ["subscription"]
mode = "interactive_handoff"
binary = "claude"

[local_model]
auto_detect = true
strict_no_cpu = true
preferred_model_source = "ollama"      # "ollama" | "huggingface_cache"
enable_hf_cache_runtime = true
fallback_models = ["subscription/codex", "subscription/claude"]

[local_model.api_base_urls]
ollama = "http://localhost:11434"
lmstudio = "http://localhost:1234/v1"
mlx = "http://127.0.0.1:23003"
```

---

## 기술 스택

| 구분 | 기술 |
|------|------|
| 에이전트 오케스트레이션 | LangGraph (StateGraph, Send API) |
| LLM 추상화 | LangChain Core (`init_chat_model`) |
| 메모리 | LangGraph Store + LangMem + KAIROS |
| 성능 모듈 | Rust + PyO3 |
| TUI | Textual |
| CLI | Typer |
| API 서버 | LangServe + FastAPI |
| 샌드박스 | bubblewrap / Seatbelt |
| 추적 | LangSmith (opt-in) |
| Python | 3.12 |
| 패키지 관리 | uv + maturin |

---

## 문서

| 문서 | 내용 |
|------|------|
| [docs/deployment-release-plan.md](docs/deployment-release-plan.md) | 릴리스·배포 계획 |
| [docs/verification-philosophy.md](docs/verification-philosophy.md) | 증거 우선 검증 철학 |
| [docs/local-frontier-philosophy.md](docs/local-frontier-philosophy.md) | 로컬 모델 프론티어급 산출물 철학 |
| [docs/search-evidence-pipeline.md](docs/search-evidence-pipeline.md) | Perplexity식 출처 중심 검색 파이프라인 |
| [docs/eval-system.md](docs/eval-system.md) | P1-P8 eval 파이프라인 |
| [docs/gemini-provider.md](docs/gemini-provider.md) | Gemini 프로바이더 아키텍처 |
| [docs/external-agent-runtime-routing.md](docs/external-agent-runtime-routing.md) | Claude/Codex/Gemini 실행 모드 분류 계약 |
| [docs/external-agent-handoff-release-evidence.md](docs/external-agent-handoff-release-evidence.md) | 외부 agent handoff 릴리스 증거 |
| [docs/ollama-provider.md](docs/ollama-provider.md) | Ollama 공식 로컬 런타임 연동 |
| [docs/vllm-metal-runtime-transition.md](docs/vllm-metal-runtime-transition.md) | Apple Silicon HF 캐시용 vLLM-Metal 런타임 전환 계약 |
| [docs/instruction-system.md](docs/instruction-system.md) | instruction 파싱·병합 시스템 |
| [docs/self-evolution-control-plane.md](docs/self-evolution-control-plane.md) | KAIROS 자기 진화 제어 |
| [docs/cursor-speed-quality-contract.md](docs/cursor-speed-quality-contract.md) | 속도·품질 계약 |
| [docs/local-agent-reliability-patterns.md](docs/local-agent-reliability-patterns.md) | Cursor 2.5·Forge·vLLM·Ollama식 로컬 에이전트 신뢰성 패턴 |
| [docs/skipped-tests.md](docs/skipped-tests.md) | 외부 런타임 스킵 테스트 정책 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 기여 가이드 |

---

## Development

```bash
# 저장소 클론 및 의존성 설치
git clone https://github.com/cluxion/cluxion-os.git
cd cluxion-os
uv sync --extra dev

# Rust 코어 빌드
maturin develop --release

# 테스트
uv run pytest

# 린트
uv run ruff check .
uv run mypy src/
```

---

## Contributing

Cluxion-OS는 모듈형 아키텍처로 설계되어 있어 각 기능을 독립적으로 작업할 수 있다. 기여가 특히 필요한 영역:

- **Rust PyO3 모듈** — 성능 핵심 내부 구조
- **MCP 서버 통합** — 커넥터 생태계 확장
- **Textual TUI** — 터미널 UI 컴포넌트
- **마이그레이션 어댑터** — Claude Code / Codex 호환성

V1 기여 우선순위는 TUI 사용성, 상태 표시, handoff UX, 오류 메시지,
검증 결과 가독성이다. Desktop/Mobile 기능 확장은 별도 릴리즈 라운드에서
다룬다.

자세한 기여 절차는 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고한다.

---

## License

[Apache License 2.0](LICENSE)

---

<p align="center">
  Built by <a href="https://github.com/algocean1204">algocean</a> · Design by human, implementation by AI, verification by AI
</p>

