graphify를 쓰면 에이전트 토큰이 80% 준다는데, 과연 진짜일까?

이번 시간에는 코드를 미리 그래프로 만들어 두고 에이전트가 그 그래프부터 묻게 하는 graphify가 실제로 토큰을 줄이는지 claude -p로 측정하며 배워가는 시간입니다. claude -p는 대화 화면 없이 질문 하나를 보내고 결과를 받는 실행 방식이에요.

같은 질문을 graphify를 설치한 저장소와 안 한 저장소에 번갈아 보내서, 어떤 도구를 몇 번 부르고 어떤 파일을 읽었는지와 입력 토큰을 비교할게요. 이 글에서 입력은 결과 JSON의 세 필드(input_tokens, cache_creation_input_tokens, cache_read_input_tokens) 합이고, 캐시에서 읽은 토큰도 모델 요청마다 다시 읽으니 함께 셉니다.

다시 돌리면 숫자가 달라질 수 있고, --model opus가 가리키는 모델도 시간이 지나면 달라질 수 있어요.

graphify가 하는 일과 공개 수치

graphify는 tree-sitter로 소스 코드를 읽어 함수·클래스와 그 사이의 호출·상속·import 관계를 graphify-out/graph.json에 그래프로 저장해요. 에이전트는 graphify query "<질문>", graphify explain "<이름>", graphify path "<A>" "<B>"로 이 그래프에서 필요한 부분만 꺼내 봅니다.

README 맨 위의 "Cut agent token spend by 80%."는 유료 서비스 Graphify Cloud를 소개하는 문장이고, 측정 방법이나 비교 기준은 적혀 있지 않아요. 오픈소스 쪽 docs/how-it-works.md에는 파일 52개 묶음에서 질의당 토큰이 71.5배 적다는 수치가 있지만, 원본 파일을 모두 읽는 경우와 그래프 출력 크기를 비교한 값이라 에이전트 실행이 아니에요.

에이전트로 잰 BENCHMARKS.md는 ERPNext 질문 6개에서 핵심 사실을 담은 비율이 82.0%로 grep·파일 읽기만 쓴 기준(70.8%)보다 높았다는 정확도 수치예요. 질의당 약 140K 토큰, 저장소를 통째로 넣으면 약 20배라는 값은 있지만, grep 기준과 토큰을 비교한 수치는 없어요.

그래서 이 글은 오픈소스 graphify를 공식 방법대로 붙였을 때 토큰이 줄어드는지 직접 잽니다.

실습 준비

이 글의 명령은 모두 실습 코드의 graphify-code-graph/ 디렉터리에서 실행합니다.

• Dockerfile: graphify 0.9.95를 넣은 이미지 graphify-lab:0.9.95
• lab.sh: 인덱스를 만드는 index, 컨테이너와 graphify 실행 파일을 준비하는 start, 질문 하나를 보내는 ask, 정해 둔 순서대로 26번 묻는 run
• summarize.py: 결과를 질문·조건별로 모으고 정답을 판정하며, 호출 하나의 도구 사용 목록을 보여 주는 스크립트

따라 하시려면 Claude Code 2.1.309와 구독 로그인, Docker, jq, bash가 필요해요.

공식 설치는 uv tool install graphifyy(또는 pipx, pip) 뒤 graphify install이에요. 프로젝트에서는 Claude Code 안에서 /graphify .로 그래프를 만들거나, 코드만 다룰 때는 graphify extract . --code-only로 만든 뒤 graphify claude install을 실행합니다.

여기서는 Mac에 아무것도 설치하지 않고, 코드가 밖으로 나가지 않는지 네트워크를 끊어 확인하려고 graphify를 Docker 이미지에 넣었어요.

FROM python:3.12-slim
RUN pip install --no-cache-dir "graphifyy[mcp]==0.9.95"
ENV GRAPHIFY_BACKEND=none GRAPHIFY_NO_TIPS=1 GRAPHIFY_NO_CTA=1 GRAPHIFY_QUERY_LOG_DISABLE=1 \
    DO_NOT_TRACK=1 PYTHONDONTWRITEBYTECODE=1 PIP_DISABLE_PIP_VERSION_CHECK=1

