claude-jev

작은 판단에 대해 프론티어 모델 가격을 지불하는 것을 멈추세요.

코딩 에이전트는 매 턴 수십 번의 빠른 호출을 합니다. 이 프롬프트는 어떤 종류인가요? 도구가 필요한가요? 이 수정 사항은 CLAUDE.md의 규칙을 위반하나요? 컨텍스트가 가득 찼을 때 어떤 턴들이 여전히 중요한가요? 이 플러그인은 이러한 질문들을 TypeSafe's Jev로 보냅니다. Jev는 System One 모델입니다: 텍스트가 아닌 타입이 지정된 답변을 반환하며, 코드를 작성하지 않습니다.

얻게 되는 것:

• 유지되는 규칙. 지침 파일을 위반하는 수정 사항은 파일:라인 인용과 함께 차단됩니다. v0.23.0에서 동일한 247개의 승인된 수정 사항을 재점수화했을 때 23개(9.3%)가 차단되었고, v0.21.0 실행에서는 22개(8.9%), 단일 리포지토리의 자체 댓글 금지 규칙에 따라서는 17개가 차단되었습니다.
• 분 단위가 아닌 약 1초 만에 압축. Jev는 요약문을 작성하는 대신 중요한 정확한 행들을 유지합니다. 심은 사용자 제약 조건들은 100%의 시간 동안 생존했습니다.
• 적절한 크기의 서브 에이전트. 각 생성(spawn)에는 모델 티어가 부여됩니다. 파일은 변경하지만 경로, 승인 기준, 검증 또는 커밋 정책을 누락한 간략 보고서가 한 번 전송됩니다.
• 라우팅 힌트. 각 프롬프트는

Pi는 package.json의 pi.extensions 필드에서 adapters/pi/jev.ts를 로드합니다. 이 파일은 session_before_compact 훅과 /jev 명령을 담당합니다. TYPESAFE_API_KEY나 OPENROUTER_API_KEY가 없으면 훅은 아무것도 반환하지 않고 Pi가 자체 요약을 작성합니다. 동일한 두 변수는 먼저 환경에서 읽어온 다음, $PI_CODING_AGENT_DIR/.env (~/.pi/agent/.env)에서 읽어옵니다. JEV_PROVIDER는 typesafe 또는 openrouter로 고정(pin)됩니다. JEV_MODEL은 기본값으로 jev-latest를 사용합니다.

이 훅은 src/compact/strategy.ts에서 selectBlocks를 사용하여 판단합니다. Pi 전용 조각들은 어댑터에 남아 있습니다: 즉, Pi 메시지가 블록이 되는 방식, toolCallId를 통해 도구 결과를 호출에 페어링하는 방식, bash 출력을 재레이블링하고 이전 요약들을 처리하며, <read-files>와 <modified-files> 목록을 요약이 모델에게 보여줍니다. 보존된 블록들은 14,000자 크기에 맞게 조정됩니다. 버려지거나 잘린 호출의 경로는 여기에 2,000자를 더 사용할 수 있습니다. Pi 자체의 읽기 경로와 <modified-files>는 이 할당량 밖에 위치합니다. Claude의 압축 예산은 여전히 단일한 16,000자입니다. 0x7067/pi-jev는 유지되며, 이 레포지토리는 아직 그 설치를 대체하지 않습니다.

키 및 제공업체(Keys and providers)

• 두 변수가 모두 설정된 경우, 플러그인은 TYPESAFE_API_KEY를 먼저 읽습니다.
• 두 변수 중 어느 쪽이든 sk-or-로 시작하는 키는 모든 호출을 api.typesafe.ai 대신 OpenRouter의 System One API로 전송합니다.
• 두 변수가 모두 설정된 상태에서 OpenRouter를 사용하려면, /claude-jev 또는 /config의 Provider 행에서 선택해야 합니다. 고정된 제공업체는 자신의 변수만 읽습니다.

function-hooks 플래그

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS는 Claude Code가 자체적으로 사용하는 실험적인 함수 훅(function hooks) 스위치입니다. 기본적으로 비활성화되어 있으며 문서화되어 있지 않습니다. docs/claude-code-compaction-research.md에 검증된 내용이 기록되어 있습니다. 함수 훅 모듈은 신뢰할 수 있는 작업 공간에서만 로드되며, 서브 에이전트(subagents)를 위해서는 절대 로드되지 않습니다.

