Gemma 4와 Pi Coding Agent로 완전히 로컬에서 실행하는 코딩 에이전트 만들기 (feat. LM Studio)

9bow · 5월 3, 2026, 3:30오전

로컬 코딩 에이전트가 필요한 이유

지난 1~2년 동안 Claude Code, Cursor, Aider, OpenAI Codex 등 다양한 코딩 에이전트가 등장하면서, 개발자들이 터미널과 에디터에서 LLM을 일상적으로 활용하는 흐름이 자리잡았습니다. 그러나 이러한 도구 대부분은 클라우드 기반의 프론티어 모델(GPT, Claude, Gemini 등)에 의존하기 때문에, 작업 중인 코드와 파일 컨텍스트가 외부 서버로 전송된다는 점, 그리고 토큰 사용량에 비례해 비용이 발생한다는 점은 여전히 현실적인 부담으로 남아 있습니다.

이러한 맥락에서 최근 들어 다시 주목받고 있는 흐름이 바로 로컬 코딩 에이전트(local coding agent) 입니다. Llama 3, Qwen 3, DeepSeek-V3, 그리고 Gemma 4에 이르기까지, 오픈 가중치(open-weight) 모델들이 함수 호출(function calling), 시스템 프롬프트, 사고(thinking) 모드 등 에이전트 워크로드에 필수적인 기능을 점차 갖추면서, 노트북이나 워크스테이션에서 로컬로 실행하는 것만으로도 실용적인 코딩 도우미를 구성할 수 있게 되었습니다.

이번 글에서는 Patrick Loeber가 자신의 블로그에 정리한 가이드를 바탕으로, LM Studio와 Mario Zechner가 만든 미니멀 터미널 코딩 에이전트인 Pi(pi-coding-agent), 그리고 Google의 Gemma 4 26B A4B 모델을 결합하여 완전히 로컬에서 동작하는 코딩 에이전트를 구축하는 방법을 단계별로 살펴봅니다. 모든 추론이 사용자의 하드웨어에서 이루어지므로 데이터 외부 유출 우려가 없고, API 비용 또한 발생하지 않는다는 것이 가장 큰 장점입니다.

핵심 구성 요소: LM Studio + Pi Agent + Gemma 4

원문이 제안하는 권장 셋업은 다음과 같이 세 가지 컴포넌트의 조합입니다.

모델 서버: LM Studio가 모델 다운로드, 양자화, OpenAI 호환 로컬 API 서버 노출까지 담당합니다. CLI 환경을 선호한다면 Ollama나 llama.cpp의 llama-server도 동일하게 사용할 수 있습니다. 세 도구 모두 OpenAI 호환 엔드포인트를 노출하므로 Pi 입장에서는 어떤 것을 사용해도 무방합니다.
코딩 에이전트 하네스: Pi는 macOS, Linux, Windows에서 동작하는 터미널 기반 코딩 에이전트로, 모델에게 read, write, edit, bash 단 네 가지 기본 도구만 제공하는 의도적으로 작은 코어를 가집니다.
모델: Gemma 4, 그중에서도 26B 파라미터 중 토큰당 4B만 활성화되는 Mixture-of-Experts(MoE) 모델인 gemma-4-26b-a4b가 권장됩니다. Apache 2.0 라이선스로 공개되어 있어 상업적 활용도 자유롭습니다.

이 조합의 핵심은 "프론티어급 모델을 흉내내려 하지 않고, 작은 도구 셋과 잘 정돈된 컨텍스트만으로 로컬 모델이 실제로 잘 동작할 수 있는 환경을 만들어 준다"는 점에 있습니다. 시스템 프롬프트가 작고 토큰 효율이 높다는 Pi의 특성은, 컨텍스트 윈도우가 상대적으로 빠듯한 로컬 모델 환경에서 특히 중요한 의미를 가집니다.

Gemma 4 모델 라인업과 26B A4B 권장 이유

Gemma 4는 Google이 발표한 최신 오픈 가중치(open-weight) 모델 패밀리로, 이전 Gemma 2, Gemma 3와 비교했을 때 코딩과 에이전트 활용에서 한 단계 도약한 모델로 평가됩니다. 네이티브 함수 호출(function calling), 시스템 프롬프트 지원, 사고(thinking) 모드를 제공하여 로컬 코딩 에이전트의 베이스 모델로 적합한 형태가 되었습니다.

