<h1 align="center">agentty</h1>
<p align="center">
<b>터미널에서 작동하는 빠르고 오픈 소스인 코딩 에이전트입니다.</b><br>
C++26으로 구현된 드롭인(drop-in) Claude Code 대안 — 단일 정적 바이너리, 밀리초 단위 시작, 모든 모델 지원.
</p>
<p align="center">
<a href="https://github.com/agentty-org/agentty/releases/latest"><img src="https://img.shields.io/github/v/release/agentty-org/agentty?style=flat-square&color=blue" alt="Release" /></a>
<a href="https://github.com/agentty-org/agentty/stargazers"><img src="https://img.shields.io/github/stars/agentty-org/agentty?style=flat-square&color=f1c40f&labelColor=555555" alt="Stars" /></a>
<a href="https://github.com/agentty-org/agentty/releases"><img src="https://img.shields.io/github/downloads/agentty-org/agentty/total?style=flat-square&color=brightgreen" alt="Downloads" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License" /></a>
<a href="https://discord.gg/qhb9AZ8f3c"><img src="https://img.shields.io/badge/Discord-join%20chat-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" /></a>
<a href="https://web.libera.chat/#agentty"><img src="https://img.shields.io/badge/IRC-%23agentty-555555?style=flat-square&logo=libera.chat&logoColor=white" alt="IRC" /></a>
</p>
<p align="center">
<img src="https://raw.githubusercontent.com/agentty-org/agentty/master/agentty.gif" alt="agentty demo" width="800" />
</p>
왜 agentty인가?
대부분의 터미널 코딩 에이전트는 Node 또는 Python 앱으로 배포되며, 매 턴마다 저장소(repository)의 큰 부분을 모델에 전송합니다. agentty는 이와 반대되는 접근 방식을 취합니다:
- 단일 네이티브 바이너리입니다. 크기는 약 30MB이며, 밀리초 단위로 열리고 런타임 종속성이 전혀 없습니다. Node, Python,
npm install, node_modules가 필요하지 않습니다. 다운로드하여 실행하기만 하면 됩니다.
- 관련 코드만 전송합니다. 내장 로컬 검색 기능(하이브리드 키워드 + 임베딩 검색, 코드 인식 청킹 및 랭킹)이 필요한 조각들만을 가져옵니다. 이는 전체 리포지토리를 덤프하는 방식에 비해 컨텍스트를 80% 이상 절감합니다.
- 특정 공급업체에 종속되지 않습니다. Claude Pro/Max로 로그인하거나, OpenAI, Groq, OpenRouter, Cerebras, DeepSeek, xAI (Grok), Mistral, Gemini, Fireworks 또는 완전히 로컬의 Ollama 모델을 지정할 수 있습니다.
^P를 사용하여 실시간으로 전환합니다.
- 기본적으로 안전합니다. 쉘 및 빌드 명령어는 샌드박스(sandbox) 내에서 실행되며, 단 하나의 명령어로 전체 세션을 SSH 상에서 에어갭(air-gap) 할 수 있습니다.
- 오픈 소스이며 (MIT) Zed 내부의 ACP 위에서 실행됩니다.
다른 도구에서 오셨나요? 솔직한 비교를 확인해 보세요: vs Claude Code · vs Aider · vs Cursor · 모든 대안.
시작하기 (Getting Started)
curl -fsSL https://raw.githubusercontent.com/agentty-org/agentty/master/install.sh | sh
cd your-project
agentty
최초 실행 시 인증(auth) 화면이 열립니다. API 키를 붙여넣거나 (Anthropic sk-ant-…, 또는 다른 공급업체의 키), 아예 키가 필요 없는 로컬 Ollama 모델을 사용하세요. 선호한다면 Claude Pro/Max OAuth로 로그인할 수도 있습니다. 접속한 후, 첫 실행 환영 카드에서 몇 가지 시도해 볼 것을 제안합니다. 그냥 입력하고 Enter를 누르기만 하면 됩니다.
기능 (Features)
<table>
<tr>
<td width="50%">
⚡ 전 과정에 걸친 즉각적인 속도 (Instant, all the way through)
콜드 스타트(Cold start)는 1ms 미만이며, 키 입력부터 픽셀까지 약 1ms입니다. Node, Python, npm install가 필요 없는 순수 정적 바이너리입니다. 독립적인 도구 호출은 병렬로 실행되며, 모델이 타이핑하는 동안 읽기 전용(read-only) 도구가 시작되므로, 도구를 많이 사용하는 작업도 더 빨리 완료됩니다.
🔌 모든 모델 지원 (Any model)
Claude, GPT, Groq, OpenRouter, Ollama 또는 모든 OpenAI 호환 엔드포인트가 가능합니다. ^P를 사용하여 실시간으로 전환할 수 있습니다.
</td>
</tr>
</table>
🛡️ 기본적으로 샌드박스 환경 제공
모든 셸 호출은 OS가 강제하는 샌드박스 내에서 실행됩니다. Linux에서는 claybin(seccomp + landlock + cgroup2; 하나의 엔진으로 bwrap이 제거됨), macOS에서는 seatbelt + rlimits를 사용하며 sandbox-exec가 대체 수단입니다. Windows에서는 AppContainer + 제한된 토큰(restricted token) + job objects를 사용합니다. 더 약한 대체 엔진은 없으며, 호스트가 방화벽을 구축할 수 없을 경우 시작 시 알림이 표시되고 명령은 제약 없이 실행됩니다.
자격 증명 파일(Credential files)은 설정 여부와 관계없이 마스킹되며, 파일 도구는 작업 공간 외부의 경로를 거부합니다. 네트워크는 필터링 프록시를 통해 전송되어 LAN, localhost, 클라우드 메타데이터 접근을 거부합니다. 허용 호스트(Allowed hosts) 기능은 지정한 사이트로 범위를 좁히고, airgapped 프리셋은 이를 비활성화합니다.
심층 분석: docs/SANDBOX.md.
🌐 에어갭 모드 (Air-gapped mode)
인터넷 연결이 없는 장치에서 실행됩니다. 사용자의 노트북은 TLS가 종단 간(end-to-end)으로 고정된 SSH를 통해 바이트를 중계합니다.
🤖 스크립트 및 CI
agentty run "fix the failing test"는 도구를 사용하여 하나의 프롬프트를 실행하고 답변만 출력합니다. --json, 명확한 종료 코드(clear exit codes), --timeout, --events jsonl (도구 호출 및 추론 기록), 그리고 신뢰할 수 없는 코드를 위한 --read-only --no-network 옵션을 지원합니다. 문서 ↗
read · write · edit · bash · grep · glob · git · web · search_docs · search_code · task — 각 도구는 목적에 맞게 제작된 위젯을 가지고 있습니다.
🧠 코드베이스 학습
Agent Skills와 기억/망각 메모리(remember/forget memory), 그리고 코드에 민감한 재순위 지정기(code-aware reranker)를 갖춘 하이브리드 키워드 + 임베딩 검색을 지원하는 완전히 로컬 RAG 엔진이 사용자의 코드, 문서, 스킬, 메모리를 학습합니다. 한 번 가르치면 모든 세션에서 사용자만의 규칙을 알게 됩니다. 작동 방식 ↓
🎯 스마트 모드 (Smart Mode)
플래그십 모델 하나가 계획을 세우고; 더 저렴한 모델들이 실제 작업을 수행합니다. 노력(Effort)은 각 턴의 복잡도에 따라 조정되며, 저렴한 시도가 부족할 때만 캐스케이드 재시도(cascade retries)를 통해 더욱 열심히 작동하고, 라우터는 세션 전반에 걸쳐 사용자의 리포지토리를 학습합니다. Off 상태는 엄격하게 아무 작업도 하지 않습니다(no-op). 작동 방식 ↓
제공업체 (Providers)
agentty # 사용자가 직접 키/모델 제공
agentty --provider openai -m gpt-4o # GPT
agentty --provider groq -m llama-3.3-70b # Groq
...
--provider는 유지됩니다. 앱 내에서 ^P를 사용하여 실시간으로 전환할 수 있습니다.
검색 증강 생성 (Retrieval-Augmented Generation, RAG)
컨텍스트 덤핑 없는 검색 (Retrieval without context dumping)
repository 전체나 모든 프로젝트 문서를 각 프롬프트에 주입하는 대신, agentty는 작업이 프로젝트 지식을 필요로 할 때만 작고 출처 태그가 지정된 관련 구절을 검색합니다. 이는 컨텍스트를 집중시키고, 작업 자체를 위한 공간을 더 많이 남겨주며, 불필요한 자료를 반복적으로 전송하는 비용을 절감해 줍니다.
agentty는 두 가지 도구 뒤에 완전히 로컬인 검색 엔진을 탑재하고 있습니다. 클라우드 연결이나 설정이 필요 없으며 오프라인에서도 작동합니다: 키워드 검색은 첫 실행부터 작동하며, 로컬 Ollama를 사용하면 의미 기반 검색도 가능해집니다.
search_code: 이름은 모르지만 기능으로 코드를 찾습니다('재시도 백오프(retry backoff) 처리는 어디에 있나요?' 등). grep의 보완재입니다.search_docs: 문서 폴더(./docs, 또는 AGENTTY_DOCS_DIR), 설치된 스킬, 그리고 사용자가 기억하도록 요청한 사실을 검색합니다.
반환되는 모든 구절은 파일 + 라인 범위와 함께 출처 태그(docs: · skill: · memory: · MCP URI)가 지정되어 있어 모델이 이를 인용하거나, 열거나, 추적할 수 있습니다.
의미 기반 검색 활성화 (단일 명령어):
ollama pull qwen3-embedding:0.6b
agentty는 로컬의 Ollama를 자체적으로 찾아내며, 해당 환경에 있으면 qwen3-embedding:0.6b를 우선 사용합니다. agentty diagnostics를 통해 연결 여부(probe: ok)를 확인할 수 있습니다. 인덱스는 리포지토리당 한 번 구축되며, 변경된 파일에 대해서만 업데이트됩니다.
agentty가 자체적으로 판단한 질문에 대해, search_code는 qwen3-embedding 사용 시 6378%의 확률로 올바른 파일을 가장 먼저 제시하며, 상위 8개 내에서는 9397%입니다 (키워드만 사용할 경우: 첫 번째가 5760%, 상위 8개가 9295%). agentty rag-eval을 사용하여 사용자의 리포지토리에서 측정해 보세요.
<details>
<summary><b>검색 흐름 (The retrieval funnel)</b></summary>
각 검색은 다음 순서로 실행됩니다:
- 구조 인식 청킹(Structure-aware chunking) — 코드는 함수와 클래스 단위로, 문서는 제목(heading) 단위로 분할됩니다. 각 청크는 해당 제목과 헤딩 경로를 가지고 인덱싱됩니다.
- 하이브리드 검색(Hybrid retrieval) — BM25 (키워드; 식별자는 단어로 분할되므로
onClipboardRead가 "clipboard read"와 일치함) 및 밀집 임베딩(HNSW)을 사용하며, 쿼리당 결합됩니다.
- 재순위화(Rerank) — 결정론적 특징 재순위화기입니다. 코드의 경우, 요청하지 않는 한 소스 코드가 테스트나 문서보다 높은 순위를 차지하며, 헤더는
.cpp 파일을 올립니다.
- 다양성 확보 및 중복 제거(Diversify + de-duplicate) — MMR(Maximal Marginal Relevance), 근접 중복 제거, 그리고 인접한 청크들을 하나의 스팬으로 연결합니다.
- 압축 및 예산 할당(Compress + budget) — 패시지(passage)는 쿼리와 일치하는 문장들로 잘라져 하드 바이트 예산 내에 패킹됩니다.
- 신뢰도(Confidence) — 모든 결과에는 신뢰도가 부여되며, 약한 결과는 이를 명시합니다.
옵트인 단계(Opt-in stages) (기본적으로 비활성화됨; 켜기 전에 측정 권장): 유사 관련성 피드백(pseudo-relevance feedback) (AGENTTY_RAG_PRF=1), GraphRAG (AGENTTY_RAG_GRAPH=1), 수정적 재시도(corrective retry) (AGENTTY_RAG_CORRECT=1) 그리고 모델 호출 비용이 드는 두 가지 기능: 다중 쿼리 확장(multi-query expansion) (AGENTTY_RAG_EXPAND=1) 및 HyDE (AGENTTY_RAG_HYDE=1).
사전 검색(Proactive retrieval) (설정(/settings)에서 켜기 전까지 비활성화됨 → Proactive retrieval (RAG))은 모델이 질문하기 전에 깔때기를 실행하며, 턴에 출처 태그가 지정된 <retrieved-context> 블록을 추가합니다. 이는 신뢰도 막대와 사용된 출처를 가진 하나의 📚 카드로 표시됩니다.
모든 기능은 자체 개발한 C++(rag-cpp)로 구현되었으며, 각 단계는 우아하게 저하(degrades gracefully)되며, AGENTTY_RAG_*를 통해 조정 가능합니다. 전체 설명서: docs/website/retrieval.md.
스마트 모드 (Smart Mode)
하나의 모델이 모든 상황에 적합한 경우는 드뭅니다. 한 줄 이름 변경이나 파일 간 리팩토링은 같은 노력을 요구하지 않으며, 사소한 지식(trivia)에 최고급 추론 능력을 사용하는 것은 느리고 비용이 많이 듭니다. 스마트 모드 (^S)는 오케스트레이터-워커 설계를 통해 이를 해결합니다: 강력한 모델이 계획을 소유하고 잘 정의된 하위 작업을 더 저렴한 워커들에게 위임합니다.
이 시스템은 **세 가지 역할(three roles)**과 **여덟 개의 독립적인 레이어(eight independent layers)**로 구성되어 있으며, 각 레이어는 토글 방식으로 작동합니다:
- Strategic (주력): 계획을 세우고 위임하며 · Implementation (중급): 코드를 작성하고 · Utility (저비용): 요약 및 단순 작업을 처리합니다. 리졸버(resolver)는 역할을
(모델, 노력)에 매핑하며, 모델 이름을 문자열로 확인하지 않기 때문에 어떤 슬롯에도 어떤 모델을 고정해도 항상 안전합니다.
- 각 턴마다 복잡도 기반의 노력(Complexity-scaled effort) 크기를 조정하며 (사소함 → 복잡함), 저비용 시도가 실제로 부족할 때만 더 높은 노력으로 재시도하는 캐스케이드(cascade) 기능을 사용합니다. 이는 RouteLLM/캐스케이드 아이디어를 에이전트 루프 내부에 적용한 것입니다.
- 이 루프는 무상태 라우터(stateless router)가 볼 수 없는 결과(예: 빌드 실패, 테스트 빨간색 표시 등)를 확인하기 때문에, 스마트 모드(Smart Mode)는 워크스페이스별로 학습합니다. 캐스케이드가 발견한 이전의 노력을 유지하고 작동했던 분해 과정을 기억합니다. 레포지토리 내 두 번째 세션은 첫 번째 세션보다 더 똑똑합니다. 모든 학습은 로컬 디스크(
.agentty/)에 저장되며, 삭제할 수 있습니다.
^S를 사용하여 오버레이(overlay)를 열면, 푸터(footer)에서 이 레포지토리에서 학습한 내용을 확인할 수 있습니다.
Off는 엄격하게 바이트 대 바이트의 No-op입니다. 추가 토큰도 없고 지연 시간(latency)도 없습니다.
전체 설명: docs/website/smart-mode.md.
키(Keys)
| 키 | 동작 | 키 | 동작 |
|---|
Enter | 전송 / 대기열 추가 | ^K | 명령어 팔레트 |
| ... | | | |
작성기는 완전한 readline 스타일의 편집기입니다:
| 키 | 동작 | 키 | 동작 |
|---|
^←/→ | 단어 단위 이동 | ^W / Alt+D | 뒤로 / 앞으로 단어 삭제 |
| ... | | | |
전체 키맵: docs/website/keybindings.md.
SSH를 통해 이미지를 붙여넣으려면 터미널 설정이 하나 필요합니다. 클립보드 및 이미지(Clipboard & Images)를 참조하세요.
더 알아보기(More)
<details>
<summary><b>설치 옵션</b></summary>
Linux
curl -fsSLO https://github.com/agentty-org/agentty/releases/latest/download/agentty_${V}_amd64.deb
sudo dpkg -i agentty_${V}_amd64.deb
...
패키지 파일명에 버전이 포함되어 있으므로, latest/download/ 경로는 명시해야 합니다. 정확한 이름은 릴리스 페이지를 참조하거나, 자동으로 해결해 주는 설치 스크립트를 사용하세요.
macOS
brew tap 1ay1/tap && brew install agentty
Windows
scoop bucket add 1ay1 https://github.com/1ay1/scoop-bucket; scoop install agentty
# or
winget install agentty.agentty
Termux / Android (루트 권한 없음, proot 사용 안 함)
agentty는 Termux의 Bionic/libc++ 툴체인에 대해 네이티브로 빌드됩니다. 설치 스크립트는 Termux를 감지하고 $PREFIX/bin (PATH 경로)에 설치합니다:
pkg install git cmake clang openssl libnghttp2
curl -fsSL https://raw.githubusercontent.com/agentty-org/agentty/master/install.sh | sh -s -- --build
