이 레포가 무엇을 하는 물건인가.
예를 들어 git status의 (use "git add <file>..." to update...) 같은 안내 줄은 에이전트에게 아무 정보가 없습니다. lowfat은 이런 줄을 걸러 "브랜치 + 변경 파일 목록"만 남깁니다 — 신호는 그대로, 분량만 다이어트.
철학이 분명합니다: 가볍게(작은 단일 바이너리), 로컬 우선(텔레메트리 없음), 조합 가능(UNIX 파이프, 마법 아님), 사용자 소유(lowfat history로 내가 뭘 자주 쓰는지 보고 직접 커스터마이즈). 압축 강도는 lite/full/ultra 3레벨로 조절하고, README는 정직하게 "이 수치는 명령 출력 조각의 상한이지 전체 토큰 절감의 약속이 아니다"라고 못 박습니다.
트렌딩 이유 · 경쟁 대비 장점.
에이전트 사용량이 늘며 "토큰 다이어트" 도구가 우후죽순(README가 대안 7개를 직접 나열할 정도) 생겼습니다. lowfat의 포지션은 가장 가까운 경쟁자 rtk와의 비교에서 드러납니다 — rtk가 100+ 명령을 내장한 '풀옵션'이라면, lowfat은 6개 핵심 명령 + 확장 가능한 미니멀 코어입니다.
| 비교 항목 | rtk (batteries-included) | lowfat (minimal core) |
|---|---|---|
| 내장 명령 | 100+ 생태계 전반 | git·docker·grep·find·ls·tree 6개 정선 |
| 커스텀 필터 | TOML DSL | .lf DSL + 셸 + Python(PEP 723/uv) |
| 철학 | 다 해줌 | 코어는 작게, 내 사용 패턴은 내가 확장 |
장황한 출력은 토큰 비용일 뿐 아니라, 중요한 한 줄(에러·변경 파일)이 보일러플레이트에 묻혀 에이전트가 놓치는 원인이 되기도 합니다.
PreToolUse 훅(Claude Code)이나 셸 통합으로 명령 실행 길목에 서서, 명령별 필터(.lf)가 레벨에 맞게 줄을 거르고 합칩니다. lowfat stats가 누적 절감량을, --explain이 "왜 이 줄이 잘렸는지"를 보여줘 신뢰를 검증할 수 있습니다.
Rust 워크스페이스 — 코어·플러그인·러너·CLI 4크레이트.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 코어 | lowfat-core (Rust) | .lf DSL 파서(lf.rs)·파이프라인·레벨·토큰 추정(tokens.rs)·시크릿 마스킹(redact.rs)·기록(db.rs). |
| 필터 DSL | .lf 파일 | 줄 지향·들여쓰기 민감 규칙 언어 — 명령 출력의 거르기/병합 규칙 기술. |
| 플러그인 | lowfat-plugin + embedded/ | git·docker·grep·find·ls·tree 내장 필터 + 샘플 + 벤치마크 동봉. |
| 러너 | lowfat-runner (Rust) | 파이프라인 실행·플러그인 로딩·HybridRunner — lf_filter.rs·runner.rs·process.rs 포함. |
| 확장 | 셸 스크립트 · Python(PEP 723 + uv) | .lf로 부족하면 탈출구 — 단일 파일 Python 의존성 자동 설치. |
| 통합 | Claude Code 훅 · shell-init · OpenCode 플러그인 · Pi prefix | 4가지 주입 경로 — 에이전트 환경(CLAUDECODE=1 등) 자동 감지. |
| 관측 | stats · history · info · --explain | 절감량 추적, 자주 쓰는 명령 랭킹, 필터 동작 설명. |
| 배포 | cargo · brew · 바이너리 릴리스 | 단일 바이너리. |
git diff 출력 한 덩이가 다이어트되는 길.
.lf DSL이 설계의 중심입니다. lf.rs의 주석이 밝히듯 "줄 지향·들여쓰기 민감, INDENT/DEDENT 토큰 없이 (들여쓰기, 텍스트) 쌍으로 직접 파싱해 파서를 짧게, 에러 메시지를 소스 줄 번호에 묶는다"는 실용적 선택을 했습니다. 규칙은 define(재사용 매크로)과 rule(매칭→연산)로 구성되고, 레벨 조건이 붙어 같은 필터가 lite/full/ultra에서 다르게 동작합니다.
또 하나 중요한 디테일은 샘플·벤치마크 동봉 문화입니다. 내장 플러그인마다 실제 출력 샘플(samples/)과 bench.sh·BENCHMARK.md가 붙어 있어, README의 절감 수치를 cat 샘플 | lowfat filter ...로 누구나 재현할 수 있습니다.
비서에게 서류를 올리기 전의 요약 담당자와 같습니다. 30장짜리 보고서(git log)에서 결재에 필요한 핵심 줄만 추려 올리되, 요약 규칙(레벨)을 사장님이 정하고, "왜 이 줄을 뺐는지"(--explain)도 물어보면 답해주는.
어떤 폴더가 무슨 일을 하나.
| 위치 | 주목할 점 |
|---|---|
lowfat-core/src/lf.rs | DSL 파서 — 작은 언어 구현의 깔끔한 예제 (AST·들여쓰기 처리). |
embedded/*/samples/ + bench.sh | "수치는 재현 가능해야 한다" — 필터마다 실측 샘플과 벤치 동봉. |
lowfat-core/src/redact.rs | 출력 필터링 도구가 시크릿 마스킹까지 — 보너스 보안 계층. |
docs/PLUGINS.md | .lf 작법 + 셸/Python 탈출구 + "AI에게 플러그인 짜게 하는 프롬프트"까지. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
lf.rs는 "파서를 짧게 유지하는 설계 결정"이 주석으로 설명된, 미니 DSL 구현 입문에 알맞은 규모입니다. regex 기반 매칭 + 레벨 조건 + define 매크로의 조합을 따라가 보세요.
훅(PreToolUse)·셸 평가(shell-init + 환경 감지)·플러그인(OpenCode)·명령 prefix — 같은 기능을 환경별로 주입하는 방법의 비교 카탈로그입니다. 내 도구를 에이전트 워크플로에 투명하게 끼울 때 그대로 참고.
"이건 출력 조각의 상한이지 전체 절감의 약속이 아니다"라는 각주, 재현 명령 공개, 명령·레벨별 표 — 절감률 마케팅이 난무하는 분야에서 신뢰를 만드는 글쓰기의 예.
경쟁(rtk)의 batteries-included에 맞서 "6개만 잘하고 나머지는 .lf/셸/Python으로 너가" — 도구 설계에서 범위를 자르는 결정의 사례 연구입니다.
돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 설치 | cargo install lowfat 또는 brew install zdk/tools/lowfat 또는 릴리스 바이너리. |
| 통합 대상 | Claude Code(.claude/settings.json 훅)·OpenCode·Pi·일반 셸(zsh/bash) 중 택일. |
| Python 필터 | 선택 — PEP 723 인라인 의존성 + uv로 자동 처리 (plugin doctor가 점검). |
| 네트워크 | 불필요 — 완전 로컬, 텔레메트리 없음. |
난이도별로 손에 익히는 단계.
설치 후 작업 중인 레포에서 git status와 lowfat git status, git log와 lowfat git log를 나란히 실행해 비교합니다. lowfat level ultra로 바꿔 차이도.
PreToolUse 훅을 걸고 하루 작업 후 lowfat stats·lowfat history로 누적 절감과 "다이어트 효과가 큰 명령 랭킹"을 확인합니다. ultra 레벨에서 에이전트가 필요한 정보를 놓치지 않는지도 관찰.
동봉 샘플로 cat samples/git-diff-full.txt | lowfat filter --explain ./filter.lf --sub=diff --level=ultra를 돌려 어떤 규칙이 어떤 줄을 지웠는지 추적합니다 — .lf 문법이 자연스럽게 익혀집니다.
lowfat plugin new kubectl(또는 자주 쓰는 장황한 명령)로 스캐폴드를 만들고, 실제 출력 샘플을 받아 .lf 필터를 작성 → 레벨 3단계 동작까지 검증합니다. 내장 git 필터를 교본으로.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 설치·통합·레벨 체험 | README · 실습 1~2 |
| 2주차 | .lf DSL 문법과 파이프라인 | docs/PLUGINS.md·CONFIG.md · 실습 3 |
| 3주차 | 파서 구현 정독 | lf.rs · pipeline.rs |
| 4주차 | 플러그인 제작 + 대안 도구 비교 | 실습 4 · rtk·tokf 등 README 대안 목록 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| .lf DSL | lowfat 필터 규칙 언어 — 줄 지향, 들여쓰기 민감, 레벨 조건 지원. |
| 레벨 (lite/full/ultra) | 압축 강도 3단계 — 높을수록 손실 압축에 가까움. |
| PreToolUse 훅 | Claude Code가 도구 실행 직전 사용자 명령을 끼워 주는 지점. |
| shell-init | 셸 시작 시 평가해 에이전트 환경에서만 자동 활성화되는 통합. |
| redact | 출력 속 시크릿(토큰·키)을 마스킹하는 처리. |
| PEP 723 | Python 단일 파일에 의존성을 인라인 선언하는 규격 — uv가 자동 설치. |
| --explain | 어떤 규칙이 어떤 줄을 제거했는지 보여주는 디버그 모드. |
| tee | 명령 실패 시 raw 출력을 로컬에 보존하는 오류 덤프 모듈 — exit_code != 0이고 출력 500자 이상일 때만 동작. |
| rtk | 가장 가까운 경쟁 도구 — batteries-included 철학의 대척점. |