모델 크기	아키텍처 유형	컨텍스트 길이
Gemma 4 E2B	Dense	128K tokens
Gemma 4 E4B	Dense	128K tokens
Gemma 4 26B A4B	Mixture of Experts (MoE)	256K tokens
Gemma 4 31B	Dense	256K tokens

원문 저자의 추천은 명확합니다. Gemma 4 26B A4B 를 사용하라는 것입니다. 이 모델은 총 26B 파라미터를 갖되 토큰당 4B만 활성화하는 MoE 구조로, 추론 속도는 작은 모델에 가깝지만 품질은 훨씬 큰 모델 수준을 유지합니다. 텍스트는 물론 이미지 이해, 함수 호출, 사고 모드까지 모두 지원하므로 코딩 에이전트가 요구하는 기능을 폭넓게 충족합니다.

다만 여기에는 한 가지 주의점이 있습니다. 활성 파라미터가 4B에 불과하더라도, 빠른 라우팅을 위해서는 26B 전체 파라미터가 메모리에 로드되어야 한다는 점입니다. 즉 VRAM 요구량은 일반적인 dense 26B 모델에 가깝습니다. VRAM이 부족하다면 Gemma 4 E4B가 대안이 될 수 있는데, 크기에 비해 놀라울 만큼 좋은 성능을 보이지만 더 구체적인 프롬프트와 가이드가 필요합니다.

LM Studio에서 모델을 다운로드할 때는 GGUF 양자화 버전을 선택합니다. 가용 VRAM에 따른 권장 양자화는 다음과 같습니다.

양자화	다운로드 크기	품질
Q4_K_M	18 GB	균형 잡힌 선택
Q6_K	24 GB	더 높은 품질
Q8_0	28 GB	거의 원본 수준

Mac 환경이라면 MLX 포맷의 Gemma 4 빌드도 확인해 볼 만합니다. MLX는 Apple Silicon에 네이티브로 최적화되어 있어 M 시리즈 칩에서는 GGUF 대비 더 빠른 추론 속도를 보일 수 있습니다.

LM Studio로 로컬 OpenAI 호환 서버 실행

LM Studio는 macOS, Windows, Linux를 모두 지원하는 데스크톱 앱으로, 모델 다운로드와 GGUF/MLX 양자화 관리, 그리고 OpenAI 호환 로컬 API 서버 실행을 GUI에서 한꺼번에 처리할 수 있게 해줍니다. 설치 후 작업 흐름은 다음과 같습니다.

먼저 LM Studio 안에서 gemma-4-26b-a4b를 검색하여 원하는 양자화 GGUF 버전(예: Q4_K_M)을 다운로드합니다. 다운로드가 끝나면 Developer 탭으로 이동하여 받은 모델을 선택한 뒤 Start Server 버튼을 누릅니다. 기본적으로 http://localhost:1234에서 서버가 실행되며, OpenAI 호환 API를 제공합니다.

서버가 정상 동작하는지 확인하려면 다음과 같이 모델 목록 엔드포인트를 호출해 봅니다. 코드 내 주석은 원문 그대로 영어로 유지합니다.

# Verify the local server is up and lists your loaded model
curl http://localhost:1234/v1/models

컨텍스트 크기와 GPU 오프로드 설정

본격적인 작업에 들어가기 전에 Model Settings 화면에서 컨텍스트 크기와 GPU 오프로드 설정을 점검하는 단계가 매우 중요합니다. 컨텍스트 크기는 곧 VRAM 사용량과 직결되며, 모델 가중치가 차지하는 기본 VRAM 위에 추가적으로 누적되는 메모리이기 때문입니다. Gemma 4 26B A4B 모델은 최대 256K 토큰까지 지원하지만, 실제 코딩 작업에서 그 전체를 다 사용할 일은 많지 않습니다.

사용 사례	컨텍스트 크기	추가 VRAM (대략)
단일 파일 소규모 편집	16K	~1 GB
일반적인 코딩 세션	64K	~4 GB
멀티 파일 리팩토링	128K	~8 GB
전체 저장소 컨텍스트	256K	~16 GB

원문 저자는 가용 VRAM이 허락한다면 128K 컨텍스트를 기본값으로 추천합니다. 코딩 에이전트는 한 세션 동안 파일 내용, 도구 출력, 대화 이력 등을 빠르게 누적하기 때문에, 작업 중간에 컨텍스트가 부족해지는 상황은 생산성에 큰 타격을 줍니다.

