개요
TokenEconomizer는 코딩 에이전트를 자주 쓰는 저장소에서 에이전트 자체를 바꾸지 않고 비용을 줄이는 플러그인이다. 저장소 부제는 “Experience-Driven Black-Box Cost Control for Coding Agents”이고, UC Berkeley와 Microsoft Research·Microsoft Security 소속 11명의 논문(arXiv 2610.22732)에 딸린 구현이다. Claude Code, codex, GitHub Copilot CLI, Pi를 지원하고 opencode는 실험적 지원이다.
2026-10-31 수집 시점 지표는 스타 2,472개, 포크 145개, Python, Apache-2.0, 생성 2026-10-13이다. 만든 지 3주도 안 됐는데 스타가 빠르게 쌓이고 있다.
핵심 아이디어는 “에이전트는 일을 끝내도록 만들어졌지, 싸게 하도록 만들어지지 않았다”는 관찰이다. 매 턴마다 지시문, 로드된 모든 도구 정의, 지금까지의 대화를 다시 지불하는데, 같은 저장소에서 같은 에이전트를 반복해 쓰면 같은 사실을 다시 알아내고, 안 쓰는 도구를 계속 보내고, 비슷한 실패 루프를 다시 돈다. TokenEconomizer는 한 저장소의 지난 세션 기록에서 이 낭비를 배워 다음 세션에서 줄인다. 플러그인이 쓰는 비용은 이후 세션에서 회수된다는 계산이다.
세 가지 메커니즘
| 메커니즘 | 하는 일 | 기본값 |
|---|---|---|
| 마이크로스킬 (micro-skills) | 저장소에서 반복되는 사실(먼저 돌려야 하는 빌드, pytest가 없을 때 python -m pytest, 명령에 필요한 환경 변수, 생성 파일 위치)을 배워 세션 시작 때 알려 준다. 세 세션이 확인해야 주입하고, 이후 세션이 반박하면 버린다 | 꺼짐 |
| 도구 가지치기 (tool pruning) | 10개 프롬프트(2개 이상 세션에 걸쳐) 또는 5개 세션 동안 안 쓴 도구를 에이전트 설정으로 다음 세션부터 빼 둔다. 명령 하나로 되돌린다 | 켜짐 |
| 루프 가드 (failure-loop intervention) | 한 턴이 같은 실패를 반복하면 판정 모델이 막혔는지 본다. 확신이 0.7 이상이면 “다른 접근을 시도하라”는 짧은 메모를 컨텍스트에 넣는다. 턴당 최대 1회 | 켜짐 |
마이크로스킬은 두 출처에서 사실을 배운다. 세션 간에 반복되는 실패, 그리고 3세션마다 최근 세션을 검토해 사실을 제안하는 모델이다. 제안자가 모델 호출을 더하므로 기본은 꺼져 있고, microskills=envfacts로 두면 반복 실패에서만 배워 모델 호출이 없다.
루프 가드는 턴을 스스로 끊지 않는다. 리디렉트 뒤에도 막혀 있으면 “이 턴은 아직 막힌 것 같다, Esc를 눌러 중단하라”는 한 줄만 보여 준다. 중단은 사용자 몫이다. 이 가드는 먼저 그 저장소의 “보통 턴 길이”를 익힌 뒤에 작동한다(잘 끝난 턴 5개 필요). 헤드리스 실행(claude -p, codex exec 등)에서는 지켜보는 사람이 없으므로 표시된 턴도 끝나거나 에이전트 자체 한도에 닿을 때까지 돈다.
설계 원칙 넷: 에이전트가 이미 읽는 경로(세션 시작 컨텍스트, 에이전트 설정)로만 개입하고, 캐시 가격을 반영해 플러그인 자신의 모델 호출까지 비용에 넣고, 반복 증거가 있을 때만 사실을 만들며(작업 성공 보호), 모든 동작을 되돌릴 수 있게 한다.
결과 (저자 측정)
SWE-Bench 277개 작업(저장소 6개)을 5개 에이전트×모델 조합으로 돌렸다. 저장소별로 작업을 순서대로 실행하고 아무것도 배우지 않은 상태에서 시작했으며, 비용에는 플러그인의 모델 호출이 모두 포함된다.
| 조합 (README 표기) | 평균 비용 | Pass@1 |
|---|---|---|
| Claude Code + Sonnet 5 | −23.6% | +1.3 |
| Claude Code + Opus 4.8 | −30.9% | −1.0 |
| Codex + GPT-5.6 Terra | −24.7% | +0.9 |
| Codex + GPT-5.6 Sol | −26.1% | +1.6 |
| Copilot CLI + Sonnet 5 | −18.4% | +2.6 |
- 5개 조합 모두 평균 비용이 줄었고, 저장소×조합 30개 칸 전부에서 기본값보다 쌌다. 같은 저장소·조합 안에서 비용은 5~40% 줄었다.
- Pass@1(첫 시도 성공률)은 5개 중 4개에서 올랐다. Opus 4.8 조합만 1.0포인트 내렸다.
- 다른 벤치마크에서도 줄었다: Web-Bench 16
21%, 작업마다 새 저장소를 쓰는 보안 감사 벤치마크 2종 620%.
공유된 소개글의 “5개 구성 모두 비용 절감, 4개는 성공률도 향상”은 README와 일치한다.
설치와 사용
Claude Code, Codex, Copilot CLI는 저장소를 clone한 뒤 각자의 plugin marketplace add로 등록하고 plugin install한다(clone을 지우면 안 된다). Pi는 pi install git:github.com/microsoft/TokenEconomizer 한 줄이다. Python 3.10+이 필요하고, 플러그인은 API 키를 따로 받지 않고 에이전트의 로그인·요금제를 그대로 쓴다.
- 명령:
status(배운 것·비용),microskills,toolprune,toolprune restore,config set microskills=on. Claude Code·Copilot은/tokeneconomizer:<명령>, Codex는$tokeneconomizer:<명령>, Pi는/te <명령>. 에이전트 안에서 명령을 치면 모델 턴 하나가 들고, 터미널의~/.tokeneconomizer/bin/te로 치면 공짜다. - 끄기:
TE_DISABLE=1 claude로 한 세션만 전체를 끄고,TE_LOOPGUARD=off처럼 메커니즘별로도 끈다. - 데이터: 배운 내용은
~/.tokeneconomizer에만 저장된다. 일부가 실패해도 세션은 플러그인이 없는 것처럼 계속된다. - 도구 가지치기 대상은 에이전트마다 다르다: Claude Code는 개별 도구(
.claude/settings.local.json), Codex는 capability 패키지(.codex/config.toml), Copilot CLI는 MCP 서버 통째(.github/copilot/settings.local.json). Pi는 기본 도구가 넷뿐이라 대상이 없고 opencode는 아직 미지원이다. 사용자가 쓴 deny 규칙은 건드리지 않는다. - 캐시 고려: 가지치기는 그 저장소의 세션이 60분 쉰 뒤(늦어도 목록이 생긴 지 하루 뒤)에만 목록을 쓴다. 도구가 바뀐 채 대화를 이어 가면 전체 이력을 프롬프트 캐시에 다시 써야 하기 때문이다.
한계와 쓰기 전에 알 것
- 수치는 저자 자신의 측정이다. 같은 팀이 논문·구현·실험 harness(
experiments/)를 모두 냈다. 재현 코드는 공개돼 있지만 이 노트는 돌려 보지 않았다. - 효과는 반복 사용을 전제로 한다. 실험은 저장소마다 아무것도 배우지 않은 상태에서 시작해 순서대로 작업을 돌린 결과다. 한 번 쓰고 마는 저장소에서는 배울 기회가 없다. 새 저장소 보안 감사 벤치마크에서 절감이 6~20%로 작아진 것과 맞물린다.
- 켜진 기본값은 둘뿐이다. 도구 가지치기와 루프 가드가 기본이고, 마이크로스킬은 저장소와 작업에 따라 절감이 달라 꺼져 있다. 소개글이 “세 가지를 한다”고 해도 기본 설치에서 켜지는 것은 두 가지다.
- “오래 안 쓴 도구를 자동 제거”는 조건이 구체적이다. 프롬프트 10개 이상이 2세션에 걸치거나 5세션 동안 쓰이지 않아야 하고, 유휴 시간 뒤에 쓰이며, 되돌릴 수 있다.
- 지원 버전 범위가 좁다. Claude Code 2.1.300
2.1.310, Codex 0.153.10.164.0, Copilot CLI 1.0.831.0.102, Pi 1.2.01.3.0. 범위 밖 버전은 “지원 안 함”이거나 미검증이다. - Claude Code에서는 알림이 기본 화면에 안 뜬다. 플러그인 메시지는 상세 트랜스크립트(Ctrl+O)에서만 보여서, 루프 가드의 “아직 막혔다” 한 줄은 Claude에게 답변에서 반복해 달라고 요청하는 방식이고 모델이 다르게 쓰거나 빼먹을 수 있다.
- 루프 가드의 비용. 판정 모델과 리디렉트 작성이 모델 호출이므로, 루프에 빠진 턴이 많은 저장소일수록 호출이 늘지만 이 비용도 보고된 절감에 포함됐다.
공유자 의견
공유된 소개글의 작성자는 “가장 실용적인 기능은 루프 끊기”라고 본다. AI가 버그 하나를 수십 라운드 붙잡고 토큰을 태우는 경우가 있기 때문이다. 이 의견은 소개글 쪽의 판단이고 README는 세 메커니즘 간 기여도를 따로 밝히지 않는다. 마지막 질문(“토큰을 아끼는 쪽이냐, 첫 시도 성공을 위해 더 쓰는 쪽이냐”)에 대한 저자 측 답은 Pass@1이 대체로 함께 올랐다는 것이다. 다만 Opus 4.8 조합은 비용을 가장 많이 줄이면서 Pass@1이 내려, 항상 공짜 점심은 아니다.
같은 소개가 X에도 올라왔다(@TiagerBao, 2026-10-30, 중국어). “277개 SWE-Bench 과제, 5개 모델 구성 모두 평균 비용 감소, 그중 4개는 성공률도 상승”을 강조하고, “토큰을 아낄지, 돈을 더 써서 한 번에 맞힐지”를 독자에게 묻는다.
관련
- 같은 문제를 다른 층에서 푸는 도구: 명령 출력 압축 프록시 2026-04-10-rtk-token-optimization-proxy, 사용량·비용 대시보드 2026-04-15-codeburn-ai-coding-cost-dashboard, 사용자 쪽 도구 정리 팁 2026-05-02-xiaoying-eth-claude-code-token-10tools.
- 내 Claude Code 환경에 넣을지 검토한 결과는 2026-10-31-tokeneconomizer-claude-code-fit-review에 있다.
- Claude Code 활용 전반은 moc-claude-code를 본다.