🚀 터미널에서 자신만의 AI 코딩 에이전트를 실행하는 방법 — 로컬, 프라이빗, 무료 (Pi + llama.cpp 활용)

단계별 가이드:

사용 도구:
Pi — earendil-works에서 제작한 최소한의 터미널 코딩 에이전트입니다. Electron도 없고, 불필요한 요소(bloat)도 없으며, 클라우드도 사용하지 않습니다. 터미널에서 실행되며 빠르고 확장 가능합니다. 30개 이상의 클라우드 제공업체(Anthropic, OpenAI, Google, DeepSeek, Groq, OpenRouter…)와 연동되지만, OpenAI 호환 API를 통해 로컬 모델(local model)에도 매우 쉽게 연결할 수 있습니다. 이것이 바로 우리가 원하는 것입니다.

웹사이트: https://t.co/kmUK5ZL2YL
리포지토리(Repo): https://t.co/norHti0HZd
npm 패키지: https://t.co/iZNmJNbqwj

─ PI 설치하기 ─

한 줄 명령어로 설치:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

또는 npm 없이 설치:
curl -fsSL https://t.co/XKfALcoCH7 | sh

pi 명령어로 실행합니다. 기본적으로 /login(Claude, OpenAI, Copilot…)을 요청하지만, 우리는 그것에 관심이 없습니다 — 우리는 로컬 모델을 원합니다.

─ 설정(Config) 위치 ─

• ~/.pi/agent/settings.json → 글로벌 설정 (기본 제공업체, 사고 수준(thinking level), 압축(compaction), 패키지 등…)
• ~/.pi/agent/models.json → 모델 및 제공업체 정의

models.json은 /model을 열 때마다 다시 로드되므로, 재시작 없이 실시간으로 편집할 수 있습니다.

─ LLAMA.CPP 서버 시작하기 ─

lama-server -m Qwen3.6-27B-Q5_K_M.gguf --host 0.0.0.0 --port 8080 -ngl 99 -c 32768 --jinja

주요 플래그(flags):

• --jinja → 모델에 내장된 채팅 템플릿(chat template)을 사용합니다.
• --port 8080 → localhost:8080/v1에서 OpenAI 호환 엔드포인트(endpoint)를 제공합니다.
• -ngl 99 → 모든 레이어(layers)를 GPU에 올립니다.
• -c 32768 → 컨텍스트 윈도우(context window)

실행 확인:
curl http://localhost:8080/v1/models
모델 목록이 포함된 JSON을 반환하면 → 준비가 완료된 것입니다.

─ ~/.pi/agent/models.json 생성하기 ─

providers:
llamacpp:
baseUrl: "http://localhost:8080/v1"
api: "openai-completions"
apiKey: "llama"
compat:
supportsDeveloperRole: false
supportsReasoningEffort: false
maxTokensField: "max_tokens"
models:
[
{
"id": "Qwen3.6-27B-Q5_K_M.gguf",
"name": "Qwen 3.6 27B (Local)",
"reasoning": true,
"input": ["text"],
"contextWindow": 32768,
"maxTokens": 8192,
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"compat": { "thinkingFormat": "qwen-chat-template" }
}
]
}
}

apiKey: "llama"는 단순히 자리 표시자(placeholder)입니다. llama.cpp는 이를 무시하지만, Pi가 모델을 /model에서 보여주기 위해서는 필요합니다. cost가 모두 0이라는 것은 로컬 모델이며, 비용이 청구되지 않는다는 의미입니다. HuggingFace의 어떤 GGUF 모델이라도 작동할 수 있습니다. Qwen, Gemma, Llama, DeepSeek 등... 적절한 thinkingFormat과 contextWindow만 설정하면 됩니다.

─ 모델 실행 및 선택하기 ─

pi
/model

Qwen 3.6 27B (Local)을 선택합니다. 또는 CLI에서 직접 다음 명령어를 사용하세요:
pi --model llamacpp/Qwen3.6-27B-Q5_K_M.gguf

완료되었습니다. 프롬프트를 시도해 보세요. 예를 들어, "이 폴더의 모든 .js 파일을 .ts로 이름 변경해 줘" 또는 "이 파일에 대한 테스트 코드를 작성해 줘"와 같은 요청입니다. 에이전트는 파일을 읽고 편집하며, bash를 실행하고, 세션을 JSONL 트리 형태로 저장합니다.

─ 이렇게 하는 이유 ─

• 사용자의 어떤 코드도 기기를 벗어나지 않습니다 (로컬 환경).
• 오프라인에서도 작동합니다 (비행기 안, 동굴 등 어디서든).
• 월 $0이며, 토큰을 얼마나 많이 소모하든 비용이 없습니다.
• 모델을 언제든지 교체할 수 있습니다. GGUF 파일을 변경하고 models.json을 다시 로드하기만 하면 됩니다.
• Pi는 사용자가 그에 적응하도록 강요하지 않습니다. 사용자가 Pi를 자신에게 맞게 조정합니다.

─ PI가 할 수 있는 모든 것 (로컬 모델 외) ─

세션 시스템 — 모든 세션은 JSONL 트리가 됩니다. 원하는 지점으로 돌아갈 수 있고, 브랜치(/fork, /clone)를 만들거나, /tree 명령어로 트리를 탐색할 수 있습니다. 아무것도 손실되지 않으며, 모든 것이 파일에 보존됩니다.

압축(Compaction) — 긴 세션은 컨텍스트 창을 소진시킵니다. Pi는 이를 자동으로 처리합니다: 오래된 메시지를 요약하고, 최근 메시지는 유지하며, 오버플로우 시 자동 재시도합니다. 수동으로는 /compact 명령어를 사용합니다.

