Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
tokf는 CLI 명령어의 장황하고 노이즈가 많은 출력을 가로채 TOML 필터를 적용하여 핵심 정보만 추출하는 도구입니다. 이 기능을 통해 AI 에이전트가 시스템 명령을 실행할 때 발생하는 불필요한 토큰 소모를 60~90%까지 줄일 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기CI
crates.io
crates.io downloads
License: MIT
tokf.net — CLI 명령어에서 발생하는 LLM 컨텍스트 소비량을 60–90% 줄여줍니다.
git push, cargo test, docker build와 같은 명령어들은 진행률 표시줄, 컴파일 노이즈, 상용구(boilerplate) 등으로 가득 찬 장황한 출력을 생성합니다. tokf는 이러한 출력을 가로채서 TOML 필터를 적용하고 중요한 내용만 추출하여 방출함으로써, AI 에이전트가 수백 개의 낭비되는 토큰 대신 깨끗한 신호만을 볼 수 있도록 합니다.
cargo test — 61줄 → 1줄:
Compiling tokf v0.2.0 (/home/user/tokf)
Compiling proc-macro2 v1.0.92
Compiling unicode-ident v1.0.14
...
✓ 47 passed (2.31s)
git push — 8줄 → 1줄:
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 10 threads
...
ok ✓ main
brew install mpecan/tokf/tokf # 또는: cargo install tokf
tokf setup # AI 도구를 감지하고 후크를 설치합니다
이것으로 끝입니다. 이제 AI 에이전트가 실행하는 모든 명령어는 자동으로 필터링됩니다.
tokf gain을 실행하여 얼마나 많은 토큰을 절약했는지 확인하거나, tokf setup --refresh를 실행하여 감지를 다시 수행할 수 있습니다.
brew install mpecan/tokf/tokf
cargo install tokf
git clone https://github.com/mpecan/tokf
cd tokf
cargo build --release
...
tokf run git push origin main
tokf는 git push에 대한 필터를 찾아 명령을 실행하고 해당 필터를 적용합니다. 필터 로직은 일반 TOML 파일에 존재하므로 재컴파일이 필요 없습니다. 누구나 필터를 작성(author), 공유하거나 덮어쓸 수 있습니다.
출력을 압축하는 것만이 이 도구가 좋은 점은 아닙니다. 파이프라인은 마지막 단계의 종료 코드(exit code)를 보고합니다. 따라서 just check 2>&1 | tail -8는 테스트가 실패했더라도 tail의 성공을 보고하지만, 출력을 작게 유지하기 위해 에이전트들이 사용하는 단축키들은 정확히 그 실패 신호를 폐기하는 것들입니다. pipeline capture를 활성화하면 tokf가 첫 번째 단계를 직접 실행하여 파이프라인이 명령어의 판결을 숨겼는지 여부를 알려줄 수 있습니다.
AI 코딩 도구를 사용한다면, 모든 명령이 자동으로 필터링되도록 훅(hook)을 설치하세요. 그러면 tokf run 접두사를 사용할 필요가 없습니다:
# Claude Code (권장: --global 플래그를 사용하여 모든 프로젝트에서 작동하도록 설정)
tokf hook install --global
...
현재 프로젝트에만 설치하려면 --global을 생략하세요. 각 도구, --path 플래그 및 필터 작성 스킬과 같은 선택적 추가 기능에 대한 자세한 내용은 Claude Code 훅을 참조하세요.
tokf run git push origin main
tokf run cargo test
tokf run docker build .
tokf apply filters/git/push.toml tests/fixtures/git_push_success.txt --exit-code 0
tokf verify # 모든 테스트 스위트를 실행합니다.
tokf verify git/push # 특정 스위트를 실행합니다.
tokf verify --list # 사용 가능한 스위트 목록과 케이스 수를 나열합니다.
...
tokf는 make와 just를 자동으로 감싸서(wrap) 각 레시피 라인마다 개별적으로 필터링을 수행합니다:
make check # 각 레시피 라인 (cargo test, cargo clippy 등)이 필터링됩니다.
just test # 동일합니다. 각 레시피가 tokf를 통해 실행됩니다.
자세한 내용 및 사용자 정의는 Rewrite configuration을 참조하세요.
tokf ls # 모든 필터 목록 표시
tokf which "cargo test" # 어떤 필터가 일치하는지 확인
tokf show git/push # TOML 소스 출력
tokf eject cargo/build # .tokf/filters/ 에 복사 (프로젝트 로컬)
tokf eject cargo/build --global # ~/.config/tokf/filters/ 에 복사 (사용자 레벨)
이는 필터의 TOML과 테스트 스위트를 설정 디렉토리에 복사하여 내장된 것을 덮어씁니다(shadows). 추출된 사본을 자유롭게 편집할 수 있으며, tokf의 우선순위 시스템은 원본 대신 사용자가 정의한 버전을 사용하도록 보장합니다.
| Flag | Description |
|---|---|
--timing | 필터링에 걸린 시간을 출력합니다. |
| ... |
기본적으로 strip_ansi = true를 가진 필터는 ANSI 이스케이프 코드를 영구적으로 제거합니다. --preserve-color 플래그가 이를 변경합니다: tokf는 패턴 매칭(skip, keep, dedup)을 위해 ANSI를 내부적으로 제거하지만, 최종 출력에서는 원래의 색상화된 줄을 복원합니다. --preserve-color가 활성화되면 필터 설정의 strip_ansi = true를 재정의합니다.
tokf는 명령어가 색상을 출력하도록 강제하지 않습니다. 자식 명령어가 ANSI 코드를 출력하는지 확인해야 합니다(예: FORCE_COLOR=1 또는 --color=always를 통해):
# Node.js / Vitest / Jest
FORCE_COLOR=1 tokf run --preserve-color npm test
...
제한 사항: 색상 통과는 skip/keep/dedup 파이프라인(2~2.5 단계)에 적용됩니다. match_output, parse, 및 lua_script 단계는 깨끗한 텍스트에서 작동하며 이 플래그의 영향을 받지 않습니다. [[replace]] 규칙은 색상 분할 전 원본 텍스트에서 실행되므로, --preserve-color가 활성화되면 해당 패턴이 ANSI 이스케이프 코드를 고려해야 할 수 있습니다. 이는 복원된 색상 텍스트와 일치하는 브랜치 레벨의 skip 패턴과 유사합니다.
| Filter | Command |
|---|---|
git/add | git add |
| ... |
특정 명령에 전용 필터가 없는 경우, 세 가지 내장 하위 명령어(subcommands)가 임의 출력물에 유용한 압축 기능을 제공합니다:
| Command | Purpose | Default context |
|---|---|---|
tokf err <cmd> | 오류 및 경고 추출 | 3 lines |
| ... |
tokf err — 오류 추출 (Error extraction)일반적인 툴체인(Rust, Python, Node, Go, Java) 전반의 출력에서 오류/경고 패턴을 스캔하고 관련 라인과 주변 컨텍스트만 보여줍니다.
# 빌드에서 오류만 표시
tokf err cargo build
...
일치하는 패턴: error:, warning:, FAILED, Traceback, panic, npm ERR!, fatal:, Python/Java 예외 유형 등.
동작 방식 (Behaviour):
[tokf err] no errors detected (empty output)가 출력됩니다.[tokf err] 헤더가 표시됩니다.[tokf err] no errors detected가 출력됩니다.tokf test — 테스트 실패 추출 (Test failure extraction)테스트 실패 세부 정보를 추출하며 항상 요약/결과 라인을 포함합니다.
# 테스트 실패만 표시
tokf test cargo test
tokf test go test ./...
...
일치하는 패턴: FAIL, FAILED, panicked, 어설션 불일치(assertion mismatches), Jest의 ✕ 마커, Go의 --- FAIL: 등.
항상 포함되는 요약 라인: test result:, Tests:, passed, failed 카운트, pytest/RSpec 요약 라인.
동작 방식 (Behaviour):
[tokf test] all tests passed가 출력됩니다.tokf summary — 휴리스틱 요약 (Heuristic summary)헤더(header), 푸터/요약(footer/summary), 그리고 반복적인 중간 섹션을 식별하여 예산 제약이 있는 요약을 생성합니다.
# 긴 빌드 로그 요약
tokf summary cargo build
...
알고리즘:
[tokf summary] 라인으로 추가됨세 명령어 모두 다음을 지원합니다:
| 플래그 | 설명 |
|---|---|
--baseline-pipe <cmd> | 기준선 회계 처리(예: tokf run과 동일) |
| ... |
일반 명령어는 rewrite system과 통합되어 훅(hook)을 통해 자동으로 트리거될 수 있습니다. 전용 필터가 없는 명령어에 대한 규칙은 .tokf/rewrites.toml 파일에 추가하세요:
# 필터가 없는 빌드 명령어를 tokf 에러를 통해 라우팅합니다
[[rewrite]]
match = "^mix compile"
...
중요: 사용자 리라이트 규칙은 필터 매칭 전에 확인됩니다. 이미 전용 필터(예: cargo build, npm test)가 있는 명령어에 대한 규칙을 추가하지 마세요. 전용 필터가 일반 명령어보다 더 나은 출력을 생성할 것입니다.
명령어에 이미 필터가 있는지 확인하려면 다음 명령어를 사용하세요: tokf which "cargo build"
일반 명령어는 tokf run과 동일한 추적 데이터베이스와 기록을 사용하여, 필터 이름 _builtin/err, _builtin/test, 그리고 _builtin/summary를 사용합니다. 전체 압축되지 않은 출력을 보려면 tokf raw last를 사용하세요.
필터는 .tokf/filters/ (프로젝트 로컬) 또는 ~/.config/tokf/filters/ (사용자 레벨)에 위치한 TOML 파일입니다. 프로젝트 로컬 필터가 사용자 레벨보다 우선하며, 사용자 레벨이 내장 라이브러리(built-in library)보다 우선합니다.
command = "my-tool"
[on_success]
...
tokf는 두 가지 내장 동작(built-in behaviours)을 사용하여 필터 패턴과 명령어를 매칭합니다:
Basename 매칭 — 패턴의 첫 번째 단어는 basename으로 비교됩니다. 따라서 command = "git push"를 가진 필터는 /usr/bin/git push 또는 ./git push와도 일치합니다. 이는 자동으로 작동하며, 특별한 패턴 구문이 필요하지 않습니다.
투명 전역 플래그 (Transparent global flags) — 명령어 이름과 서브커맨드 키워드 사이의 플래그 형태 토큰은 매칭 중에 건너뛰어집니다. git log에 대한 필터는 다음 모든 경우와 일치합니다:
git log
git -C /path log
git --no-pager -C /path log --oneline
...
건너뛴 플래그들은 실제로 실행되는 명령어에는 보존되며, 패턴 매칭 시에만 우회됩니다.
참고:
run오버라이드와 투명 플래그: 필터가run필드를 설정하는 경우, 투명 전역 플래그는{args}에 포함되지 않습니다. 매칭된 패턴 단어들 뒤에 나타나는 인자만이{args}로 사용 가능합니다.
로컬 환경 래퍼 (Local environment wrappers) — 필터가 nix develop -c cargo test와 같은 로컬 래퍼를 통해 매칭되도록 하려면 특별히 할 필요가 없습니다. tokf는 래퍼 접두사를 제거하고 내부 명령어(cargo test)를 기존 패턴과 비교합니다. 구성 가능한 목록은 Local environment wrappers를 참조하십시오.
command = "git push" # 매칭할 명령어 패턴 (와일드카드 및 배열 지원)
run = "git push {args}" # 실제로 실행할 오버라이드 명령어
description = "간결한 git push 출력" # 사람이 읽기 쉬운 설명 (tokf ls에서 표시됨)
...
run 오버라이드run은 tokf가 사용자가 입력한 것과 다른 명령어를 실행하도록 만듭니다. 이는 정교한 도구이며, 한 가지 규칙이 있습니다:
run은 정보를 손실해서는 안 됩니다. 동일한 데이터를 더 밀도 있게 재인코딩할 수는 있지만 (--porcelain,--format json,-o json), 사용자가 요청한 것보다 좁은 질문으로 절대로 잘라내거나, 제한하거나, 답변해서는 안 됩니다.
그 이유는 복구 가능성(recoverability) 때문입니다. tokf는 자신이 실제로 실행한 명령어의 출력만을 보기 때문에, 이 출력이 히스토리에 기록되고 tokf raw <id>가 돌려주는 내용이 됩니다. 만약 run이 tokf가 데이터를 보기 전에 데이터를 버린다면, 아무것도 복구할 수 없습니다—tokf raw로도, 다른 어떤 방법으로도도 말입니다. 콘텐츠를 누락시키는 축소(Reductions)는 전체 출력이 캡처된 후에 실행되는 필터 파이프라인(skip, chunk, max_lines, templates)에 속해야 합니다.
치환(Substitutions)은 기록되고 표시됩니다. tokf history show는 Executed: 라인을 출력하고, tokf raw는 stderr로 메모를 출력합니다 (stdout은 순수한 출력을 유지하므로 파이프에는 영향을 주지 않습니다). 그리고 --verbose 옵션은 치환이 발생하는 순간에 그 내용을 보고합니다:
$ tokf run --verbose -- git status
[tokf] executing: git status --porcelain=v1 -b -uall --find-renames
[tokf] (substituted by `run` for: git status)
...
run-오버라이드 필터의 절약량은 치환된 명령어의 출력을 기준으로 측정된다는 점에 유의하십시오. 이것이 tokf가 관찰하는 유일한 기준선입니다. Executed: 라인은 해당 그림(figure)이 어떤 명령어를 참조하는지 알려줍니다.