cluxion-os 1.1.0

Open-source multi-model coding agent OS with Rust safety gates, TUI, and local model routing.

⚡ Cluxion-OS

어떤 AI 모델이든, 코드 변경 없이 연결하는 오픈소스 멀티모델 코딩 에이전트 OS

설치 · 빠른 시작 · 기능 · 아키텍처 · 문서 · 기여

---

For non-Korean speakers: Cluxion-OS is an open-source 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+ 모델을 코드 변경 없이 전환하며 쓸 수 있는 오픈소스 코딩 에이전트 플랫폼이다. 터미널 TUI 하나로 에이전트 팀을 병렬 실행하고, 메모리와 검증, 외부 CLI handoff를 운영한다. 인프라 비용은 $0 — 내 컴퓨터가 서버다.

---

설치

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

pip install cluxion-os
cluxion-os

소스에서 직접 빌드하거나 기여하려면 저장소를 클론한다.

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

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

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

# 로컬 런타임까지 자동 준비
curl -fsSL https://raw.githubusercontent.com/algocean1204/cluxion-official/main/scripts/install.sh \
  | CLUXION_INSTALL_RUNTIME_DEPS=1 CLUXION_RUNTIME_PROFILE=all sh

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

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

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

---

빠른 시작

# 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"

외부 CLI에서 Cluxion 켜기

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

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

# 외부 공식 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로 수행한다.

/override on claude
/override status claude
/override off claude

복원 전에 사용자가 파일을 수정하면 자동 덮어쓰기를 멈추고 사용자 편집본을 보존한다.

  ⚡ Cluxion-OS
  Model: anthropic:claude-sonnet-4
  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 엔드포인트

---

OpenAI 호환 게이트웨이 (외부 앱 연결)

내가 만든 앱을 AI 모델에 직접 붙이는 대신, 앱 → Cluxion → 모델 순으로 붙이면 모든 요청이 Cluxion의 검증 하네스(FQP 정제·다모델 합의)를 거쳐 더 높은 정확도로 처리된다. Cluxion은 OpenAI 호환 API를 그대로 노출하므로, 기존 OpenAI SDK에서 base_url과 model만 바꾸면 된다.

게이트웨이 실행

# OpenAI 호환 API 서버 실행 — 기본 127.0.0.1:23002 (내 컴퓨터 안에서만 열림)
cluxion-os api-serve

# 포트/호스트 변경
cluxion-os api-serve --port 23002 --host 127.0.0.1

기본값은 localhost 전용이라 외부에 노출되지 않는다. 같은 네트워크의 다른 기기에서 접속하려면 명시적으로 호스트를 열어야 한다.

연결용 API 키 발급

cluxion-os api-key generate --name my-app   # 원본 키는 이 순간에만 출력된다 — 안전한 곳에 보관
cluxion-os api-key list                     # 발급된 키 목록(원본은 노출 안 함)
cluxion-os api-key revoke <키접두어>         # 키 폐기

요청 인증은 x-api-key: <키> 또는 Authorization: Bearer <키> 헤더로 한다.

정확도 티어 (model 이름으로 선택)

model	동작	용도
cluxion-os-fast	FQP 정제·합의 생략, 단일 패스	저지연 우선
cluxion-os	기본 파이프라인(FQP 정제 on, 합의는 설정 기본값)	균형
cluxion-os-deep	FQP 정제 + 다모델 합의 강제(quality_mode 활성·비 local_only·모델 2개 이상일 때)	최고 정확도(지연·토큰↑)

cluxion-os-deep는 클라우드 채점이 불가능한 오프라인 로컬 전용 모드에서는 합의를 강제하지 않고 안전하게 단일 경로로 동작한다(정직성 — 없는 합의를 지어내지 않는다).

OpenAI SDK / curl 예시

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:23002/v1", api_key="<발급키>")
resp = client.chat.completions.create(
    model="cluxion-os-deep",                       # cluxion-os / cluxion-os-fast / cluxion-os-deep
    messages=[{"role": "user", "content": "이 함수의 버그를 찾아줘"}],
)
print(resp.choices[0].message.content)