GRAPHIFY_BACKEND=none은 문서·이미지 해석과 그래프 묶음 이름 짓기에 쓰는 LLM을 모두 끄는 설정이에요. 나머지는 질의 기록·안내 문구·추적을 끄는 설정과 Python·pip 설정이에요.

아래 블록은 파일로 만들지 말고 실습 디렉터리에서 연 터미널에 그대로 붙여 넣어 주세요. 이후 명령은 모두 이 터미널에서 실행하고, 터미널을 새로 열면 다시 붙여 넣으시면 됩니다.

export RICH_TAR=$PWD/rich-v15.0.0.tar.gz

py312() { docker run --rm --network none -v "$PWD":/w -w /w python:3.12-slim python -I "$@"; }

excerpt() { jq 'select(.type == "result") | {usage: (.usage | {input_tokens, cache_creation_input_tokens, cache_read_input_tokens, output_tokens}), num_turns, total_cost_usd, duration_ms}' "$@"; }

이미지를 만들고 rich v15.0.0 소스를 받은 다음, 그래프를 한 번 만들어요.

docker build -t graphify-lab:0.9.95 .
curl -L -o rich-v15.0.0.tar.gz https://github.com/Textualize/rich/archive/refs/tags/v15.0.0.tar.gz
chmod +x lab.sh
./lab.sh index

index는 work/runs/b/rich에 rich를 풀고 네트워크를 끊은 컨테이너에서 graphify extract . --code-only, graphify cluster-only ., graphify claude install --project를 실행해요. 결과는 work/seed/에 보관했다가 매 회차 새 저장소에 복사합니다(출력 발췌).

[graphify extract] found 405 code, 0 docs, 0 papers, 0 images
real	0m7.311s
[graphify label] LLM backends disabled by GRAPHIFY_BACKEND=none; keeping Community N placeholders.
Graph: 3445 nodes, 9610 edges
Done - 165 communities. GRAPH_REPORT.md, graph.json and graph.html updated.
real	0m2.461s
  .claude/settings.json  ->  PreToolUse hooks registered (Bash|Grep search + Read/Glob)

그래프 만들기 7.3초, 묶음 나누기 2.5초였고 graphify-out/은 12MB(graph.json 3.2MB)였어요. --code-only가 문서 110개와 이미지 25개를 건너뛰어 LLM이나 임베딩 API를 한 번도 부르지 않았고, 네트워크가 끊긴 채로 끝났으니 코드가 밖으로 나가지 않았습니다.

--project는 스킬을 홈이 아닌 저장소 .claude/에 두고 훅 명령을 경로 없이 써요. 저장소에는 세 가지가 생깁니다.

• CLAUDE.md의 ## graphify 절(1,159바이트): "run graphify query "<question>" before your first grep, search or source-file read for a codebase question"이 들어 있는 규칙 5줄
• .claude/settings.json: PreToolUse 훅 두 개. Bash·Grep 호출 전에는 graphify hook-guard search, Read·Glob 호출 전에는 graphify hook-guard read가 돌아요.
• .claude/skills/graphify/: /graphify 스킬 파일과 그 스킬을 알리는 .claude/CLAUDE.md

훅은 그래프부터 조회하라는 안내를 덧붙이기만 하고, 0.9.95는 세션마다 처음 한 번, 그 뒤로는 30분 안에 조회가 없을 때만 많아야 5번까지 붙여요. MCP 서버(graphify-mcp)는 어떤 설치 명령도 등록하지 않아서, 이 글은 Claude가 Bash로 graphify를 치는 길만 잽니다.

./lab.sh start는 graphify 컨테이너를 띄우고, Claude Code가 쓸 graphify 실행 파일을 work/bin/에 만들어요.

start() {
  docker rm -f "$CTR" > /dev/null 2>&1
  docker run -d --name "$CTR" --network none -e HOME=/tmp/h \
    -v "$WORK/runs/b:$WORK/runs/b" "$IMAGE" sleep infinity > /dev/null
  mkdir -p "$WORK/bin" "$OUT"
  cat > "$WORK/bin/graphify" <<EOF
#!/bin/sh
case "\$PWD" in "$WORK/runs/b"*) wd="\$PWD" ;; *) wd="$B" ;; esac
echo "\$*" >> "\${GFY_LOG:-/dev/null}"
exec docker exec -i -w "\$wd" $CTR graphify "\$@"
EOF
  chmod +x "$WORK/bin/graphify"
  echo '{"mcpServers":{}}' > "$WORK/mcp-empty.json"
}

