Sleuther: Ollama 기반 Oh My Zsh용 로컬 터미널 에러 분석 도구

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

터미널에서 발생하는 복잡한 에러 메시지를 해석하기 위해 브라우저를 검색하는 번거로움을 해결하기 위해 Sleuther가 개발됐다. 이 도구는 zsh 훅을 통해 실패한 명령어를 감지하고, 해당 컨텍스트를 로컬 Ollama 서버에 전달하여 에러의 근본 원인과 수정 방안을 출력한다. 기본 모델로 qwen2.5-coder:7b를 사용하며, 모든 처리가 로컬에서 이루어져 데이터 프라이버시를 보장한다. 개발자는 터미널을 떠나지 않고도 즉각적인 에러 진단과 안전한 수정 명령어를 제안받아 생산성을 높일 수 있다.

배경

Oh My Zsh, Ollama, Python 3, curl

대상 독자

Oh My Zsh를 사용하는 개발자 및 로컬 LLM 활용에 관심 있는 엔지니어

의미 / 영향

이 도구는 클라우드 기반 AI 서비스의 개인정보 유출 우려를 해소하면서도 개발 생산성을 높이는 로컬 AI 에이전트의 실용적인 사례를 보여준다. 특히 보안이 엄격한 환경에서 작업하는 개발자들에게 유용한 대안이 될 수 있다.

섹션별 상세

터미널 명령어 실패 시 수동으로 원인을 파악해야 하는 기존 방식은 흐름을 끊는 병목 현상을 초래한다. Sleuther는 zsh 훅을 사용하여 종료 코드가 0이 아닌 명령어를 자동으로 포착하고 로컬 Ollama 인스턴스에 분석을 요청한다. 내부적으로 qwen2.5-coder:7b 모델을 호출하여 에러의 근본 원인과 해결책을 구조화된 텍스트로 렌더링한다. 이를 통해 개발자는 에러 발생 즉시 맥락에 맞는 진단 결과를 터미널 내에서 확인할 수 있다.

Sleuther가 터미널 에러를 감지하고 분석 결과를 출력하는 데모 애니메이션이다. — Screenshot실제 터미널 환경에서 에러가 발생했을 때 Sleuther가 어떻게 원인(Root Cause)과 해결책(Fix)을 시각적으로 렌더링하는지 보여준다. 사용자가 제안된 명령어를 확인하고 승인하는 과정을 직관적으로 파악할 수 있다.

민감한 터미널 데이터가 외부 클라우드로 유출되는 보안 위협을 방지하기 위해 로컬 우선 아키텍처를 채택했다. 모든 API 요청은 localhost:11434로 제한되며, 외부 URL 설정 시 자동으로 로컬 주소로 리셋되는 강제 로직이 포함됐다. 또한 제안된 명령어는 eval 대신 zsh 파싱을 통해 토큰 단위로 실행되며, 파괴적이거나 네트워크 지향적인 명령어는 실행 가드에 의해 차단된다. 보안이 중요한 기업 환경에서도 AI의 도움을 안전하게 받을 수 있는 구조를 갖췄다.

자동 감지 모드에서 캡처하지 못하는 상세한 에러 로그는 수동 모드를 통해 보완할 수 있다. zsh 훅은 표준 출력(stdout)이나 표준 에러(stderr)를 직접 노출하지 않으므로, 사용자가 직접 에러 메시지를 인자로 전달하는 manual path를 제공한다. 수동 모드에서는 더 풍부한 컨텍스트가 모델에 전달되어 정확도 높은 해결책을 도출할 수 있다. 상황에 따라 자동과 수동 모드를 선택적으로 활용하여 다양한 CLI 환경 문제를 해결할 수 있다.

bash

git clone https://github.com/chocks/sleuther \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/sleuther

# ~/.zshrc의 plugins 리스트에 sleuther 추가 후
ollama pull qwen2.5-coder:7b
source ~/.zshrc

Sleuther 플러그인 설치 및 기본 모델 다운로드 과정

bash

SLEUTHER_MODEL="qwen2.5-coder:7b"
SLEUTHER_AUTO_RUN=false
SLEUTHER_OLLAMA_URL="http://localhost:11434"
SLEUTHER_TIMEOUT=30
SLEUTHER_KEEP_ALIVE="10m"

Sleuther의 주요 설정 파일 구성 예시

실무 Takeaway

로컬 Ollama를 활용하여 터미널 에러 데이터를 외부로 유출하지 않고 안전하게 분석할 수 있다.
zsh hooks 기반의 자동 모드에서 해결되지 않는 복잡한 에러는 sleuther 명령어에 에러 메시지를 직접 전달하는 수동 모드로 해결 가능하다.
보안을 위해 SLEUTHER_AUTO_RUN 옵션을 비활성화하고 제안된 명령어를 실행 전 반드시 검토하는 습관이 필요하다.

언급된 리소스

GitHubsleuther GitHub Repository