curl http://127.0.0.1:23002/v1/chat/completions \
  -H "x-api-key: <발급키>" \
  -H "Content-Type: application/json" \
  -d '{"model":"cluxion-os-deep","messages":[{"role":"user","content":"안녕"}]}'

엔드포인트는 /v1/chat/completions, /v1/completions, /v1/models를 제공하며 스트리밍을 지원한다.

---

주요 기능

TurnPipeline — 9단계 에이전트 루프

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

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

판단·설계는 고성능 모델, 코드 작성은 중간 모델, 반복 작업은 로컬 모델 — 작업 유형을 분류해 모델 티어를 자동 배정한다. 동일 품질 기준에서 비용을 크게 줄인다.

Judgment → 고성능 모델     (방향이 틀리면 모든 게 잘못됨)
Execution → 실행 모델      (계획된, 검증된 작업)
Simple    → 경량 모델      (기계적, 저위험 작업)
None      → Rust          (LLM 불필요)

Worker 3모드 — 병렬 에이전트

> API 인증 구현을 3개 워커로 나눠 병렬 처리해줘
  Plan:
  ├─ Agent 1: API endpoints + auth middleware
  ├─ Agent 2: Test suite
  └─ Agent 3: 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 체인으로 컨텍스트 비용을 절감한다. 압축 중에도 Plan Pad, Tool Cards, User Fitting은 절대 압축되지 않는다.

보안 — Rust 기반 5층 방어

층	방어
Rust 패턴 매칭	위험 명령·시크릿 패턴을 마이크로초 단위로 감지, 토큰 비용 0
OS 샌드박스	bubblewrap(Linux) / Seatbelt(macOS) 프로세스 격리
데이터 출처 추적	출처 태그 기반, untrusted 입력의 실행 도구 접근 차단
Security Invariants	불변 접두어를 프롬프트에 주입, 압축 불가
jailbreak 방어	사용자 입력·파일·웹·MCP·메모리 5경로 차단

고품질 모드

선택형 3모델 합의 레이어다. 켜면 계획 실행 전/중/후에 연결된 고성능 모델 최대 3개가 같은 근거를 보고 독립 판단 후 상호 반박/수용 라운드를 수행한다. 별도로 LLM 호출 없이 소스 코드를 직접 분석해 안티패턴을 자동 감지·수정하는 자율 품질 모드도 제공한다.

문서 생성

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

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

마이그레이션

기존 코딩 에이전트의 설정과 메모리를 그대로 가져온다.

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

---

빌트인 에이전트 팀

작업 유형에 맞는 전문 팀을 자동으로 라우팅한다.

팀	역할
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	파일 무결성, 백업, 삭제 안전 확인

개발·설계·품질·문서·전문화·운영 카테고리의 스킬 팀이 추가로 등록되어 작업 성격에 따라 호출된다.

---

아키텍처

┌──────────────────────────────────────────────────────┐
│                    Textual TUI                       │
│       (페인, 스트리밍, 슬래시 커맨드, 사이드바)          │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│               LangGraph StateGraph                    │
│        (TurnPipeline 9단계, 체크포인팅)                 │
├──────────┬────────────┬────────────┬─────────────────┤
│ Providers│   Tools    │   Memory   │   Sub-agents    │
│ (멀티    │ (shell,    │ (KAIROS,   │ (Coordinator,   │
│  프로바  │  edit,     │ autoDream, │  worktree,      │
│  이더)   │  MCP, LSP) │ 모순 해결) │  FORK mode)     │
└──────────┴─────┬──────┴────────────┴─────────────────┘
                 │
┌────────────────▼─────────────────────────────────────┐
│                  Rust Core (PyO3)                     │
│   (위험 패턴 감지, 파일 감시, 데이터 출처 추적,         │
│    입력 sanitize, 에이전트 행동 감시)                  │
└──────────────────────────────────────────────────────┘

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

---

