mlx-code 소개: Mac을 위해 구축된 구성 가능하고 Git으로 격리된 코딩 에이전트

Apple Silicon 기반의 로컬 AI 개발은 믿을 수 없을 정도로 빠르게 발전하고 있지만, 로컬 코딩 에이전트를 실행할 때는 보통 두 가지 큰 골칫거리가 따릅니다. 바로 시간이 지날수록 느려지는 **비대해진 컨텍스트 윈도우 (context windows)**와 에이전트가 통제를 벗어났을 때 발생하는 **파괴적인 코드 편집 (destructive code edits)**입니다.

**mlx-code**가 등장했습니다.

이 도구는 네이티브 MLX 추론 서버, 터미널 하네스 (terminal harness), git worktree 격리, 그리고 구성 가능한 멀티 에이전트 프리미티브 (multi-agent primitives)를 하나의 오프라인 우선 (offline-first) Python 패키지로 묶었습니다. 완전히 로컬에서 실행하거나, 표준 셸 스크립트에 파이프 (pipe)로 연결하거나, 원격 API로 교체하여 사용할 수 있습니다.

내부적으로 표준 도구 호출 (tool-calling) 세션이 어떻게 작동하는지 보여주는 예시입니다:

user@mac:~$ mlc --model mlx-community/Qwen3.6-27B-OptiQ-4bit
[System] Apple Silicon에서 로컬 MLX 서버 부팅 중...
[System] 워크스페이스가 격리된 git worktree로 스냅샷됨.
...

무엇이 다른가?

1. Git Worktree 격리

AI가 현재 작업 중인 디렉토리를 무모하게 (YOLO-edit) 편집하도록 내버려 두는 대신, mlx-code는 매 세션마다 새로운 git worktree를 할당합니다. 모든 도구 상호작용과 대화 상태는 자동으로 로컬 git 커밋 (commit)으로 캡처됩니다. 만약 에이전트가 환각 (hallucination)을 일으키거나 빌드를 깨뜨리더라도, 워크스페이스 타임라인은 전적으로 사용자의 통제 하에 있습니다. 그냥 롤백 (roll back)하면 됩니다.

2. 내장된 컨텍스트 저하 완화 (Context Decay Mitigation)

긴 코딩 세션은 컨텍스트 제한이 채워짐에 따라 LLM의 성능을 저하시킵니다. mlx-code는 기본 에이전트가 무거운 하위 작업(예: 특정 유닛 테스트 작성)을 위해 샌드박스화된 하위 에이전트 (sub-agents)를 생성할 수 있게 함으로써 이 문제를 근본적으로 해결합니다. 하위 에이전트가 힘든 작업을 수행하고 종료된 후 최종 결과만 반환하므로, 기본 컨텍스트를 깨끗하게 유지할 수 있습니다.

3. 완전한 구성 가능성 (Absolute Composability)

프레임워크 전체가 모듈식입니다. 터미널에서 직접 완전히 다른 로컬 또는 원격 모델 간에 출력을 파이프 (pipe)로 연결하거나, 순수 Python으로 병렬 에이전트 워크플로 (workflows)를 구축할 수 있습니다.

빠른 시작

단 두 줄로 내장된 로컬 REPL 하네스에 바로 진입할 수 있습니다:

pip install mlx-code
mlc

UNIX 스타일 파이프의 강력함

표준 셸 아키텍처 (shell architecture)를 사용하여 복잡한 에이전트 작업들을 하나로 엮을 수 있습니다. 이는 mlx-code가 표준 출력 (stdout)을 네이티브하게 처리하기 때문입니다:

# 완전히 다른 백엔드(backends)를 가로질러 생성된 솔루션을 비평(Critique)하기
echo "explain lsp.py" | mlc-run -a deepseek | cat - PLAN.md | mlc-run --url http://localhost:9000

Python에서의 병렬 에이전트 (Concurrent Agents)

군집 (swarm)이 필요하신가요? asyncio를 사용하여 병렬 연구자 (parallel researchers)를 실행함으로써 맞춤형 로컬 워크플로우 (local workflows)를 구축할 수 있습니다:

import asyncio
from mlx_code.repl import Agent

...

확장하기 (Extending It)

커스텀 도구 (custom tool)를 추가하는 과정에는 보일러플레이트 (boilerplate) 코드가 전혀 필요하지 않습니다. Tool을 상속받고, 파라미터를 위한 Pydantic 스키마 (schema)를 매핑한 뒤, 바로 사용하면 됩니다:

from mlx_code.tools import Tool
from mlx_code.repl import Agent
from pydantic import BaseModel, Field
...

💬 함께 논의해봐요

이 저장소는 완전히 오픈 소스이며 바로 테스트해 볼 수 있습니다:

GitHub Repository

Watch the YouTube Demo

현재 로컬 개발자 에이전트 (local developer agents)를 실행할 때 발생하는 컨텍스트 윈도우 (context window) 비대화 문제를 어떻게 해결하고 계신가요?