메시지 큐 (Message queue) — 에이전트가 작업하는 동안에도 계속 타이핑을 할 수 있습니다. Enter는 조종 메시지 (steering message, 현재 턴이 끝난 후 전달됨)를 입력하며, Alt+Enter는 후속 메시지 (follow-up, 모든 작업이 완료된 후에만 전달됨)를 입력합니다. Escape 키를 누르면 작업을 중단하고 메시지를 에디터로 복구합니다.

기술 (Skills) — Markdown 형식의 온디맨드 명령어 팩 (Agent Skills 표준). /skill:이름을 통해 호출하거나, 에이전트가 문맥에 따라 자동으로 로드하도록 할 수 있습니다. pi 패키지를 통해 공유 가능합니다.

프롬프트 템플릿 (Prompt templates) — 변수가 포함된 .md 파일 형태의 재사용 가능한 프롬프트입니다. /템플릿이름을 통해 확장합니다.

확장 기능 (Extensions) — 기본적으로 무엇이든 할 수 있는 TypeScript 모듈입니다: 커스텀 도구 (custom tools), 커스텀 명령어 (custom commands), 이벤트 핸들러 (event handlers), UI 컴포넌트 (UI components), 상태 표시줄 (status lines), 커스텀 압축 (custom compaction), git 체크포인팅 (git checkpointing), SSH 샌드박스 (SSH sandbox), 그리고 기다리는 동안 터미널에서 즐길 수 있는 게임까지 가능합니다 (네, Doom이 실행됩니다).

테마 (Themes) — 다크/라이트 모드 및 커스텀 테마를 지원하며, 재시작 없이 핫 리로드 (hot-reload)가 가능합니다.

─ MCP는 어떤가요? ─

Pi는 흥미로운 철학을 가지고 있습니다: 코어에는 MCP (Model Context Protocol)가 없습니다. 저자는 README 파일이 포함된 CLI 도구를 작성하거나 (Skills 참조), 자신이 원하는 방식 그대로 MCP 지원을 추가하는 확장 기능을 만드는 것이 더 낫다고 주장합니다. 왜일까요? MCP는 종종 불필요한 복잡성 계층을 추가하기 때문입니다.

하지만 — MCP 서버를 연결해야 한다면, 이를 위한 확장 기능이 있습니다. 다음 명령어로 설치하세요:
pi install npm:pi-mcp-adapter

settings.json 파일에 `

SDK — Pi는 프로그래밍 방식의 API (programmatic API)를 제공합니다. 여러분의 앱에 직접 내장할 수 있습니다. 실제 사례로, GitHub의 openclaw 프로젝트는 완전한 통합을 위해 Pi SDK를 사용하고 있습니다.

RPC 모드 — Node.js가 아닌 환경에서의 통합을 위해 pi --mode rpc를 사용하면 stdin/stdout JSONL을 통해 통신할 수 있습니다.

세션 공유 (Share sessions) — /share 명령어를 사용하면 세션을 비공개 GitHub gist로 업로드하고 공유 가능한 HTML 링크를 생성합니다. /export는 HTML 또는 JSONL 형식으로 내보냅니다.

OSS 세션 공유 — 오픈 소스 작업을 위해 Pi를 사용하는 경우, 모델과 평가(evaluations)를 개선하는 데 도움이 되도록 세션 데이터를 공유할 수 있습니다. 관련 도구: GitHub의 pi-share-hf.

오프라인 모드 (Offline mode) — PI_OFFLINE=1 또는 --offline을 사용하면 모든 시작 시 네트워크 활동(업데이트 확인, 텔레메트리, 패키지 확인)을 비활성화합니다. 외부로 데이터를 전송하지 않습니다.

컨텍스트 파일 (Context files) — AGENTS.md (또는 CLAUDE.md) 파일이 현재 작업 디렉토리(cwd) 및 상위 디렉토리에서 자동으로 로드됩니다. 프로젝트 컨벤션, 명령어, 스타일 등을 한곳에서 관리할 수 있습니다. --no-context-files를 통해 비활성화할 수 있습니다.

시스템 프롬프트 오버라이드 (System prompt override) — .pi/SYSTEM.md (프로젝트 단위) 또는 ~/.pi/agent/SYSTEM.md (글로벌 단위)를 통해 기본 프롬프트를 교체할 수 있습니다. APPEND_SYSTEM.md를 사용하면 기존 내용을 교체하지 않고 내용을 추가할 수 있습니다.

─ 보너스 팁 (BONUS TIP) ─

pi install npm:pi-observability — 실시간 TPS(초당 토큰 수) 대시보드를 추가하고, 기본 푸터를 관측성(observability) 바(bar)로 교체하며, 실행 후 초당 토큰 수 요약을 출력합니다. 로컬 모델의 성능을 튜닝할 때 매우 유용합니다.

전체 문서는 리포지토리의 docs/ 디렉토리에 있습니다. 커스텀 모델 설정을 위한 models.md, 자체 프로바이더 구축을 위한 custom-provider.md가 있으며, https://t.co/kmUK5ZL2YL 에서 연결되는 Discord 커뮤니티가 있습니다.

Pi는 도구를 자신에게 맞추도록 강제합니다. 반대로 사용자가 도구에 맞추는 것이 아닙니다. "Pi를 여러분의 워크플로우에 맞추세요, 그 반대가 아니라." 이것이 당신을 가두는 도구와 당신의 것이 되는 도구의 차이입니다.

#LocalLLM #llamacpp #AIAgent #OpenSource #CodingAgent #piAgent #SelfHosting #DevTools