저장소를 컨테이너에 같은 절대 경로로 붙여서, 이 실행 파일은 받은 인자를 그대로 컨테이너 안의 graphify에 넘겨요. 훅 명령 graphify hook-guard ...도 설치 파일을 고치지 않고 이 파일을 거칩니다. 실제 설치와 달리 graphify가 컨테이너에서 돌고 호출마다 docker exec 시간이 더 들어서, 걸린 시간은 참고로만 봐요.

ask는 조건 a(기준)와 b(graphify)를 이렇게 나눠요.

ask() {
  local cond=$1 qid=$2 name=$3 dir=$A env_path=$PATH
  local allow=()
  if [ "$cond" = b ]; then
    dir=$B
    fresh_repo "$B" && cp -a "$WORK/seed/." "$B/"
    rm -rf "$B/graphify-out/cache/last_query_stamp" "$B/graphify-out/cache/hook_sessions"
    env_path="$WORK/bin:$PATH"
    allow=(--allowedTools "Bash(graphify:*)")
  else
    fresh_repo "$A"
  fi
  (cd "$dir" && PATH="$env_path" GFY_LOG="$OUT/$name.graphify.log" \
    DISABLE_TELEMETRY=1 DISABLE_AUTOUPDATER=1 DISABLE_ERROR_REPORTING=1 \
    perl -e 'alarm shift; exec @ARGV' 900 \
    claude -p "$(question "$qid")" --model opus --effort medium \
      --tools "Bash,Read,Grep,Glob,ToolSearch,Skill" ${allow[@]+"${allow[@]}"} \
      --setting-sources project --strict-mcp-config --mcp-config "$WORK/mcp-empty.json" \
      --no-session-persistence --include-hook-events \
      --output-format stream-json --verbose < /dev/null) > "$OUT/$name.jsonl" 2> "$OUT/$name.err"
  tail -n 1 "$OUT/$name.jsonl" | jq -r '.result // empty' > "$OUT/$name.answer.txt"
}

• 두 조건 모두 회차마다 rich를 길이가 같은 경로(work/runs/a/rich, work/runs/b/rich)에 새로 풀어요.
• graphify 조건에만 그래프와 설치 파일을 복사하고, 앞 회차의 조회 기록이 훅 안내를 막지 않게 상태 파일 두 개를 지워요.
• --allowedTools "Bash(graphify:*)"는 graphify 조건에만 줬어요. 대화 화면에서는 사용자가 처음 한 번 허락하지만 claude -p에는 그 창이 없어서예요.
• --setting-sources project는 홈 설정 없이 저장소의 CLAUDE.md와 .claude/만 읽게 해요. graphify-out/이 Grep 결과에 걸리는 것은 실제 사용과 같아 그대로 뒀습니다.

질문 4개는 lab.sh에 원문 그대로 있어요. 모두 "tests와 docs는 제외. 코드는 수정하지 마."로 끝나고 그래프를 쓰라는 말은 없습니다.

• q1: _render_buffer가 정의된 곳과 이를 직접 호출하는 함수를 모두 찾기
• q2: rich/_loop.py의 loop_last가 바뀌면 직접 영향받는 모듈과 함수를 모두 찾기
• q3: rich.print("[bold]hi[/bold]")에서 rich/markup.py의 _parse까지 이어지는 호출 경로 찾기
• q4: Highlighter를 직접 또는 간접 상속하는 클래스를 모두 찾고 highlight 오버라이드 여부 알리기

정답 목록은 Python ast 호출 그래프로 뽑고 소스를 읽어 확인했고, summarize.py 안에 판정 규칙과 함께 들어 있어요. 질문마다 필요한 함수·클래스 이름(q1 5개, q2 12개, q3 6단계, q4 9개)이 같은 줄이나 가까운 줄(위 40줄, 아래 3줄)의 파일 이름과 함께 모두 나와야 정답입니다. q3의 순서와 q4의 오버라이드 구분은 답을 직접 읽어 확인했어요.