자동 압축(auto-compact)을 켜 놓으세요. 이는 /config의 자동 압축 행이며, ~/.claude/settings.json에서 autoCompactEnabled로 저장됩니다. 이 플래그를 설정하면, 자동 압축은 /compact가 수행하는 방식과 같이 Jev를 통해 진행됩니다. 자동 압축이 꺼져 있으면, 세션은 컨텍스트 제한에 도달할 때까지 실행되며, 그 후에는 직접 /compact를 실행해야 합니다.

/claude-jev 패널

플래그가 설정되면, /claude-jev는 설정 패널을 엽니다. 이 패널을 사용하여 다음 작업을 수행할 수 있습니다:

• 모든 세션을 위한 API 키 저장 (실행 환경의 키가 저장된 키보다 우선합니다)
• 제공업체 선택
• 각 후크(hook) 켜기 또는 끄기
• 마지막 Jev 호출 확인
• 통계(Stats) 행 읽기: scripts/stats.py는 라우터 힌트, 세션이 수행한 작업, 규칙 보정 및 압축에 대한 보고서를 제공합니다.

플래그가 없으면, 네 개의 켜기/끄기 행은 /config에 있습니다.

ast-grep (선택 사항)

규칙 후크의 비교기는 ast-grep 0.45.3을 사용합니다. 이것이 PATH에 없다면, 편집이 필요할 때 처음으로 분리된 프로세스가 해당 고정 릴리스를 ~/.claude/jev-bin에 가져와 sha256을 확인합니다. 모든 후크는 그것 없이도 작동합니다. 지금 가져오거나 실행될 바이너리를 보려면 다음 명령어를 사용하세요:

python3 scripts/comparators.py fetch
python3 scripts/comparators.py which

후크(The hooks)

규칙(Rules)

규칙은 사용자가 이미 가지고 있는 지침 파일에서 가져옵니다:

• CLAUDE.md 및 ~/.claude/CLAUDE.md
• 중첩된 AGENTS.md
• .claude/rules/* 및 .cursor/rules/*

컴파일할 필요가 없으며, 추가로 커밋되는 것도 없습니다.

규칙이 읽히는 방식

후크는 해시당 각 파일을 한 번 분류하고 결과를 ~/.claude 아래에 캐싱합니다. 각 규칙은 네 개의 필드를 갖습니다:

• 종류 (Kind): 작성된 코드에 대한 지침이거나, 사실, 포인터 또는 프로세스 규칙입니다.
• 범위 (Scope): 편집(edit) 단위별이거나, 전체 턴(turn) 단위입니다.
• 극성 (Polarity): 금지하거나 요구합니다. 규칙은 그 본문(괄호 바깥의 텍스트)에 명시되어 있는 경우에만 금지됩니다: 문장 시작이나 절 시작에서 never, no, avoid, don't 또는 do not이 있거나, must/should/shall/may 뒤에 not 또는 never가 오거나, forbidden, prohibited, banned, disallowed, not allowed라는 단어가 있는 경우입니다. Jev가 금지라고 부르는 설명(

1. 로컬에서 필터링합니다. 주제별로 저렴한 테스트를 수행하여 규칙이 깨뜨릴 수 없는 부분을 제거합니다. 예를 들어, 가져오기(import) 규칙은 아무 가져오기 라인도 건드리지 않는 편집에 대해서는 질문하지 않습니다. v0.21.0 실행에서는 필터가 범위 내 검사의 36%를 제거했으며, 중앙값 편집은 14개의 규칙을 포함했고 8가지 질문을 받았습니다.
2. ast-grep으로 컨텍스트를 조회합니다. 일부 위반 사항은 한 청크(hunk)에서 볼 수 없습니다. 세 가지 주제에 대해 저장소 전체에 결정론적 검색이 먼저 수행됩니다. 이 검색은 이미 편집된 리터럴 값을 담고 있는 상수, 양쪽 값이 동일한 단언(assertion), 그리고 오류 처리 방식이 변경된 함수의 호출자들을 찾아냅니다.
3. Jev에게 한 번 질문합니다. 배치 호출(batched call) 하나로 남은 각 규칙에 대해 예/아니오 질문을 합니다. Polarity가 질문을 선택합니다: 새로운 코드가 금지된 행위를 하는지, 아니면 규칙이 명확하게 다루지만 필요한 요소가 없는 경우의 케이스를 추가하는지에 대한 것입니다? Jev는 각각의 규칙이 깨졌을 확률로 점수를 매깁니다. 이전 코드→새로운 청크, 사용자의 마지막 프롬프트, 그리고 편집 주변의 라인을 확인합니다. 가져오기 규칙의 경우 파일 디렉터리의 형제 모듈(sibling modules)도 함께 확인합니다. 하나의 편집은 최대 40개의 질문을 받으며, 경로 범위 규칙이 먼저 처리되고 파일들이 순차적으로 진행됩니다.
4. 결정합니다. 점수가 0.80에 도달하면 후크가 편집을 차단하고 파일:라인을 인용합니다. 0.50 미만일 경우 아무것도 표시하지 않습니다.
5. 불확실한 것을 에스컬레이션(Escalate)합니다. 0.50과 0.80 사이의 규칙은 모든 그러한 규칙을 하나의 요청으로 받아 두 번째 호출을 받습니다. 이 호출은 편집 후 디스크에서 읽어온 포함하는 함수와 지침 파일 내의 규칙 주변 문장들을 추가합니다. 두 번째 답변이 결정합니다. 여전히 불확실한 것은 사용자에게만 플래그가 지정됩니다. 편집의 약 14%가 그 두 번째 호출에 대한 비용을 지불합니다.

ast-grep 바이너리는 sha256으로 고정되어 있으며 크기는 51 MB이고, 분리된 프로세스(detached process)에서 한 번 가져옵니다. 로딩이 완료되거나 무언가 실패할 때까지 모든 조회는 아무것도 반환하지 않습니다.

제한 사항 및 전체 트랜(whole-turn) 규칙

• 규칙은 루프에 빠지는 것을 막기 위해 세션당 동일 파일을 최대 두 번만 차단합니다. 나중에 해당 규칙과 파일에 대한 act-band 매치는 이미 제기되었음을 알리는 통지입니다. 에이전트에게 다시 알려주지 않습니다. flag-band 매치는 불확실성 통지로 유지됩니다. Calibration은 하나의 규칙의 act bar를 0.80에서 이동시킬 수 있습니다. Stop은 모든 턴 규칙에 걸쳐 세션당 최대 두 번만 차단합니다. 이 제한으로 인해 보류된 hit은 해당 세션이 이미 두 번의 턴 블록을 사용했음을 의미할 뿐, 그 규칙이 인용되었다는 것을 주장하지 않습니다.
• Vendored, 생성된(generated), 그리고 프로젝트 외부 경로(out-of-project paths)는 절대 판단되지 않습니다. 경로는 작업 디렉토리 위에서 해결되는 경우, 예를 들어 /tmp/x.mts와 같이 프로젝트 외에 있다고 간주됩니다.
• 전체 턴 규칙은 편집별 검사를 건너뜁니다. 예시: 최소 변경(minimal changes), 단일 호출자 추상화 없음(no single-caller abstraction), 관련 없는 리팩토링 없음(no unrelated refactoring). Stop 후크는 이러한 경우를 해당 턴의 모든 hunk에 대해 판단하며, 범위가 확장되는지(scope creep) 확인합니다.
• Stop은 최신 사용자 프롬프트 이후 생성된 hunk만 보고, 아무것도 없는 턴은 건너뜁니다.
• Bash 명령어 또한 계산됩니다. 이 후크는 각 명령어 전에 추적되지 않은 파일(untracked files)을 포함하여 git 작업 트리(git working tree)를 스냅샷하고, 그 후에 diff를 생성합니다. 예를 들어 git 저장소 외부에서 스냅샷에 실패하는 경우, Jev는 diff가 부분적이라고 통보받습니다.

압축 (Compaction)

hooks/register.ts는 session.compact 후크를 사용합니다. /compact, 자동 압축(auto-compaction), 그리고 /rewind 요약의 경우, 대화 내용을 Jev에게 행(rows) 형태로 전달합니다. Jev가 유지하는 행들이 전체 압축 후 컨텍스트가 됩니다. 어떠한 요약도 작성되지 않습니다. 압축은 30~60초 대신 1초 미만으로 소요됩니다. 이 플래그가 없으면, Claude Code는 항상 그랬던 것처럼 압축하고, 플러그인은 그 경로에 아무것도 추가하지 않습니다.

이 후크는 산문(prose)이 아닌 바이트를 유지합니다:

• Harness rows(슬래시 명령어 래퍼, 주의사항)와 한 단어 승인 응답은 로컬에서 삭제됩니다.
• 두 번째 줄마다 다섯 가지 예/아니오 확인이 이루어집니다. 사용자 제약 사항을 명시했습니까? 결정과 그 이유를 기록했습니까? 정확한 오류가 발생했습니까? 진행 중인 작업을 명명했습니까? 재실행 시 동일한 출력이 출력될까요?
• 코드는 이러한 답변들을 판결로 변환합니다. 점수 유지(keep score)는 네 가지 확인 중 가장 강력한 것입니다.
• 높은 제약 또는 오류 점수를 가진 줄은 원문 그대로 유지됩니다 — 단, 재실행 가능한 답변이 '예'인 경우, 재실행 시 다시 출력되므로 재실행 포인터가 달린 헤드가 전체 내용을 대체합니다. 다른 모든 유지된 줄은 잘린 헤드와 해당 내용을 다시 읽을 수 있는 포인터를 갖게 됩니다.
• 유지되는 일반 메시지는 바이트 단위로 동일하게 복원됩니다. 유지되는 도구 호출 및 결과는 텍스트로 복원됩니다. 점수가 매겨지지 않은 줄도 유지됩니다.
• 고정된 한 줄 헤더가 압축된 컨텍스트를 시작합니다. /compact 이후에 입력하는 모든 텍스트는 상태(state)에 이름이 부여되며, 모든 확인은 이를 참조합니다.

Jev는 다섯 가지 확인과 함께 가장 최신 150개 줄을, 그리고 그 이전의 150개 줄만 제약 사항 확인만을 통해 판단하므로, 긴 세션 초기에 명시된 요구사항도 Jev에게 전달됩니다. 유지되는 텍스트는 16k 문자로 제한되며, 신뢰도가 가장 낮은 내용부터 우선적으로 다운그레이드됩니다. Jev의 줄은 요약을 대체하며, 아무리 축소되더라도 그렇습니다. 키 누락, Jev 서비스 중단, 또는 브릿지(bridge) 오류가 발생했을 때만 내장된 요약으로 넘어갑니다.

어떤 경로로 실행되었는지 확인하려면 Claude Code를 -d 옵션과 함께 시작하고 압축 후 ~/.claude/debug/<세션-id>.txt 파일을 읽으세요:

• a hook's N messages stand (hooked by claude-jev); core never ran은 Jev의 줄이 요약을 대체했음을 의미합니다.
• jev-compact: ... built-in summary runs는 브릿지가 작동했으며, 해당 라인에 그 이유가 적혀 있음을 의미합니다.

라우팅(Routing)

프롬프트(Prompts)

각 프롬프트는 API 호출 한 번을 비용으로 합니다. 이는 의도, 범위, 그리고 도구 필요 여부를 요청합니다. 대부분의 프롬프트가 후속 조치이기 때문에, 이 호출에는 이전 턴이 포함됩니다.

• lookup은 '단일 검색(one search)'이라는 힌트를 받습니다.
• fix는 '집중 편집, 범위 제한 검증(focused edit, narrow verification)'을 받습니다.
• feature와 ops는 어떤 힌트도 받지 못합니다. 라이브 환경과 리플레이 환경 모두에서 이 힌트들은 맞는 것보다 틀린 경우가 더 많았습니다.
• 신뢰도가 0.75 미만일 경우, 라우터(router)는 침묵을 지킵니다.
• 도구 사용이 필요하지 않다는(no-tools) 힌트는 오직 거의 확실한 예/아니오 답변에서만 발동되는데, 이는 필요한 작업을 건너뛰는 것이 비용이 많이 드는 실수이기 때문입니다.

Subagents