Maclaw: 맥용 미니멀 AI 에이전트

1. 핵심 요약 (Executive Summary)

Maclaw (Pi 기반 미니멀 AI 에이전트)
https://github.com/junsang-dong/vibe_0203_maclaw_v1

Maclaw는 Pi 철학을 계승한 미니멀 AI 에이전트로, 사용자가 선호하는 로컬 또는 클라우드 컴퓨팅 환경에서 에이전트 기능을 유연하게 활용할 수 있도록 설계된 프로젝트입니다. 현재 Mac과 Sublime Text 환경을 중심으로 한 MVP(Minimum Viable Product) 단계에 있으며, Express 기반의 서버 아키텍처를 통해 다양한 LLM(OpenAI, Anthropic, Google)과의 연동 및 JSON-RPC 스트리밍을 지원합니다.

본 프로젝트의 핵심 가치는 **’최소 의존성’**과 **’에디터 중심의 워크플로우’**에 있으며, 로컬 실행을 우선하되 클라우드 확장이 용이한 구조를 갖추고 있습니다. 특히 보안을 고려한 터미널 명령 승인 플로우와 세션 기반의 대화 기록 관리 기능을 통해 실무적인 개발 환경에서의 활용성을 극대화한 것이 특징입니다.

기능 분류	주요 기능	설명
에이전트 서버	Express 기반 로컬 서버 및 엔드포인트	에이전트의 핵심 로직을 처리하며, 세션 관리 및 작업 프로세싱을 위한 API 제공
세션 관리	디스크 기반 세션 저장 및 히스토리 기록	대화 내역을 로컬 디스크에 저장하고 세션 생성, 조회 및 전체 목록 기능을 제공
LLM 연동	다중 LLM 및 Mock LLM 지원	OpenAI, Anthropic, Google 모델의 REST API 호출 및 에러 상세 분기 처리
스트리밍	JSON-RPC + Native SSE 스트리밍	LLM의 SSE 스트림을 읽어 델타 및 툴 호출 이벤트를 클라이언트에 전송
도구 레이어	파일 시스템 조작 및 터미널 실행	파일 읽기/쓰기/수정 및 Bash 명령 실행을 지원하며 프로젝트 루트로 작업 경로 제한
플러그인	Sublime Text 에디터 연동	인라인 diff, 수락/거부 UI, 대화 기록 출력 등 에디터 중심의 워크플로우 제공

2. 주요 아키텍처 및 기술적 구성

2.1 에이전트 서버 (Express 기반)

Maclaw의 심장부는 Express 기반의 로컬 서버로 구성되어 있으며, 다음과 같은 핵심 기능을 수행합니다.

• 엔드포인트 관리: 헬스체크(/health), 프로세스 처리(/api/agent/process), 세션 관리 등의 API를 제공합니다.
• JSON-RPC 2.0: 표준화된 통신 규격인 JSON-RPC 2.0을 통해 클라이언트와 상호작용하며, 특히 /rpc 엔드포인트를 통해 스트리밍을 지원합니다.
• Native SSE 스트리밍: LLM의 응답 및 툴 호출(Tool Call) 이벤트를 SSE(Server-Sent Events)를 통해 실시간으로 전송합니다.

2.2 LLM 연동 및 추상화

다양한 AI 모델을 유연하게 선택하여 사용할 수 있는 레이어를 구축했습니다.

• 지원 모델: OpenAI, Anthropic, Google REST API 호출을 구현하였습니다.
• Mock LLM: 테스트 및 개발 편의를 위해 가상의 응답을 생성하는 Mock LLM 기능을 포함합니다.
• 에러 처리: 권한 미달, 쿼터 초과, 미지원 모델 등 상세한 분기 처리를 통해 안정성을 확보했습니다.

2.3 세션 및 데이터 관리

• 디스크 기반 저장: .ai-agent/sessions/ 경로에 대화 히스토리를 저장하여 지속성을 보장합니다.
• 기능: 세션 생성, 조회, 목록화 기능을 통해 과거 작업 내역을 체계적으로 관리합니다.

3. 기능적 특징 및 도구 레이어

3.1 기본 도구(Tool) 시스템

에이전트가 실제 환경에서 작업을 수행할 수 있도록 기본적인 도구 레이어를 제공합니다.

• 파일 조작: 파일 읽기(Read), 쓰기(Write), 편집(Edit) 기능.
• 명령 실행: Bash 명령 실행 지원.
• 제약 사항: 보안을 위해 프로젝트 루트 내로 작업 경로를 제한합니다.

3.2 안전한 실행 환경 (Terminal Approval)

터미널 명령 실행 시 발생할 수 있는 위험을 방지하기 위해 승인 기반의 플로우를 도입했습니다.

• 프로세스: 명령 요청(request) → 사용자 확인 및 승인 → 실제 실행(execute).
• 사용자 인터페이스: Sublime Text 플러그인을 통해 승인 팝업을 출력합니다.

4. Sublime Text 플러그인 통합

Maclaw는 개발자의 워크플로우 내에 직접 통합되는 것을 목표로 하며, Sublime Text를 위한 MVP 플러그인을 제공합니다.

주요 기능	상세 설명
스트리밍 출력	LLM의 응답을 Output Panel에 실시간으로 출력
인라인 Diff	코드 수정 제안 시 인라인 Diff 팝업을 통해 수락/거부 UI 제공
컨텍스트 인식	현재 열려 있는 문서의 전체 텍스트를 AI 요청 시 컨텍스트로 포함
대화 관리	세션별/전체 대화 기록을 컬러 구분이 포함된 팝업으로 출력
UI 분리	사용자의 요청 영역과 AI의 응답 영역을 명확히 분리하여 출력

5. 배포 및 운영 전략

5.1 배포 모델

1. 로컬 우선 (Local First): 사용자의 개인 환경에서 직접 실행하여 지연 시간을 최소화하고 제어권을 확보합니다.
2. 클라우드 확장: Node.js 20+ 환경이나 Docker/Compose를 통해 서버를 클라우드로 배포할 수 있습니다.
3. 최소 의존성 유지: 작은 런타임과 단순한 배포 구조를 지향합니다.

5.2 운영 지침 및 보안

• API 키 관리: LLM API 키는 서버측(~/.ai-agent/config.json 또는 환경변수)에만 저장하고 클라이언트에 노출하지 않습니다.
• 프록시 설정: Nginx 사용 시 스트리밍 연결을 위해 proxy_buffering off 및 충분한 타임아웃(3600s) 설정이 권장됩니다.
• 로그 보안: 로그 기록 시 API 키나 민감한 프롬프트 내용이 남지 않도록 주의합니다.

6. 프로젝트 로드맵

Maclaw는 MVP 단계를 넘어 다음과 같은 단계로 확장을 계획하고 있습니다.

1. MVP 안정화: 스트리밍, 세션 처리, 툴 호출 안정성 확보.
2. UX 고도화: 인라인 Diff 고도화, 부분 수락 기능, 실시간 상태 표시 기능 강화.
3. 툴 실행 루프 (Tool Loop): 툴 호출부터 실행, 결과 반영까지 이어지는 자율적 루프 완성.
4. 배포 가이드 정리: 로컬과 클라우드가 통합된 형태의 실행 가이드 및 환경 구성 표준화.