명령 빠른 참조

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 api-serve	OpenAI 호환 게이트웨이 실행 (기본 127.0.0.1:23002, 외부 앱 연결용)
cluxion-os api-key generate|list|revoke	게이트웨이 API 키 발급·조회·폐기
cluxion-os migrate from-claude	설정 마이그레이션 (Claude Code)
cluxion-os migrate from-codex	설정 마이그레이션 (Codex)
cluxion-os context on --agent claude --project .	외부 공식 CLI용 context overlay 켜기
cluxion-os context off --agent claude --project .	context overlay 복원
cluxion-os context install-commands --agent all	공식 slash command 파일 설치

---

설정

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

[cluxion-os]
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"

[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
샌드박스	bubblewrap / Seatbelt
Python	3.12
패키지 관리	uv + maturin

---

문서

문서	내용
docs/model-connection-onboarding.md	모델 연결 온보딩
docs/quality-mode.md	고품질 모드 (3모델 합의)
docs/autonomous-quality-mode.md	자율 품질 모드
CONTRIBUTING.md	기여 가이드

---

Development

git clone https://github.com/algocean1204/cluxion-official.git
cd cluxion-official
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 컴포넌트
• 마이그레이션 어댑터 — 외부 코딩 에이전트 호환성

자세한 기여 절차는 CONTRIBUTING.md를 참고한다.

---

비전공자용 자동 설정 (AI에게 맡기기)

설치·설정이 어렵게 느껴진다면, 아래 프롬프트를 터미널을 직접 실행할 수 있는 AI 비서(Claude Code, Codex, Cursor 등)에게 그대로 복사해 붙여넣는다. AI가 내 컴퓨터 환경을 확인하고, Cluxion을 설치하고, 쉬운 말로 하나씩 물어보며 답하는 대로 바로 설정해 준다.

당신은 Cluxion-OS 설치와 설정을 도와주는 친절한 가이드입니다. 저는 비전공자라서 전문 용어를 잘 모릅니다. 한 번에 하나씩, 쉬운 말로 물어봐 주세요. 제가 답하면 그에 맞는 터미널 명령을 당신이 직접 실행해서 바로바로 설정해 주세요. 다음 순서로 진행해 주세요.

1. 먼저 제 컴퓨터 환경을 확인하세요(운영체제, Python 3.12 이상 설치 여부). Python이 없거나 버전이 낮으면 설치를 도와주세요.
2. Cluxion-OS를 설치하세요: pip install cluxion-os==1.1.0. 끝나면 cluxion-os --version으로 확인해 주세요.
3. 어떤 AI를 쓸지 쉬운 말로 물어봐 주세요. 예: "ChatGPT나 Claude 구독이 있으세요?" 또는 "무료로 내 컴퓨터에서만 돌리는 로컬 AI를 쓸까요?" 제 답에 따라 cluxion-os 첫 실행 설정 마법사를 함께 진행하거나, 필요한 키를 어디서 받는지 단계별로 안내하고 입력을 도와주세요.
4. 제가 "제가 만든 다른 앱을 Cluxion에 연결하고 싶다"고 하면, OpenAI 호환 게이트웨이를 켜 주세요.
   • 게이트웨이 실행: cluxion-os api-serve (기본 주소 http://127.0.0.1:23002, 내 컴퓨터 안에서만 열림)
   • 연결용 키 발급: cluxion-os api-key generate --name my-app (출력된 키는 이때 한 번만 보이니 안전한 곳에 적어두라고 알려주세요)
   • 제 앱에서 쓸 수 있도록 OpenAI SDK 기준 base_url과 model 예시를 보여주세요. model은 빠른 cluxion-os-fast, 균형 cluxion-os, 정확한 cluxion-os-deep 중에서 고르게 해주세요.
5. 매 단계마다 무엇을 왜 하는지 한 문장으로 쉽게 설명하고, 에러가 나면 침착하게 원인과 해결을 안내해 주세요. 제 동의 없이 시스템을 크게 바꾸지 마세요.

준비되면 1번부터 시작해 주세요.

---

License

Apache License 2.0

---

Built by algocean