다행히 Pi에는 이러한 문제를 다루는 내장 세션 관리 기능이 잘 갖추어져 있습니다. /compact 명령은 오래된 메시지를 요약하여 컨텍스트를 비워주고, /new는 완전히 새 세션을 시작하며, /tree로 세션 이력을 탐색해 임의의 이전 시점으로 점프할 수 있습니다. /fork를 사용하면 과거의 특정 메시지에서 새 세션을 분기하여, 기존 흐름을 잃지 않고 다른 방향의 시도를 병행할 수 있습니다.

또한 GPU Offload 설정은 모델의 몇 개 레이어를 GPU에 올리고 몇 개를 시스템 RAM에 둘지를 결정합니다. GPU에 올라가는 레이어가 많을수록 추론이 빠르지만, 그만큼 VRAM이 더 필요합니다. GPU 메모리에 모델 전체가 들어가지 않으면 LM Studio가 자동으로 GPU와 CPU에 분할 배치하므로, 동작 자체는 가능하지만 CPU 구간에서 속도가 떨어집니다. 메모리 부족(out-of-memory) 오류가 발생한다면, GPU 오프로드 비율을 조정하기 전에 컨텍스트 크기를 먼저 줄여보는 것이 일반적으로 더 효과적입니다.

Pi Coding Agent 설치와 철학

Pi는 Mario Zechner가 개발한 미니멀 터미널 코딩 하네스로, 코어가 의도적으로 작게 설계되어 있다는 점이 가장 큰 특징입니다. 모델은 기본적으로 read, write, edit, bash 네 가지 도구만을 사용하며, 그 외의 기능은 모두 확장(extensions), 스킬(skills), 프롬프트 템플릿, 테마 등의 형태로 추가됩니다.

이러한 설계는 Pi의 철학(philosophy)에 명시적으로 드러나 있습니다. Pi는 MCP를 내장하지 않고, 서브 에이전트를 강제하지 않으며, 권한 팝업도, 플랜 모드도, 빌트인 투두 리스트도, 백그라운드 bash도 기본 제공하지 않습니다. 그 대신 모든 기능을 사용자가 자신의 워크플로우에 맞게 확장이나 스킬로 만들어 붙일 수 있도록 합니다. "투두 리스트는 모델을 혼란스럽게 만든다"는 식의 흥미로운 관점도 함께 공유되어 있어, 관심 있는 분들은 관련 블로그 글을 참고하면 좋습니다.

설치는 npm 글로벌 패키지로 한 줄이면 끝납니다.

# Install Pi globally via npm
npm install -g @mariozechner/pi-coding-agent

Pi는 Anthropic, OpenAI, Google Gemini, Azure OpenAI, DeepSeek, Groq, Cerebras, OpenRouter, Hugging Face, Fireworks 등 다양한 클라우드 프로바이더의 API 키와 Anthropic Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot 같은 구독형 인증을 모두 지원하지만, 우리가 관심 있는 것은 로컬 LM Studio를 커스텀 프로바이더로 등록하는 경로입니다.

Pi를 로컬 LM Studio 서버에 연결하기

Pi가 LM Studio의 OpenAI 호환 엔드포인트를 사용하도록 설정하려면, ~/.pi/agent/models.json 파일을 생성(또는 편집)하여 다음과 같이 작성합니다.

{
  "providers": {
    "lmstudio": {
      "baseUrl": "http://localhost:1234/v1",
      "api": "openai-completions",
      "apiKey": "lm-studio",
      "models": [
        {
          "id": "google/gemma-4-26b-a4b",
          "input": ["text", "image"]
        }
      ]
    }
  }
}

여기서 핵심은 id 필드의 값을 LM Studio의 서버 탭에 표시되는 모델 식별자와 정확히 일치시키는 것입니다. 일치하지 않으면 Pi에서 모델 선택이 실패합니다. apiKey 값은 LM Studio가 실제로 검증하지 않으므로 임의의 문자열("lm-studio" 등)을 사용하면 됩니다.

설정이 끝나면 Pi를 실행하고 /model 명령으로 방금 등록한 로컬 모델로 전환합니다.

pi
# Inside Pi, switch to your local LM Studio model
# /model

이제 모든 추론이 LM Studio가 띄운 로컬 서버에서 처리되며, 코드와 파일 컨텍스트는 사용자의 머신을 떠나지 않습니다. 로컬 코딩 에이전트가 본격적으로 동작하기 시작하는 순간입니다.

스킬(Skills)로 능력 확장하기

Pi의 진짜 강력함은 코어가 작다는 점이 아니라, 그 코어 위에 사용자가 필요한 능력을 자유롭게 얹을 수 있다는 점에서 드러납니다. 그 첫 번째 도구가 바로 스킬(Skills) 입니다.

