agentforce314/clawcodex

English | 中文 | Français | Русский | हिन्दी | العربية | Português

Claude Code를 프로덕션 지향적으로 재구축한 Python 버전 — 실제 아키텍처를 갖춘 신뢰할 수 있는 CLI 에이전트 (Agent)

TypeScript 참조 구현체로부터 포팅되었으며 Python 네이티브 런타임(Runtime)으로 확장되었습니다.

🔥 활발한 개발 진행 중 • 매주 새로운 기능 추가 🔥

git clone https://github.com/agentforce314/clawcodex.git
cd clawcodex
python3 -m venv .venv && source .venv/bin/activate # Python 3.10+
...

2026-05-16: 코드베이스 통계 — 총 Python 파일 수: 894개; 총 Python 코드 라인 수: 177,428 라인 (2026-05-14 기준 167,034 라인에서 증가; 이틀간 약 +10.4k 라인 증가, 주로 ESC 취소(cancellation) 강화 및 이미지 처리(image-handling) 기능 일치 작업).

2026-05-16: 이미지 처리 기능 일치 (Tier C, #149/#154/#155/#156) — Read 도구 TS 이미지 파이프라인 (탐지(sniff), 크기 조정/압축, base64 캡처); @image.png를 깨진 문자(mojibake) 대신 실제 ImageBlock으로 인라인 언급; 교차 제공자(cross-provider) Anthropic image/document → OpenAI image_url/file 변환; BaseProvider에서의 API 호출 전 base64 크기 검증.

2026-05-16: 서브에이전트 (Subagent) + Bash 신뢰성 — 이제 .claude/agents/에서 커스텀 서브에이전트를 탐색함 (#151); Bash tool_result가 타임아웃(timeout)과 ESC 중단(abort)을 구분하여 모델이 두 가지를 구별할 수 있도록 함 (#152); 비동기 서브에이전트(async-subagent) AbortController 격리가 회귀 테스트(regression tests)를 통해 고정되어, 부모의 ESC가 형제 에이전트의 중단 리스너(abort listeners)를 트리거하지 않음 (#153); 취소된 tool_result가 프로덕션 경로에서 REJECT_MESSAGE를 안정적으로 노출함 (#150).

2026-05-15 ~ 2026-05-16: 모든 제공자에 대한 ESC 취소 강화 (#144–#148) — 스트리밍 도중 취소 시 모든 지원되는 제공자(Anthropic, OpenAI, GLM, Minimax, DeepSeek, OpenRouter)에 대해 약 50ms 이내에 스트리밍 HTTP 응답을 종료함; 공유 StreamAbortGuard 헬퍼 추출; LiteLLM 워커 스레드(worker-thread) 반복문이 OpenAI 호환 백엔드에서의 롱테일 행(long-tail hangs) 현상을 수정함.

2026-05-15: SWE-bench 검증 결과 — clawcodex는 openclaude 대비 **291/499 (58.2%)**를 해결함.

265/499 (53.0%) — 표준화된 하네스 (standardized harness) 하의 Gemini 2.5 Pro 결과 (비교 프레임워크는 eval/ 참조 — 누적 배치 처리 (cumulative batching), 병렬 --predict-workers, 전체 stream-json 트레이스 캡처 포함).

2026-05-15:
네이티브 Gemini 프로바이더 (Native Gemini provider) — google-genai SDK를 통한 src/providers/gemini_provider.py 구현. 스키마 정제 (Schema sanitization)를 통해 OpenAI 스타일의 도구 정의가 Gemini의 더 엄격한 Schema (oneOf / additionalProperties 제거, 다형성 파라미터(polymorphic params)를 string으로 강제 변환)와 호환되도록 유지함.

2026-05-14:
코드베이스 통계 (Codebase stats) — 총 Python 파일 수: 837개; 총 Python 코드 라인 수: 167,034 라인.

2026-05-14:
ESC 취소 지연 시간 수정 (#130) — ESC를 누르면 이제 실행 중인 Bash 명령 및 스트리밍 응답이 약 50ms 이내에 취소됨. 이는 diff 컬러 바 전체 너비 렌더링 수정 (#129) 및 경로 외부 권한 우회 수정 (#128)에 추가된 사항임.

2026-05-12:
부트스트랩 (Bootstrap) + 아키텍처 문서 — docs/ARCHITECTURE.md에 새로운 아키텍처 개요 추가; 프로덕션 부트스트랩 포트 (메모이제이션된 init(), 신뢰 경계 (trust boundary), 통합된 launch_repl(args), --bare 패스트 패스 (fast path), 스키마 마이그레이션 러너); 메인 쿼리 루프 및 에이전트 루프는 dispatch_full을 통해 라우팅됨.

도구 로딩 지연 (deferred tool loading)과 함께.

2026-05-11 (v0.5.0):
ClawCodex v0.5.0 출시— 사용자에게 보이는 모든 UI에서 ClawCodex로 리브랜딩; 반응형 상태 서브시스템 (reactive state subsystem) 이식 (시그널 (signals), 스토어 (store), 세션 컨텍스트 (session context), 비용 추적기 (cost tracker), 1시간 캐시 적격성 (1h cache eligibility)); API 레이어 강화 (출력 토큰 제한 (output-token cap), 요청 ID 주입 (request-id injection), 메시지 레벨 캐시 중단점 (message-level cache breakpoints), Haiku 패스트 패스 (fast path), 와치독 (watchdog) + 비스트리밍 폴백 (non-streaming fallback), 스트림 재시도 (retry-with-stream)); 에이전트 루프 기반 구축 (타입 지정 터미널 (typed terminal), 미디어 복구 (media recovery), 차단 제한 가드 (blocking-limit guards), 토큰 예산 (token budget), 중지 훅 (stop hooks), 모델 폴백 (model fallback), 연속성 넛지 (continuation nudge)); README 스크린샷 업데이트.

2026-05-10:
MCP 서브시스템 도입— OAuth 배선, HTTPS, XSS 강화 및 비동기 I/O (async I/O)를 포함한 전체 모델 컨텍스트 프로토콜 (Model Context Protocol, MCP) 지원; 다단계 보안 검토 통과.

2026-05-10:
성능 개선 작업— 스타트업 프로파일러 (startup profiler), 스티키 래치 (sticky latches)를 이용한 프롬프트 캐시 배관 (prompt-cache plumbing), 점수 제한 가지치기 (score-bound pruning)를 포함한 비트맵 + 비동기 검색 인덱싱 (bitmap + async search indexing), 콜드 스타트 지연 시간 감소, 스트리밍 강화.

2026-05-10:
CCR 원격 브리지 (0~5단계)— cc:// 및 cc+unix://를 통한 직접 연결 (Direct Connect), Bridge v2 전송 (transport), 원격 세션 뷰어 (Remote Session viewer), CCR 업스트림 프록시 (upstream proxy).

2026-05-10:
독립형 REPL 모듈— vim 모드, 트랜스크립트 검색 (transcript search), IME 커서, 터미널 하이퍼링크, 프레임 메트릭 (frame metrics), 사고 위젯 (thinking widget), 도구별 권한 특성화 (per-tool permission specialization), 출력 스타일 프론트매터 (output-styles frontmatter); REPL 트랜스크립트 가독성 및 ANSI diff 배경 적용.

2026-05-08:
훅 (Hooks) 시스템— 워크스페이스 신뢰 게이트 (workspace-trust gate)를 갖춘 스냅샷 기반 실행기 (executor), 확장된 이벤트/소스 분류 체계 (taxonomy), 스키마 검증 (schema validation), 환경 주입 (environment injection).

2026-05-08:
멀티 에이전트 조정 (Multi-agent coordination)— 타입 지정 작업 상태 머신 (typed task state machine), JSONL 트랜스크립트 작성기, 에이전트 작업 라이프사이클, 진행률 추적기, 작업 알림 라우팅, SendMessage 피어 DM, 스웜 프리미티브 (swarm primitives), 백그라운드 재개, 코디네이터 모드 + 워커 에이전트, 권한 전달 브리지; main 브랜치에서 전체 테스트 스위트 통과 (green).

.2026-05-07:****자동 메모리 (Auto-memory) + 동시성 (concurrency)— 지속성 자동 메모리 (persistent auto-memory) 서브시스템 (사용자 / 피드백 / 프로젝트 / 참조 유형) 이식; TypeScript 레퍼런스와 동시성 오케스트레이터 (concurrency-orchestrator) 및 도구 실행 (tool-execution) 기능의 동일성 확보; 권한 시스템 (permission-system) 격차 해소.
**2026-05-06:**서브에이전트 (Subagent) 동일성— 포크-서브에이전트 (fork-subagent) 경로 이식; 서브에이전트 비동기 생명주기 (async lifecycle)를 TypeScript 레퍼런스와 일치시킴.
2026-05-05:****문서 개선 (Docs polish)— 헤더 아래에 빠른 설치 (Quick Install) 섹션 추가; clawcodex login에 의해 작성되는 설정 경로 (config path) 문서화.

.**2026-04-30:**기술 (Skills) 서브시스템 동일성— 기술 (Skills) (프로젝트 + 사용자, 명명된 인자 (named args), 도구 제한 (tool limits)) 기능을 TypeScript 레퍼런스와 동일한 수준으로 구현.
**2026-04-29:**REPL 스피너 UX— REPL 스피너 행에 경과 시간 및 토큰 수 (token count) 표시.
**2026-04-27:**새로운 데모— Adopt Me 스타일의 펫 게임 (React + Vite + Vitest), ClawCodex에 의해 엔드투엔드 (end-to-end)로 생성됨.
2026-04-26:****신뢰성 수정 (Reliability fix)— DeepSeek 사고 모드 (thinking-mode) 재생 실패 및 불필요한 권한 프롬프트 문제 해결.
**2026-04-25:**DeepSeek 지원— 직접적인 DeepSeek 프로바이더 (api.deepseek.com을 통한 V4 Pro / Flash) 및 OpenRouter 경로 지원.
2026-04-25:****API 검증 수정 (API validation fix)— API 검증을 위한 AskUserQuestion 옵션 스키마 수정.
**2026-04-23:**생성된 데모— CRM, LinkedIn, Minecraft 데모 앱 (모두 ClawCodex 자체에 의해 생성됨) 및 README 내 데모 (Demos) 섹션 추가.
2026-04-21:****권한 연결 (Permissions wiring)— --dangerously-skip-permissions를 모든 엔트리포인트 (REPL, TUI, -p)에 연결.
2026-04-20:****최초 공개 릴리스 (Initial public release)— 프로젝트 소스, 문서, 테스트 및 빌드 설정이 포함된 첫 번째 커밋.

ClawCodex는 Claude Code를 프로덕션 지향적으로 재구축한 Python 버전으로, 실제 TypeScript 아키텍처로부터 이식되었으며, 단순한 소스 코드 덤프가 아닌 실제로 작동하는 CLI 에이전트로 제공됩니다.

실제 에이전트 런타임 (Real Agent Runtime)— 도구 호출 루프 (tool-calling loop), 스트리밍 REPL, 세션 히스토리 (session history) 및 멀티 턴 실행 (multi-turn execution)
고충실도 포팅 (High-Fidelity Port)— 원본 Claude Code 아키텍처를 유지하면서 관용적인 Python 스타일로 적응
해킹하기 좋게 설계됨 (Built to Hack On)— 읽기 쉬운 Python 코드베이스, 풍부한 테스트, 그리고 마크다운 기반의 기술 확장성 (skill extensibility)
멀티 LLM 제공업체 (Multi-LLM providers)— 업스트림 (upstream) 대비 가장 큰 진전: Claude Code는 Claude 시리즈 모델만을 중심으로 구축되었으나, ClawCodex는 모든 주요 LLM 제공업체를 연결하는 데 전념하여 에이전트 코딩을 위한 가장 유연하고 비용 효율적인 스택을 선택할 수 있게 합니다.

Python으로 구현된 실제 Claude Code 스타일의 터미널 워크플로: 답변 스트리밍, 도구 호출, 컨텍스트 가져오기, 그리고 기술 (skills)을 통한 동작 확장.

🚀 지금 바로 시도해보세요! 포크(Fork)하고, 수정하고, 당신만의 것으로 만드세요! 풀 리퀘스트 (Pull requests)를 환영합니다!

전체 SWE-bench Verified 분할 데이터셋 (499개 인스턴스, 공개 에이전트 코딩 리더보드)에서, 당사의 표준화된 하네스 (harness) 환경 아래 Gemini 2.5 Pro로 구동된 두 에이전트의 결과는 다음과 같습니다:

에이전트	해결됨 (Resolved)	미해결 (Unresolved)	오류 (Error)
clawcodex	291 / 499 (58.2%)	124	84
openclaude	265 / 499 (53.0%)	144	90

• ✅ 둘 다 해결: 241 🟢
• 🔵 clawcodex만 해결: 50
• ❌ openclaude만 해결: 24
• ⚪ 둘 다 해결 못함: 184

로컬에서 재현하려면 — 전체 워크플로 (누적 배치 처리, --predict-workers N, --capture-traces)를 위해 eval/README.md를 참조하세요.

>>> /stream on
>>> Explain tests/test_agent_loop.py
[streaming answer...]
...

• 직접적인 답변을 위한 실제 API 스트리밍 및 도구 기반 에이전트 루프 중 더욱 풍부한 스트리밍 제공
• 실시간 출력을 위한 내장 /stream 토글 및 필요 시 깔끔한 마크다운 재렌더링을 위한 /render-last 제공 - 텍스트 스트리밍, 가시적인 도구 활동, 안정적인 폴백 (fallback) 동작 등 실제 터미널 데모를 위해 설계됨

---
description: Explain code with diagrams and analogies
allowed-tools:
...

• 마크다운 기반의 SKILL.md 슬래시 명령 (slash commands)
• 프로젝트 기술 (project skills), 사용자 기술 (user skills), 명명된 인자 (named arguments) 및 도구 제한 (tool limits) 지원

ClawCodex의 주요 장점은 **멀티 프로바이더 지원 (multi-provider support)**입니다. Claude Code가 Claude 모델을 타겟으로 하는 반면, 저희는 동일한 에이전트 런타임(agent runtime) 뒤에서 **모든 주요 LLM 프로바이더 (LLM provider)**를 지원하는 것을 목표로 합니다. 따라서 도구 (tools), 기술 (skills), 또는 코딩 루프 (coding loop)를 포기하지 않고도 벤더 (vendors), 지역 (regions), 가격 계층 (price tiers)을 교체할 수 있습니다. 이러한 유연성이 에이전트 기반 코딩 (agentic coding)을 대규모로 실용화할 수 있게 만드는 핵심입니다.

providers = ["anthropic", "openai", "glm", "minimax", "openrouter", "deepseek"] # OpenAI 호환 및 GLM API; 더 추가될 수 있음

기본 (default) 대화형 UI는 인라인 prompt_toolkit + Rich REPL (스크롤백 내 트랜스크립트, 도구 인식 상태 행)입니다. 원할 때 Textual 앱 내 경험을 시작하려면 clawcodex --tui를 사용하거나 REPL 내부에서 **슬래시 명령어 (slash command)**인

/tui

를 사용하세요.

>>> Hello!
Assistant: Hi! I'm ClawCodex, a Python reimplementation...
>>> /help # 명령어 표시
...

clawcodex # 인라인 REPL (기본값)
clawcodex --tui # Textual TUI
clawcodex --stream # 실시간 렌더링이 포함된 REPL
...

--dangerously-skip-permissions 플래그는 해당 세션의 모든 도구 권한 확인을 비활성화합니다. 인터넷 접속이 없는 샌드박스 컨테이너 (sandboxed containers) 또는 VM 내부에서만 사용하는 것을 권장합니다. 프로세스가 root/sudo 권한으로 실행 중일 때는 IS_SANDBOX=1 또는 CLAUDE_CODE_BUBBLEWRAP=1이 설정되지 않은 한 이 플래그는 거부됩니다.

구성 요소 (Component)	상태 (Status)	개수 (Count)
REPL 명령어 (REPL Commands)	✅ 완료 (Complete)	내장 기능 + /tools , /stream , /context , /compact , 기술 (skills) 등.
...
시스템 (System)	상태 (Status)	설명 (Description)
---	---	---
CLI 엔트리 (CLI Entry)	✅	clawcodex , login , config , -p / --print , --tui , --stream , --version
...
카테고리 (Category)	도구 (Tools)	상태 (Status)
---	---	---
파일 작업 (File Operations)	읽기, 쓰기, 편집, Glob, Grep	✅ 완료 (Complete)
...

• ✅
  Phase 0: 설치 및 실행 가능한 CLI - ✅
  Phase 1: 핵심 Claude Code MVP 경험 - ✅
  Phase 2: 실제 도구 호출 루프 (Real tool calling loop) - 🟡
  Phase 3: 컨텍스트 깊이 (Context depth), 권한 통합 (permission integration), /resume

-클래스 복구 (class recovery) (진행 중) - 🟡
Phase 4: MCP 런타임 깊이 (runtime depth), 플러그인 (plugins), 확장성 (extensibility) (도구는 존재하며, 플랫폼 작업은 계속 진행 중) - ⏳
Phase 5: Python 네이티브 차별화 요소 (Python-native differentiators)

상세한 기능 상태 및 PR 가이드라인은 FEATURE_LIST.md를 참조하세요.

git clone https://github.com/agentforce314/clawcodex.git
cd clawcodex
# 가상 환경(venv) 생성 (uv 권장)
...

clawcodex login
# 또는: python -m src.cli login

이 흐름은 다음과 같이 진행됩니다:

• 제공자(provider) 선택 요청: anthropic / openai / glm / minimax / openrouter / deepseek
• 해당 제공자의 API 키 요청
• (선택 사항) 사용자 정의 베이스 URL (base URL) 저장
• (선택 사항) 기본 모델 (default model) 저장
• 선택한 제공자를 기본값으로 설정

설정 파일은 ~/.clawcodex/config.json에 저장됩니다.

. 예시 구조:

{
"default_provider": "anthropic",
"providers": {
...

clawcodex # 인라인 REPL 시작 (python -m src.cli와 동일)
clawcodex --help # 모든 플래그: --tui, -p, --provider, --model, …

끝입니다! 키를 설정한 다음 CLI 또는 REPL을 실행하세요.

명령 (Command)	설명 (Description)
/	명령 및 스킬 (skills) 표시
/help	도움말 텍스트
/tools	레지스트리(registry)에서 도구 이름 목록 표시
/tool <name> <json>	JSON 입력을 사용하여 도구를 직접 실행
/stream	스트리밍 (streaming) 토글: /stream on, off, 또는 toggle
/render-last	마지막 어시스턴트 답변을 Markdown으로 다시 렌더링
/save / /load <id>	세션 유지 또는 복구
/clear	대화 삭제 (또한 /reset, /new 사용 가능)
/tui	Textual TUI로 전환
/skill	스킬 실행 흐름 (skill launcher flow)
/context	워크스페이스 / 프롬프트 컨텍스트 (사용 가능한 경우)
/compact	대화 압축 또는 삭제 (압축이 불가능할 경우 삭제로 대체)
/exit, /quit, /q	종료

스킬(Skills)은 .clawcodex/skills 아래에 저장되는 마크다운(markdown) 기반의 슬래시 명령(slash commands)입니다.

. 각 스킬은 자체 디렉토리에 존재하며 반드시 SKILL.md라는 이름이어야 합니다.

1) 프로젝트 스킬 생성하기

다음 경로를 생성합니다:

<project-root>/.clawcodex/skills/<skill-name>/SKILL.md

예시: