shev가 메시지를 한 번에 판단해 JSON으로 저장한다

shev 저장소

shev는 과장 없이 메시지를 판단하는 간단한 Jev 유사 도구다. 이메일, 티켓, 리뷰, 문서 등 메시지 전체를 입력하고 원하는 작업을 말하면 JSON으로 결정 하나를 반환한다.

{
 "actionable": "Reply to Sam and cc finance about the overdue March invoice.",
 "take_action": true,
 "confidence": 95,
 "generated_response": "Hi Sam, ... (the reply, written out)"
}

메시지를 문단이나 줄 단위로 나누지 않고 한 번에 판단한다. 사용자가 원하는 작업을 먼저 받아 그 의도에 맞는 답변을 작성한다. 결과는 actionable 문자열, take_action 불리언, [34, 100] 범위의 정수 confidence로 정해진 형식을 따른다. JSON 결정은 responses.json에 response1, response2 등의 항목으로 누적되며, 다른 모델은 MCP를 통해 읽을 수 있다.

설치와 시작

macOS와 Linux에서는 다음 명령으로 설치할 수 있다.

curl -fsSL https://raw.githubusercontent.com/aditauqir/shev/main/install.sh | bash

설치 후 shev를 입력한다. 설치 프로그램은 가능하면 PATH에 이미 포함된 사용자 바이너리 디렉터리를 사용한다. 그렇지 않으면 셸 프로필에 제거할 수 있는 PATH 설정을 추가한다. 새 터미널을 열면 별도 셸 편집 없이 shev를 실행할 수 있다.

npm을 사용할 경우 패키지 이름은 @noorslvt/shev다. npm 레지스트리의 범위 없는 이름 shev는 관련 없는 프로젝트가 사용하므로 이 도구를 설치할 때 npm install -g shev를 실행하면 안 된다.

npm install -g @noorslvt/shev
shev

저장소에서 직접 설치할 수도 있다.

npm install -g git+https://github.com/aditauqir/shev.git

두 설치 방식은 적합한 사전 빌드 릴리스를 우선 사용하고, 없으면 Rust로 빌드한다. 필요한 경우 최소 Rust 툴체인을 설치한다. npm 설치는 postinstall 단계에서 알맞은 바이너리를 가져오거나 빌드한다. npm 실행기는 macOS와 Linux를 지원하며, Windows에서는 WSL을 사용할 수 있다.

최근 npm 릴리스에서 설치 스크립트가 차단돼 설치가 건너뛰면 shev가 실행할 명령을 알려준다. 미리 승인하려면 다음 명령을 쓸 수 있다.

# if npm blocked the install scripts:
npm approve-scripts @noorslvt/shev # or:
npm rebuild -g @noorslvt/shev --foreground-scripts

Rust가 설치돼 있다면 저장소에서 바로 설치할 수 있다.

cargo install --git https://github.com/aditauqir/shev

요구 사항과 빠른 사용

로컬 모델 사용에는 Apple Silicon 기반 Mac(M1 이상)과 16GB 이상의 RAM이 가장 적합하다. 8GB에서도 로컬 모델을 사용할 수 있지만 여유가 적다. 그 밖의 환경에서는 DeepSeek API 키를 사용하면 되며 Mac은 필요하지 않다. 로컬 모델은 MLX를 사용해 Apple Silicon에서만 실행된다. DeepSeek 키를 설정하면 요청은 네트워크를 통해 처리되며 Rust가 지원되는 플랫폼에서 빌드하고 실행할 수 있다.

기본 모델은 Bonsai다. 필요하면 /model에서 설치할 수 있으며 API 키가 필요하지 않다. DeepSeek는 /model에서 선택하는 선택적 모델이다. 키는 ~/.config/shev/config.json에 권한 0600으로 저장된다.

실행한 뒤 메시지를 입력하거나 붙여 넣고 Enter를 누른다. 여러 줄 메시지의 중간에 줄을 바꾸려면 Ctrl+J를 누른다. 이어서 원하는 작업을 말한다. 예를 들어 “짧은 답장 초안을 써 줘”, “오늘 처리해야 하나”, “위험 요소가 어디 있나”처럼 입력할 수 있다. 결과를 확인한 뒤 Enter를 누르면 다음 판단을 시작한다. ▸ open responses.json in Finder를 선택해 파일을 열 수도 있다.

터미널 화면과 명령

첫 화면에는 배경 사진 위에 흰색 ASCII 워드마크가 표시되며 배경 상자나 JSON 창은 없다. 대화가 시작되면 왼쪽 창에 모델 출력과 결정 필드가 표시되고, 아래쪽에는 입력창과 모드 정보가 놓인다. 오른쪽에는 현재 차례의 JSON 원문만 표시된다. JSON을 마우스로 드래그해 선택하면 놓는 순간 선택 내용이 클립보드에 복사되고 화면 위쪽 가운데에 ✓ copied to clipboard가 표시된다. 마우스 휠로 JSON 창을 따로 스크롤할 수 있다. /copy json은 화면 밖에 있는 텍스트까지 포함해 전체 레코드를 복사한다.

텍스트 패널은 어두워진 배경 사진 위에 #0F0E08 색으로 표시된다. /를 입력하면 명령을 확인할 수 있다. 패널은 터미널 가장자리에서 안쪽으로 들어와 있으며, 스킬·도구 메뉴에는 이름만 표시된다. 긴 메뉴는 선택 항목 주변으로 스크롤해 항목이 화면 밖에서 잘리지 않게 한다.

Enter는 메시지를 보낸 뒤 의도를 입력하는 데 사용하고, Ctrl+J는 입력창에서 줄을 바꾼다. Ctrl+T는 DeepSeek와 Bonsai 사이에서 모델을 바꾼다. Ctrl+H는 /history와 같은 기록 화면을 연다. 기록 화면에서 Ctrl+D를 누르면 선택한 항목만 삭제하도록 확인한다. Ctrl+Y는 선택한 JSON이나 마지막 생성 응답을 복사하며 Ctrl+C는 종료한다.

/clear는 새 대화 화면을 시작하지만 /history에서 보관된 기록을 다시 열 수 있다. /reset과 기록 삭제는 확인 메뉴에서 기본적으로 취소 상태로 시작한다. 변경을 확정하면 응답 파일도 갱신되므로 MCP 클라이언트에 반영된다.

모델과 로컬 실행

/model에서 두 백엔드 사이를 전환하고 각 모델을 관리할 수 있다. DeepSeek는 명시적으로 선택하는 원격 모델이며 API 키가 필요하다. 메뉴에서 새 키 입력, 저장된 키 삭제, 취소를 선택할 수 있다.

기본 모델인 Bonsai는 prism-ml/Ternary-Bonsai-2-2B-mlx-2bit이며 MLX를 통해 Apple Silicon에서 실행되는 소형 3진 모델이다. 인터넷에서 약 1.2GB를 내려받아 ~/.local/share/shev/models에 설치하거나 제거할 수 있다.

Bonsai 팩은 자체 로더를 포함한다. 가중치가 일반 mlx-lm이나 mlx-vlm으로는 로드되지 않으며, 이들 도구는 Unsupported model type: prism_hadamard_qwen35라고 보고한다. 따라서 shev는 팩에 포함된 런타임을 상주 워커에서 사용하며, 고정된 요구 사항은 uv로 관리한다. 같은 세션의 반복 요청은 이미 로드한 모델을 재사용하고, 대체 수단으로 일회성 로더도 둔다. 포트에서 대기하는 서버는 없다. 첫 로컬 요청에서는 MLX 스택을 uv 환경에 설치하며 몇 분이 걸릴 수 있다.

출력 헤드 실험

이 팩은 출력을 language_model.model.embed_tokens.as_linear에 연결하며 별도의 language_model.lm_head는 없다. 기본 2비트 연산에는 팩의 Hadamard 변환이 필요하므로 bits 매개변수만 바꾸는 것은 올바른 변환이 아니다.

tools/bench-bonsai-head.py는 입력 임베딩과 설치 파일을 건드리지 않은 채 메모리에서 기본 2비트 출력 헤드와 올바르게 재패킹한 4비트 출력 헤드를 비교한다. 로컬 shev 요청을 한 번 실행해 ~/.local/share/shev/models/shev_bonsai_worker.py를 만든 뒤, 팩의 runtime/requirements.txt를 사용해 실행한다.

uv run --python 3.12 --with-requirements \
 ~/.local/share/shev/models/Ternary-Bonsai-2-2B-mlx-2bit/runtime/requirements.txt \
 python tools/bench-bonsai-head.py

현재 결정론적 프롬프트를 사용한 한 차례 로컬 실행에서는 기본 2비트가 헤드당 1.55ms, 판단당 669ms였고, 재패킹한 4비트는 헤드당 2.29ms, 판단당 734ms였다. 소규모 스모크 테스트에서 두 방식 모두 행동 라벨 6개 중 6개를 맞혔다. 이전 프롬프트·샘플링 기준선은 6개 중 3개였다. 이 결과는 일반적인 정확도를 입증하지 않으며, 개선은 재패킹이 아니라 프롬프트와 샘플링 변경에서 나왔다. 재패킹으로 2비트 체크포인트에서 이미 손실된 정밀도를 복구할 수 없다. 따라서 기본값은 계속 2비트다. 하드웨어, 프롬프트, 출력 길이에 따라 시간은 달라지며, 기존에 명시적으로 선택한 제공자 설정은 유지된다.

OpenCode·Codex에서 MCP 사용

shev의 MCP 서버는 다른 어시스턴트가 저장된 결정을 읽게 한다. Bonsai나 DeepSeek를 실행하거나 파일을 수정하지 않는다. API 키, OAuth 로그인, 터미널, 네트워크 포트, 별도로 실행한 TUI도 필요하지 않다. MCP 호스트가 shev를 하위 프로세스로 시작하고 표준 입력·출력으로 JSON-RPC를 주고받는다.

먼저 명시적인 파일 경로로 판단을 하나 이상 저장한다.

shev --file "$HOME/shev-responses.json"

TUI에서 /mcp install을 실행하거나 /mcp 메뉴에서 설치를 선택한다. 그러면 ~/.config/shev/mcp/에 설명 파일을 기록하고 기존 전역 OpenCode 설정에 실행 파일과 절대 기록 경로를 등록하며, 설정의 비공개 백업을 만든다. /mcp status는 등록 상태를 보여 준다. /mcp uninstall은 변경되지 않은 shev 등록만 제거하며 결정 기록은 삭제하지 않는다.

OpenCode에서는 설치 후 /mcps에서 shev에 다시 연결하거나 클라이언트를 재시작한다. 또는 셸에서 직접 등록할 수 있다. 소스에서 빌드했다면 실행 파일 경로를 바꾼다.

opencode mcp add shev --global -- "$HOME/.local/bin/shev" --mcp --file "$HOME/shev-responses.json"
opencode mcp list

OpenCode V2 설정은 다음과 같다.

{
 "mcp": {
 "servers": {
 "shev": {
 "type": "local",
 "command": ["/absolute/path/to/shev", "--mcp", "--file", "/absolute/path/to/responses.json"],
 "enabled": true
 }
 }
}

Codex에서는 경로를 바꿔 ~/.codex/config.toml 또는 CODEX_HOME의 설정에 다음을 추가한다. Codex를 재시작한 뒤 codex mcp list로 확인한다.

[mcp_servers.shev]
command = "/absolute/path/to/shev"
args = ["--mcp", "--file", "/absolute/path/to/responses.json"]

shev --mcp와 shev-cli --mcp를 모두 사용할 수 있다. 소스 빌드에서는 cargo build --release를 실행한 뒤 /absolute/path/to/repository/target/release/shev를 지정한다. JSON이나 TOML 명령 배열 안에 $(pwd) 같은 셸 표현식을 넣으면 안 된다.

연결한 OpenCode나 Codex에 shev의 latest_decision 도구로 가장 최근 판단을 요약해 달라고 하거나, search_decisions에 invoice 검색어와 10의 제한을 주도록 요청할 수 있다. get_decision으로 response2를 읽도록 요청하는 것도 가능하다.

리소스는 전체 기록을 제공하는 shev://decisions와 최신 기록을 제공하는 shev://decisions/latest다. 읽을 때마다 파일을 새로 확인하므로 실행 중인 TUI에서 저장한 결정도 MCP 프로세스를 다시 시작하지 않고 이용할 수 있다.

unknown option --mcp 오류가 나면 호스트가 오래된 TUI 바이너리를 실행 중인 것이다. MCP 명령에 지정한 실행 파일을 업데이트하거나 다시 빌드한 뒤 shev에 재연결한다. 현재 릴리스는 터미널을 설정하기 전에 --mcp를 처리한다. 연결은 됐지만 결정이 보이지 않으면 호스트와 TUI가 같은 절대 기록 경로를 쓰는지 확인한다. shev --mcp를 직접 실행했을 때 조용히 프로토콜 입력을 기다리는 것은 정상이며 멈춘 대화창이 아니다.

기존 스킬과 도구 재사용

/skills는 Codex, Claude, 공유 ~/.agents/skills, ~/skills, OpenCode의 XDG 설정 디렉터리, 상위 프로젝트의 .opencode, .agents, .codex 스킬 폴더에서 기존 SKILL.md 파일을 읽는다. OpenCode에 설정된 로컬 스킬 디렉터리도 확인한다. 안내를 메모리에 불러올 뿐 스킬 스크립트를 설치·수정·실행하지 않는다.

/tools는 Codex의 config.toml과 OpenCode의 전역·프로젝트 JSON 또는 JSONC 설정에서 MCP 등록을 읽는다. V2의 mcp.servers도 포함하며 CODEX_HOME과 XDG_CONFIG_HOME을 따른다. 서버를 선택하면 연결해 도구 목록을 표시한다. 도구를 고르면 인수 스키마를 보여 주고 /tool server/tool {}를 준비한다. 인수를 수정한 뒤 Enter를 눌러 호출한다. 성공한 결과는 다음 판단의 참조 문맥이 되며 /skills off로 이를 해제할 수 있다. 보조 문맥은 기록에 저장된 사용자의 원래 의도를 대체하지 않는다.

readOnlyHint: true이면서 destructiveHint: true가 아닌 도구만 호출할 수 있다. 알 수 없거나 변경을 일으킬 수 있는 도구는 조용히 승인하지 않고 차단한다. MCP 주석은 신뢰하는 서버가 제공하는 선언이지 보안 샌드박스가 아니다. 신뢰하는 서버만 사용해야 한다. 설정된 서버를 시작하면 시작 코드가 실행될 수 있다. 도구 호출에는 시간과 출력 제한이 있으며 샘플링이나 승인을 요청할 수 없다.

표준 입출력과 스트리머블 HTTP(JSON/SSE)를 지원한다. 설정된 헤더와 환경 변수 토큰은 로그에 기록하지 않고 재사용하지만 호스트가 관리하는 OAuth 자격 증명은 복사하지 않는다. OAuth만 사용하는 서버는 연결 성공으로 가장하지 않고 인증이 필요하다고 알린다.

오른쪽 패널 위쪽에는 불러온 스킬이나 성공적으로 호출한 도구와 출처가 표시된다. 통합 식별 정보도 결정과 함께 저장된다. 서버를 발견하거나 선택하는 것만으로는 도구 호출 성공으로 기록되지 않는다.

OpenCode에 설정된 JavaScript 플러그인은 호환성 안내와 함께 표시된다. 호스트 전용 플러그인은 자체 호스트 런타임이 필요해 shev에서 직접 실행할 수 없다. 등록된 MCP 인터페이스가 있다면 /tools로 사용할 수 있다. 검색이나 도구 사용 과정에서 shev가 호스트 설정을 다시 쓰지는 않는다. /mcp install은 별도 명령이며 등록 전에 설정을 백업한다.

명령줄 사용

TUI는 대화형 시작 화면이고, 파이프 입력용 줄 단위 CLI는 shev-cli다.

echo "Your invoice is 30 days overdue." | shev-cli -i "draft a polite reminder"
shev-cli "Should I ship this today?" -i "answer yes or no and why"
shev-cli --mcp # serve decisions over MCP on stdio

-c 또는 --once <message>는 메시지 하나를 판단한 뒤 종료한다. -i 또는 --intent <text>는 원하는 작업을 지정한다. -f 또는 --file <path>는 판단을 추가할 파일을 정하며 기본값은 responses.json이다. --mcp는 표준 입출력으로 기록된 판단을 MCP에 제공한다.

사용할 수 있는 환경 변수는 DEEPSEEK_API_KEY(저장된 키 대신 사용), SHEV_RESPONSES_FILE(판단을 추가할 위치), SHEV_INTENT(비대화형 실행의 기본 의도), SHEV_MODELS_DIR(로컬 모델 위치), SHEV_HOME(npm 실행기가 자동으로 설정하는 관리 상태 경로), SHEV_BONSAI_MAX_TOKENS(로컬 워커 토큰 제한, 기본 256, 초기화가 차가운 대체 실행에서는 2048), SHEV_BONSAI_STREAM(1이면 워커가 토큰 단위 변경 프로토콜 메시지를 사용), SHEV_BONSAI_TEMPERATURE(로컬 샘플링 온도, 기본 0으로 결정론적)다.

화면 하단에는 토큰 사용량과 마지막 판단에 걸린 시간이 표시된다. 상주 워커는 실제 로컬 토큰 수를 보고한다. 초기화가 차가운 대체 실행에는 사용량 메타데이터가 없어 추정하지 않고 0으로 표시한다. 간결한 요약과 생성된 답변도 JSON과 함께 남는다. 측정한 워밍 상태 실행은 약 750ms였고 모델 초기화를 포함하면 약 2500ms였다. 이는 Jev의 100ms 미만 지연 시간을 달성했다는 주장이 아니다.

로컬 판단의 형식이 잘못되면 형식을 고치도록 최대 두 번 다시 요청한다. 재시도 횟수는 사용량에 포함된다. 재시도는 지연을 늘릴 수 있고, 그래도 실패할 수 있다. 이 경우 유효하지 않은 JSON을 조용히 기록하지 않는다.

데이터 위치와 삭제

~/.config/shev/config.json에는 API 키와 선택한 모델이 권한 0600으로 저장된다. responses.json에는 response1, response2 등의 결정이 추가된다. 내려받은 로컬 모델은 ~/.local/share/shev/models/에 둔다. ~/.config/shev/install.json에는 설치 프로그램이 관리하는 바이너리·PATH 설정과 범위 지정 정리를 위한 기록 경로가 저장된다.

npm 실행기는 기본 설정, 기록 파일, 모델을 위 경로 대신 ~/.local/share/shev-npm/state/ 또는 $XDG_DATA_HOME/shev-npm/state/ 아래에 분리해 보관한다. 이 데이터는 npm 업그레이드 후에도 유지된다. 셸 및 MCP 통합은 자격 증명을 복사하지 않은 채 기존 호스트 설정을 읽는다. 명시적으로 지정한 --file이나 SHEV_RESPONSES_FILE 경로는 선택한 위치에 남으며 shev --uninstall을 명시적으로 실행할 때 정리 대상에 기록된다.

curl이나 npm으로 설치한 shev를 완전히 정리하려면 먼저 실행 중인 다른 shev 세션을 닫는다. 미리보기는 파일을 삭제하지 않는다.

shev --uninstall --dry-run # preview paths; delete nothing
shev --uninstall # confirm before removal
# or: shev --uninstall --yes

이 명령은 등록된 shev 바이너리, 저장된 키와 설정, 로컬 모델 데이터, 추적 중인 대화 기록, 변경되지 않은 shev MCP 등록, 설치 프로그램이 추가한 정확한 PATH 블록을 제거한다. npm을 통해 설치한 경우 전체 삭제 과정에서 npm 패키지도 제거한다.

수정된 바이너리나 프로필 블록, 외부에서 관리하는 가중치, 호스트 복구 백업, 관련 없는 호스트 설정, 내보내기 파일의 비대화형 메타데이터, 소스 체크아웃, Rust·Node·uv·Codex·OpenCode 같은 공유 도구와 캐시는 삭제하지 않는다.

npm 패키지만 직접 삭제할 수도 있다.

npm uninstall -g @noorslvt/shev

이 명령은 npm 패키지와 바이너리를 제거한다. 최신 npm은 제거 훅을 실행하지 않으므로 지속 설정·모델·기록이나 외부 MCP 등록까지 삭제할 수 없다. 완전히 정리하려면 shev --uninstall을 사용한다. 이 명령은 npm 패키지도 제거한다. npm 업그레이드가 비공개 키, 기록, 모델 다운로드를 지우지 않도록 npm 데이터는 패키지 바깥에 둔다. 백그라운드 제거 감시자나 npm 재정의는 설치하지 않는다.

라이선스는 Apache-2.0이며 저장소의 LICENSE에서 확인할 수 있다.