스킬은 Agent Skills 표준을 따르는 온디맨드 능력 패키지로, 본질적으로는 지시문을 담은 마크다운 파일입니다. 모델은 사용자가 /skill:name으로 명시적으로 호출하거나, 적절한 상황에서 자동으로 해당 스킬을 발견하여 사용합니다.

원문 저자가 추천하는 유용한 스킬들은 다음과 같습니다:

liteparse: PDF, DOCX, PPTX 등의 문서를 빠르게 로컬에서 파싱합니다. 특히 Gemma 4는 이미지 이해는 가능하지만 문서 파일 자체를 직접 처리하지는 못하므로, liteparse가 문서를 모델이 다룰 수 있는 형식으로 변환해 주는 다리 역할을 합니다.
frontend-slides: HTML 기반 프레젠테이션 슬라이드를 생성합니다.
pi-skills: Pi 코딩 에이전트를 위한 스킬 모음으로, 커뮤니티에서 가장 자주 참고되는 컬렉션입니다.
grill-me: 모델이 사용자의 아이디어를 비판적으로 검토하고 다듬도록 유도합니다.
gemini-skills: Gemini API와 SDK 사용을 위한 스킬 모음입니다.

스킬은 git 저장소를 복제(clone)하는 방식으로 손쉽게 설치할 수 있습니다:

# User-level: available in all projects
git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills

# Project-level: scoped to the current project
git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills

확장(Extensions)으로 워크플로우 깊이 커스터마이즈

스킬이 모델의 능력을 확장하는 방법이라면, 확장(Extensions) 은 Pi 자체의 동작을 깊이 커스터마이즈하는 수단입니다. 확장은 TypeScript 모듈로 작성되며, 커스텀 도구, 커맨드, UI 컴포넌트, 권한 게이트, 서브 에이전트, 심지어 게임까지 만들 수 있을 정도로 자유도가 높습니다.

여기서 한 가지 반드시 짚고 넘어가야 할 점이 있습니다. Pi는 기본적으로 YOLO 모드로 동작합니다. 즉, bash 명령을 별도의 확인 없이 곧바로 실행합니다. 클라우드의 정렬된(aligned) 모델이라면 위험성이 상대적으로 낮을 수 있지만, 로컬 모델은 환각(hallucination) 가능성이 더 크고, 의도치 않은 파괴적 명령을 생성할 위험도 무시할 수 없습니다.

이 위험을 줄이기 위한 첫 번째 방어선이 permission-gate 확장입니다. 잠재적으로 위험한 명령이 실행되기 전에 사용자에게 확인을 요청하므로, YOLO 모드가 가져다주는 속도를 일부 양보하면서도 사고를 예방할 수 있습니다. 다만 이는 완전한 보안 샌드박스는 아니라는 점을 명확히 인식해야 합니다.

더 견고한 격리가 필요하다면 다음과 같은 옵션을 고려할 수 있습니다.

cco: 명령을 컨테이너 안에서 실행하여 호스트 시스템과 격리합니다.
sandbox extension: Pi 공식 예제로 제공되는 샌드박스 실행 확장입니다.

확장 로딩은 두 가지 방식으로 가능합니다. 일회성으로 사용할 때는 --extension 플래그를, 항상 적용하고 싶다면 확장 디렉토리에 복사하는 방식을 사용합니다.

# Load an extension once via the --extension flag
pi --extension examples/extensions/permission-gate.ts

# Or copy it into the auto-discovery directory
cp permission-gate.ts ~/.pi/agent/extensions/

세션 관리: 트리 구조와 컴팩션

Pi의 세션은 단순한 선형 로그가 아니라, JSONL 파일에 저장되는 트리 구조 입니다. 각 엔트리는 id와 parentId를 가지며, 새 파일을 만들지 않고도 동일 파일 안에서 분기할 수 있습니다. 이 구조 덕분에 다음과 같은 흐름이 자연스럽게 가능해집니다.

/tree로 세션 트리를 탐색하여 임의의 이전 시점으로 돌아가 그 지점부터 다시 작업을 이어갑니다. 한 파일에 모든 분기가 보존됩니다.
/fork로 과거 사용자 메시지에서 새 세션 파일을 만듭니다. 활성 경로의 히스토리를 그대로 복사하면서, 마지막 프롬프트는 편집기에 띄워 수정할 수 있게 해줍니다.
/clone은 현재 활성 분기를 통째로 새 세션 파일로 복제합니다.
명령행에서 pi --fork <path|id>를 사용하면 임의의 세션 파일이나 부분 UUID로부터 직접 분기할 수 있습니다.

