cluxion-os 1.0.3

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 엔드포인트

---

주요 기능

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 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를 참고한다.

---

License

Apache License 2.0

---

Built by algocean