1jehuang/jcode · 제작 Jehu Huang(1jehuang) · 라이선스 MIT · 버전 v0.61.2 · Rust 2024 에디션 · 80개 워크스페이스 크레이트 · ratatui TUI + tokio 비동기 + tract-onnx 로컬 임베딩 · Linux/macOS/Windows · TrendShift 데일리 13위 · 최신 커밋 2026-07-28)
jcode는 터미널에서 실행하는 AI 코딩 에이전트다. curl -fsSL https://jcode.sh/install | bash 한 줄로 설치하고, 터미널에 jcode를 치면 대화형 화면(TUI)이 뜬다. 자연어로 "이 버그 고쳐줘"라고 말하면 에이전트가 파일을 읽고, 코드를 수정하고, 명령을 실행하고, 테스트를 돌린다. 한 번만 실행하는 스크립트 모드(jcode run "...")도 있다.
Claude Code, Codex CLI, Cursor Agent, jcode는 모두 "바깥 껍데기 프로그램(하네스)"이다. 안에 태우는 LLM(두뇌)은 같을 수 있다 — jcode도 Claude·GPT·Gemini를 그대로 쓴다. 차이는 껍데기가 얼마나 무거운가다.
대부분의 하네스는 자바스크립트(Node.js)로 만들어져, 실행하면 무거운 런타임이 통째로 메모리에 올라온다. jcode는 Rust로 밑바닥부터 새로 짜서 그 무게를 걷어냈다. 그래서 세션 하나에 28 MB — 스마트폰 사진 몇 장 용량으로 완전한 코딩 에이전트가 돌아간다. 세션을 10개, 20개 띄우는 다중 세션 작업에서 이 차이가 결정적이 된다.
ratatui라는 Rust 라이브러리로 TUI를 그리고, 초당 1,000프레임 이상 렌더링할 수 있다.2026년 현재 코딩 에이전트 하네스는 수십 개가 경쟁 중이다(TrendShift 데일리 상위권이 죄다 하네스·스킬·에이전트다). 이 레드오션에서 jcode가 순위에 오른 이유는 "측정 가능한 우위"와 "남들이 안 한 기능" 두 가지다.
jcode는 README 첫 화면을 경쟁 도구 8종과의 정량 비교표로 채운다. 자원 효율을 마케팅이 아니라 재현 가능한 숫자로 내세운 것이다.
| 지표 (1 세션 기준) | jcode | Claude Code | Codex CLI |
|---|---|---|---|
| 램(PSS) · 임베딩 끔 | 27.8 MB | 386.6 MB | 140.0 MB |
| 첫 화면까지 시간 | 14.0 ms | 3,436.9 ms | 882.8 ms |
| 첫 입력 반응 | 48.7 ms | 3,512.8 ms | 905.8 ms |
| 세션 10개 총 램 | 260.8 MB | 2,300.6 MB | 334.8 MB |
| 세션 추가당 램 증가 | ~10.4 MB | ~212.7 MB | ~21.6 MB |
혼자 세션 한 개만 쓰면 386 MB든 28 MB든 체감이 없다. 하지만 요즘 에이전트 워크플로는 여러 세션을 동시에 띄워 병렬로 일을 시킨다(스웜). Claude Code로 세션 10개를 띄우면 램 2.3 GB가 날아가지만, jcode는 261 MB로 끝난다. 노트북 한 대에서 몇 배 많은 에이전트를 동시에 굴릴 수 있다는 뜻이다.
대부분의 하네스에서 기억(memory)은 에이전트가 "메모리 저장 도구"를 직접 불러야 작동한다. 토큰도 많이 먹고, 자주 까먹는다. jcode는 여기에 임베딩 기반 자동 회상을 넣었다. 대화의 매 턴을 의미 벡터로 바꿔 저장하고, 새 턴마다 코사인 유사도로 관련 기억을 그래프에서 찾아 자동으로 대화에 끼워 넣는다. 에이전트가 도구를 부르지 않아도, 사람이 문득 관련 기억을 떠올리듯 정보가 딸려 온다는 것이다.
같은 저장소에 에이전트 여럿을 띄우면 서버가 이들을 자동 관리한다. A가 파일을 고치면, 그 파일을 읽었던 B에게 "발밑의 코드가 바뀌었다"고 알린다. 에이전트끼리 DM·브로드캐스트로 메시지도 주고받는다. 여기에 셀프데브(self-dev) — 에이전트에게 "자기 개발 모드로 들어가"라고 하면 jcode가 자기 자신의 소스코드를 고치고, 빌드하고, 자기 바이너리를 새로 로드해 계속 작업한다. 자기를 개조하는 하네스라는 점이 커뮤니티의 흥미를 끌었다.
인상적인 수치와 기능에도 불구하고 jcode는 버전 0.61.2, 사실상 1인(Jehu Huang) 프로젝트다. iOS 앱·자체 터미널(handterm)·새 git 대체 원시타입 등은 아직 "계획/진행 중"이다. 벤치마크도 저자 본인 머신 단일 측정치라 환경에 따라 달라질 수 있다. 프로덕션 도입 전엔 직접 재보는 것이 안전하다.
jcode의 핵심 설계 결정은 "모든 걸 Rust 하나로"다. Node.js·Python 런타임을 끼지 않기 때문에 시작이 빠르고 메모리가 작다. Rust 2024 에디션을 쓰며, 워크스페이스는 80개 크레이트로 잘게 나뉘어 있다.
| 영역 | 사용 기술 | 역할 |
|---|---|---|
| 언어 | Rust (2024 edition) | 메모리 안전 + 무 GC + 네이티브 속도 |
| 비동기 런타임 | tokio | 네트워크·파일·프로세스·시그널 동시 처리 |
| 메모리 할당자 | jemalloc (tikv-jemallocator) | 다중 세션에서 파편화 억제, 램 절감 |
| HTTP 클라이언트 | reqwest (rustls-tls) | LLM API 호출 · OpenSSL 불필요(순수 Rust TLS) |
| 웹소켓 | tokio-tungstenite | 스트리밍 응답 · 실시간 세션 통신 |
| 직렬화 | serde / serde_json | NDJSON 프로토콜 프레임 인코딩 |
| 영역 | 사용 기술 | 역할 |
|---|---|---|
| TUI 프레임워크 | ratatui 0.30 | 터미널에 패널·표·위젯 렌더링 |
| 터미널 백엔드 | crossterm 0.29 | 키 입력·마우스·화면 제어(크로스 플랫폼) |
| 다이어그램 | mermaid-rs-renderer (자작) | 브라우저·TS 없이 mermaid 렌더 · 1800배 빠름 |
| 자체 터미널 | handterm (자작, WIP) | 네이티브 스크롤 API + 고효율 스크롤백 |
| 데스크탑 앱 | jcode-desktop / desktop2 | GUI 클라이언트(7만+2.5만 줄) |
| 영역 | 사용 기술 | 역할 |
|---|---|---|
| 로컬 임베딩 | tract-onnx + tract-hir + tokenizers | 순수 Rust ONNX 추론 — PyTorch 없이 벡터 생성 |
| 메모리 회상 | 의미 벡터 그래프 + 코사인 유사도 | 관련 기억 자동 주입 · 세션 RAG 검색 |
| 도구 프로토콜 | MCP (stdio 서버) | 외부 도구 연결 · Claude Code 설정 호환 |
| 제공자(Provider) | 30+ (claude/openai/gemini/copilot…) | OAuth 구독 로그인 + OpenAI 호환 엔드포인트 |
jcode login --provider claude). Claude·ChatGPT·Gemini·Copilot은 물론 OpenRouter·DeepSeek·Ollama·vLLM 같은 OpenAI 호환 엔드포인트까지 30종 이상. /account로 계정 여러 개를 즉시 갈아탈 수도 있다(토큰 소진 시 유용).jcode의 뼈대는 서버-클라이언트 분리다. 에이전트의 실제 두뇌(런타임)는 백그라운드 서버에 살고, TUI·데스크탑·스크립트는 그 서버에 붙는 화면(클라이언트)일 뿐이다. 그래서 Claude Code로 시작한 세션을 jcode로 이어받거나, 한 세션에 여러 클라이언트가 붙는 게 가능하다.
클라이언트와 서버는 jcode-harness-api라는 "안정된 계약"으로만 대화한다. 규칙이 엄격하다. 모든 프레임은 한 줄짜리 JSON 객체(NDJSON), 매 프레임은 프로토콜 버전 v를 달고 다니며, 클라이언트는 모르는 필드·이벤트는 무시해야 한다. 덕분에 서버가 새 기능을 추가해도(마이너 버전↑) 옛 클라이언트가 깨지지 않는다. 깨는 변경만 메이저 버전을 올리고 핸드셰이크에서 협상한다.
이건 "국제 우편 규격" 같은 것이다. 봉투 겉면(버전·주소)만 표준을 지키면, 안에 새로운 서류를 넣어도 우체국이 문제없이 배달한다. 받는 쪽이 모르는 서류가 들어 있으면 그냥 무시하고 아는 것만 처리한다. 그래서 보내는 쪽과 받는 쪽이 서로 다른 버전이어도 통신이 안 끊긴다.
80개 크레이트로 쪼갠 건 취향이 아니라 전략이다. ...-types 크레이트(예: jcode-message-types, jcode-memory-types)는 데이터 모양만 정의하고, ...-runtime 크레이트가 실제 동작을 담는다. AGENTS.md에는 "의존성 경계 래칫(dependency-boundary ratchet)"과 "와일드카드 재수출 금지" 가드레일이 있어, CI가 크레이트 간 잘못된 의존을 자동으로 막는다. 이렇게 잘게 나눠야 부분 재컴파일이 빨라지고, 셀프데브에서 에이전트가 자기 코드를 고칠 때 영향 범위가 좁아진다.
Cargo.toml에는 ratatui·crossterm 같은 렌더링 크레이트를 디버그 빌드에서도 최적화(opt-level)해 컴파일하라는 특수 프로파일이 잔뜩 있다. "매 TUI 프레임이 ratatui 버퍼를 셀 단위로 훑는다"는 주석과 함께다. 즉 렌더 핫패스만 골라 최적화해, 개발 중에도 초당 1,000프레임을 유지한다. "키 입력→화면 반영" 시간을 매 프레임 기록·노출하는 계측까지 최근 커밋에 들어갔다.
jcode는 성능을 나중에 튜닝하는 대상이 아니라 아키텍처 제약으로 못 박았다. 타입/런타임 크레이트 분리, 의존성 래칫, 렌더 크레이트 선택적 최적화, 코드-크기·패닉·삼킨-에러 래칫까지 — CI가 이 모든 걸 회귀 방지선으로 지킨다. "빠르고 작게"를 사람의 의지가 아니라 자동 게이트로 유지하는 방식이 이 레포의 가장 큰 교훈이다.
crates/ 아래 80개 크레이트에 있다
구조에서 두 가지가 눈에 띈다. 첫째, 루트 src/는 얇고 크레이트가 무겁다 — 진입점만 루트에 두고 로직은 전부 크레이트로 위임하는 전형적인 대형 Rust 워크스페이스 패턴이다. 둘째, docs/에 40개가 넘는 설계 문서가 있다(멀티세션·스웜·메모리 아키텍처, 코드 품질 감사, 제안서 등). 1인 프로젝트치고 문서화 밀도가 매우 높은데, 이는 AI 에이전트가 이 문서를 읽고 셀프데브를 하도록 의도된 것이기도 하다.
80개 크레이트가 어떻게 순환 의존 없이 계층을 이루는지가 살아있는 교과서다. 타입 크레이트(-types)를 바닥에 깔고, 런타임 크레이트가 그 위에 얹히는 패턴, Cargo.toml의 [profile.*.package.*]로 특정 크레이트만 최적화하는 기법, CI 가드레일로 경계를 강제하는 방법을 실전 규모로 볼 수 있다.
"매 턴을 벡터로 저장 → 코사인 유사도로 관련 기억 회수 → 대화에 주입"이라는 RAG(검색 증강 생성)의 최소 실전 형태를 하네스 안에서 볼 수 있다. 게다가 이 임베딩을 클라우드 API가 아니라 로컬 ONNX로 돌린다는 점이, "프라이버시 + 비용 0 + 오프라인"을 어떻게 달성하는지 보여준다.
"첫 프레임 14 ms", "세션당 램 10 MB" 같은 수치를 어떻게 재현 가능하게 측정하는지(PTY 10회 실행, p50/p95 범위)가 README에 그대로 있다. tui_bench·memory_recall_bench 같은 벤치 바이너리를 직접 돌려보며 "성능을 숫자로 말하는" 습관을 익힐 수 있다.
Claude Code 같은 도구를 "블랙박스"로 쓰기만 했다면, jcode는 그 뚜껑을 열어준다. 프로바이더 추상화, 스트리밍 처리, 도구 호출(MCP), 세션 저장·재개, KV 캐시 최적화, 권한 UI가 각각 어떤 크레이트에 어떻게 구현됐는지 추적할 수 있다. "에이전트 grep"(파일 구조 정보를 grep 결과에 얹어 컨텍스트 절약) 같은 실전 최적화 아이디어도 얻는다.
① 벤치 재현: jcode를 설치해 jcode를 띄우고, 다른 CLI 하네스와 /usr/bin/time -v·ps로 램을 직접 비교해 본다. README 수치가 내 환경에서 얼마나 재현되는지 확인.
② 로컬 모델 붙이기: Ollama를 깔고 jcode login --provider ollama로 로컬 LLM을 연결해, API 비용 0으로 에이전트를 돌려 본다.
③ 크레이트 그래프 그리기: cargo tree로 크레이트 의존 관계를 뽑아, -types/-runtime 계층이 실제로 어떻게 갈리는지 직접 시각화.
| 구분 | 요구사항 |
|---|---|
| 실행 OS | Linux · macOS · Windows 11(PowerShell 5.1+) |
| 설치 | 바이너리 1개 — curl … | bash 또는 irm …ps1 | iex |
| 실행 램 | 세션당 ~28 MB(임베딩 끔) / ~167 MB(로컬 임베딩 켬) |
| 런타임 의존성 | 없음(정적 바이너리) · Node/Python 불필요 |
| LLM | 구독 계정(Claude/ChatGPT 등) 또는 API 키, 혹은 로컬 Ollama/LM Studio/vLLM |
| 소스 빌드 | Rust stable + cargo · 증분 디버그 빌드 약 1분(저자 머신) — 리소스 부족 시 scripts/remote_build.sh로 원격 빌드 권장 |
jcode를 쓰는 것은 초경량이지만, 소스에서 컴파일하는 것은 무겁다. 80개 크레이트 + 26만 줄 Cargo.lock 탓에 최초 빌드는 오래 걸리고 램·CPU를 많이 쓴다. 셀프데브를 진짜로 돌리려면 넉넉한 개발 머신(또는 원격 빌드)이 필요하다. 저자도 "빌드가 죽으면 리소스 부족 때문이니 원격 빌드를 쓰라"고 안내한다.
curl -fsSL https://jcode.sh/install | bash로 설치 후 jcode 실행. 구독 계정으로 jcode login --provider claude(또는 openai) 로그인하고, "이 폴더 구조 설명해줘" 같은 간단한 요청을 던져 본다. Alt+C로 정렬 전환, /model로 모델 변경도 시도.
jcode와 다른 하네스(Claude Code 등)를 각각 띄우고 ps -o rss·time으로 램과 시작 시간을 직접 측정해 README 표와 비교. 로컬 임베딩을 켠/끈 두 경우(167 MB vs 28 MB) 차이도 확인한다.
Ollama에 qwen3-coder 같은 코딩 모델을 받고 jcode --provider ollama --model … run "hello"로 연결. vLLM을 띄웠다면 jcode provider add로 OpenAI 호환 엔드포인트를 등록해, API 비용 없이 코딩 에이전트를 굴려 본다.
같은 저장소에 세션 2~3개를 띄워, 한쪽이 파일을 고칠 때 다른 세션에 "코드가 발밑에서 바뀌었다" 알림이 오는지 관찰. 에이전트에게 스웜 툴로 서브 에이전트를 스폰해 작업을 나눠 시켜 본다.
레포를 클론해 cargo build로 직접 빌드하고(원격 빌드 고려), jcode-embedding 또는 jcode-harness-api 크레이트를 통째로 읽어 "로컬 임베딩이 어떻게 벡터를 만드는가" 또는 "NDJSON 프레임이 어떻게 정의되는가"를 추적. 여유가 되면 셀프데브 모드로 사소한 문구 하나를 에이전트에게 고치게 해 본다.
| 주차 | 주제 | 학습 내용 |
|---|---|---|
| 1주차 | Rust 비동기 · 워크스페이스 | tokio 기본, 멀티 크레이트 워크스페이스, cargo tree·프로파일. 목표: jcode 크레이트 지도 읽기 |
| 2주차 | 터미널 UI(ratatui) | ratatui 위젯·버퍼 렌더링, crossterm 입력 처리. 목표: 간단한 TUI 앱 직접 제작 |
| 3주차 | 임베딩 · RAG · 로컬 추론 | 문장 임베딩, 코사인 유사도, 벡터 검색, ONNX/tract 로컬 추론. 목표: 미니 메모리 그래프 구현 |
| 4주차 | LLM 하네스 · MCP · 스트리밍 | 프로바이더 추상화, OpenAI/Anthropic 스트리밍, MCP 도구 프로토콜, 세션 저장/재개. 목표: 초소형 하네스 프로토타입 |
mcp.json 설정도 호환한다.README.md·AGENTS.md·docs/를 볼 것