긴 세션은 결국 컨텍스트 윈도우를 소진하기 마련인데, 이를 위해 Pi는 컴팩션(Compaction) 기능을 기본 활성화 상태로 제공합니다. 컴팩션은 오래된 메시지를 요약하면서 최근 메시지는 보존하는 방식으로 작동하며, 컨텍스트가 한계에 가까워지면 사전적으로 트리거되거나, 오버플로 발생 시 복구 후 재시도합니다. 사용자가 직접 /compact 또는 /compact <custom instructions> 형태로 호출할 수도 있습니다.

컴팩션은 본질적으로 손실 압축이지만, JSONL 원본은 그대로 남아 있으므로 언제든 /tree를 통해 손실 없는 원본 히스토리로 돌아갈 수 있습니다. 자세한 동작 원리는 공식 컴팩션 문서에 정리되어 있습니다.

로컬 코딩 에이전트의 의미와 향후 전망

Patrick Loeber의 가이드는 단순한 셋업 매뉴얼을 넘어, "프론티어 모델 + 클라우드 SaaS"가 아닌 또 다른 방향의 코딩 에이전트 경로를 제시합니다. 모델은 로컬에서, 도구 셋은 작고 명확하게, 워크플로우는 사용자가 직접 조립하는 방식입니다.

이러한 접근은 다음과 같은 시나리오에서 특히 의미가 있습니다.

데이터 외부 유출이 허용되지 않는 환경: 사내 코드, 의료 데이터, 비공개 연구 코드 등 외부 API로 컨텍스트를 보내기 어려운 경우, 로컬 코딩 에이전트는 사실상 유일한 실용적 선택지입니다.
반복적이고 반복 비용이 큰 워크로드: 토큰 단위 과금이 누적되는 자동화 워크플로우에서는, 로컬 모델의 한 번 셋업 비용이 시간이 지날수록 빠르게 회수됩니다.
워크플로우 실험과 자체 도구 구축: Pi처럼 작고 확장 가능한 코어는, 자신만의 agent skill이나 TypeScript 확장을 만들고 싶은 개발자에게 좋은 출발점이 됩니다.

물론 한계도 분명합니다. Gemma 4 26B A4B 같은 모델이 점차 좋아지고 있다고 해도, 동일한 작업에서 Claude Sonnet/Opus 4.x, GPT-5 시리즈, Gemini 3 같은 프론티어 모델과 비교하면 일관성과 추론 깊이에서 차이가 존재합니다. 또한 로컬 추론은 GPU나 메모리, 전력 측면에서 일정 수준 이상의 하드웨어를 요구합니다. 그럼에도 불구하고 Apache 2.0 라이선스로 공개된 강력한 오픈 가중치 모델과, 이를 잘 받쳐주는 작고 확장 가능한 에이전트 하네스의 조합은, 앞으로 점점 더 많은 개발자에게 매력적인 선택지가 될 것으로 보입니다.

한 걸음 더 나아가기

이 가이드는 시작점일 뿐입니다. 다음 단계로 시도해 볼 만한 것들을 정리하면 다음과 같습니다.

자신만의 AGENTS.md / CLAUDE.md를 작성하여 프로젝트 컨벤션과 자주 쓰는 명령을 Pi가 시작 시점에 학습하도록 만듭니다. 컨텍스트 파일은 ~/.pi/agent/AGENTS.md(전역) 또는 프로젝트별 디렉토리에 둘 수 있습니다.
~/.pi/agent/prompts/ 아래에 자주 쓰는 프롬프트를 마크다운으로 저장하여 /이름 형태의 프롬프트 템플릿으로 재사용합니다.
Pi 패키지(npm pi-package 키워드)나 Pi Discord에서 다른 사용자들이 만든 확장과 스킬을 둘러보고 자신의 워크플로우에 맞게 통합합니다.
VRAM이 충분하다면 Q6_K 또는 Q8_0 양자화로 품질을 한 단계 끌어올리거나, Apple Silicon에서는 MLX 빌드를 시도해 봅니다.
안전성이 걱정된다면 permission-gate나 sandbox 확장, 또는 cco를 결합하여 명령 실행을 격리합니다.

Pi 프로젝트 홈페이지

How to run a local coding agent with Gemma 4 and Pi 원문 블로그

Pi Coding Agent GitHub 저장소

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~