실습 1: 같은 질문에서 무엇을 부르고 무엇을 읽었나

먼저 26번을 모두 돌려요. 조건별 워밍업 1번 뒤에 질문과 조건을 섞은 24번이 이어지고, 결과는 out/<회차>.jsonl에 쌓입니다.

./lab.sh run

q2(loop_last를 바꾸면 영향받는 함수)에서 두 조건의 입력 토큰이 각각 중앙값이었던 회차를 하나씩 볼게요. summarize.py out calls <회차>는 Claude가 부른 도구를 순서대로, 결과 글자 수와 함께 보여 줍니다.

py312 summarize.py out calls 18-a-q2-r3
py312 summarize.py out calls 04-b-q2-r1

1. Grep loop_last|from \._loop|_loop import|import _loop -> 2,115자
2. Read rich/_loop.py -> 1,359자
3. Bash grep -rln "loop_last\|_loop" --include=*.py . | grep -v -E '^\./(tests|docs)/' ; python3 - -> 652자, 거부
4. Grep loop_last -> 192자
5. Grep ^\s*(def|class) \w+ -> 10,932자
6. Read rich/tree.py -> 3,209자
7. Grep Iterator\[Tuple\[bool -> 69자
1. Bash ls graphify-out; graphify explain "loop_last" 2>&1 | head -80 -> 1,695자
2. Bash graphify explain "loop_last" --all 2>&1 | sed -n '/Connections/,/Grouped/p'; echo ---; gre -> 172자, 거부
3. Bash graphify explain "loop_last()" --all -> 1,864자
4. Bash grep -rn "loop_last" rich/ --include=*.py -> 42자
5. Bash grep -rn "loop_last" rich -> 2,017자
6. Bash python3 -I - <<'EOF' -> 59자, 거부
7. Bash grep -nE "^\s*(def|class) " rich/tree.py rich/pretty.py rich/text.py rich/table.py rich/tr -> 10,932자
8. Read rich/tree.py -> 2,986자
9. Read rich/pretty.py -> 1,142자

기준 회차는 Grep으로 loop_last를 쓰는 곳을 찾고, 파일마다 함수 정의 줄을 뽑아 호출 줄이 어느 함수 안에 있는지 맞춰 봤어요. graphify 회차는 CLAUDE.md 규칙대로 첫 호출부터 graphify explain "loop_last"를 불렀고, 세 번째 호출의 결과 1,864자에 답에 필요한 호출 함수가 모두 들어 있었어요. 다만 .__rich_console__()처럼 클래스 이름이 빠진 채 파일·줄 번호와 함께 나왔습니다.

그런데 그다음이 줄지 않았어요. 그래프는 같은 함수 안의 호출 줄을 하나씩만 보여 줬고, Claude는 답에 그 빠진 줄을 채우려고 grep으로 호출 줄을 다시 찾고, 함수 정의 줄 10,932자를 뽑고, 파일 두 개를 읽어 확인했습니다. "거부"는 claude -p가 승인 없이 실행하지 않는 명령(여러 명령을 묶은 줄의 일부, python3 스크립트 등)이라 막힌 호출이에요.

이 회차에서 훅 안내는 grep이 섞인 두 번째 Bash 호출에 한 번 붙었어요.

jq -c 'select(.subtype == "hook_response" and (.output | test("additionalContext"))) | {hook_name, output: (.output | fromjson | .hookSpecificOutput.additionalContext)}' out/04-b-q2-r1.jsonl

{"hook_name":"PreToolUse:Bash","output":"MANDATORY: graphify-out/graph.json exists. You MUST run `graphify query \"<question>\"` before grepping raw files. Grep raw files only once you know the exact file and lines you need, from the graph or an earlier read.\nStart with: `graphify explain \"loop_last()\"`\nWhat the graph already has for this call:\n- loop_last() (rich/_loop.py L18)\n- test_loop_last() (tests/test_tools.py L14)"}

두 회차의 결과 JSON을 나란히 볼게요(필요한 필드만 남긴 발췌).

excerpt out/18-a-q2-r3.jsonl out/04-b-q2-r1.jsonl

{
  "usage": {
    "input_tokens": 12,
    "cache_creation_input_tokens": 10101,
    "cache_read_input_tokens": 79450,
    "output_tokens": 3519
  },
  "num_turns": 8,
  "total_cost_usd": 0.167126,
  "duration_ms": 40746
}
{
  "usage": {
    "input_tokens": 18,
    "cache_creation_input_tokens": 15772,
    "cache_read_input_tokens": 116250,
    "output_tokens": 4008
  },
  "num_turns": 10,
  "total_cost_usd": 0.229658,
  "duration_ms": 57308
}

입력은 기준 89,563, graphify 132,040이었고 턴은 8에서 10으로 늘었습니다.

실습 2: 질문 4개를 3번씩

질문·조건별 중앙값부터 볼게요.

py312 summarize.py out short

q1 기준: 정답 3/3, 입력 56,386, 8턴, 도구 호출 7(Grep 3, Read 0, graphify 0) (중앙값)
q1 graphify: 정답 3/3, 입력 87,705, 7턴, 도구 호출 6(Grep 3, Read 0, graphify 2) (중앙값)
q2 기준: 정답 3/3, 입력 89,563, 8턴, 도구 호출 7(Grep 3, Read 1, graphify 0) (중앙값)
q2 graphify: 정답 3/3, 입력 132,040, 10턴, 도구 호출 9(Grep 3, Read 2, graphify 2) (중앙값)
q3 기준: 정답 3/3, 입력 34,716, 3턴, 도구 호출 2(Grep 1, Read 0, graphify 0) (중앙값)
q3 graphify: 정답 3/3, 입력 85,827, 7턴, 도구 호출 6(Grep 0, Read 0, graphify 7) (중앙값)
q4 기준: 정답 3/3, 입력 41,661, 4턴, 도구 호출 3(Grep 2, Read 1, graphify 0) (중앙값)
q4 graphify: 정답 3/3, 입력 52,913, 5턴, 도구 호출 4(Grep 2, Read 0, graphify 1) (중앙값)

네 질문 모두 graphify 조건의 입력 중앙값이 더 컸어요. q4가 27%로 가장 덜 늘었고, q3는 34,716에서 85,827로 2.5배가 됐습니다. 정답은 두 조건 모두 질문마다 3번 중 3번이었어요.

q3 기준 조건은 세 번 중 두 번을 도구 호출 2번으로 답했어요. graphify 조건은 graphify path와 explain을 회차마다 3~7번 실행했는데, 두 회차는 render_str에서 markup.render로 가는 호출이 그래프에 없어 소스로 확인했다고 답에 적었어요. from .markup import render as render_markup처럼 이름을 바꿔 가져와서 그래프가 잇지 못한 것으로 보여요.

다음은 조건별 전체 12번이에요.

py312 summarize.py out | tail -8

전체 기준: 12회, 정답 12/12
  중앙값: 입력 51,530, 캐시 쓰기 6,712, 출력 1,826, 6.0턴, 21.4초, $0.099, Grep 3.0, Read 1.0, 파일 1.0, 도구 호출 5.0, 도구 결과 13,091자(graphify 0자), graphify 명령 0.0
  합계: 입력 684,521, 72턴, 모델 요청 54번(요청당 입력 12,676), 도구 결과 157,669자(graphify 0자)
  호출 합계: 도구 60, Grep 31, Glob 0, Read 13, Bash 16(거부 8), Skill 0, ToolSearch 0, graphify 명령 0, graphify를 쓴 회차 0, 안내 주입 0
전체 graphify: 12회, 정답 12/12
  중앙값: 입력 86,766, 캐시 쓰기 6,934, 출력 2,134, 7.5턴, 35.8초, $0.110, Grep 2.0, Read 0.0, 파일 0.0, 도구 호출 6.5, 도구 결과 10,033자(graphify 5,282자), graphify 명령 2.0
  합계: 입력 1,106,328, 92턴, 모델 요청 80번(요청당 입력 13,829), 도구 결과 136,286자(graphify 59,788자)
  호출 합계: 도구 80, Grep 22, Glob 0, Read 8, Bash 50(거부 14), Skill 0, ToolSearch 0, graphify 명령 33(explain 17, path 9, query 7), graphify를 쓴 회차 12, 안내 주입 11

graphify 조건은 12번 모두 graphify를 실행했어요(래퍼 기록으로 explain 17번, path 9번, query 7번). /graphify 스킬은 한 번도 부르지 않았고, 훅 안내는 회차마다 많아야 한 번씩 모두 11번 붙었습니다.

탐색 자체는 조금 줄었어요. Grep은 31번에서 22번, Read는 13번에서 8번이 됐고, 받은 도구 결과도 157,669자에서 136,286자로 14% 적었습니다.

그런데 입력 합계는 684,521에서 1,106,328로 62% 늘었어요. graphify 명령이 Bash로 더해져 도구 호출이 60번에서 80번, 모델 요청(API 호출)이 54번에서 80번으로 늘었고, 요청당 입력도 12,676토큰에서 13,829토큰으로 커졌어요. 턴(num_turns, 72 대 92)은 도구 호출 수에 회차당 1을 더한 값이라 요청 수와 달라요.

늘어난 호출 20번 중 6번은 claude -p가 막은 Bash(거부 8번 대 14번)예요.

요청마다 커진 몫의 대부분은 설치 파일이 늘 붙이는 고정 입력이에요. 회차마다 첫 요청의 입력을 보면 이렇습니다.

py312 summarize.py out first

기준 첫 요청 입력: 중앙값 9,536, 최소 9,512, 최대 9,547
graphify 첫 요청 입력: 중앙값 10,438, 최소 10,415, 최대 10,450

CLAUDE.md의 graphify 규칙, .claude/CLAUDE.md, 스킬 목록의 graphify 설명 한 줄이 요청마다 약 900토큰을 더해요. 요청당 늘어난 1,153토큰의 나머지는 나눠 재지 않았어요.

비용 추정 중앙값($0.099 대 $0.110)은 캐시 순서에 흔들려 보조로만 봤고, 걸린 시간(21.4초 대 35.8초)에는 docker exec 시간이 섞여 있어요.

정리

범위: Claude Code 2.1.309 claude -p, Opus 5.5, effort medium, 도구 목록 Bash,Read,Grep,Glob,ToolSearch,Skill, graphify 0.9.95 공식 Claude Code 설치(CLAUDE.md 규칙, PreToolUse 훅, 스킬)를 Docker로 감싼 조건 대 설치하지 않은 조건, rich v15.0.0 질문 4개를 조건별 3번씩.

• README의 "80%"는 유료 Graphify Cloud 소개 문장이고, 71.5배는 원본 파일 전체와 그래프 출력의 크기 비교라 에이전트로 잰 공개 수치는 정확도뿐이에요. 오픈소스 graphify를 공식 방법대로 붙인 조건은 입력 토큰 중앙값이 51,530에서 86,766으로 68% 늘었고, 질문 4개 모두 늘었습니다.
• CLAUDE.md 규칙만으로 Claude는 12번 모두 첫 탐색을 graphify로 시작했고 정답 수도 12번 중 12번으로 같았어요. 그래프가 호출 함수를 모두 보여 준 q2 회차에서도 Claude는 grep과 파일 읽기로 다시 확인했으니, 그래프를 붙여도 확인 탐색이 사라진다고 기대하지 마세요.
• Grep·Read 호출과 받은 도구 결과는 줄었지만 graphify 호출과 모델 요청이 더 늘어 합계가 커졌어요. 탐색량만 보지 말고, 내 저장소에서 요청 수와 입력 세 필드 합을 함께 재 보세요.
• 설치하면 요청마다 약 900토큰의 안내가 고정으로 붙어요. 이 글의 짧은 탐색에서는 이 비용을 되찾지 못했으니, 파일을 수십 개씩 읽는 넓은 질문에서는 따로 재 보세요.
• 코드만 다룰 때는 --code-only와 GRAPHIFY_BACKEND=none으로 네트워크 없이 9.8초 만에 그래프가 만들어졌어요. 문서·이미지까지 넣으면 API 키가 있는 LLM을 부를 수 있으니, 코드가 밖으로 나가면 안 되는 환경에서는 이 두 설정을 먼저 켜 두세요.