본문으로 건너뛰기
Hacker News - LLM조회 3회

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

Sleuther는 Ollama를 사용하여 Oh My Zsh 터미널에서 발생하는 명령어 오류의 원인을 로컬에서 분석하고 안전한 해결 명령어를 제안하는 도구입니다.

섹션별 상세

01
터미널 명령어 실패 시 수동으로 원인을 파악해야 하는 기존 방식은 흐름을 끊는 병목 현상을 초래한다. Sleuther는 zsh 훅을 사용하여 종료 코드가 0이 아닌 명령어를 자동으로 포착하고 로컬 Ollama 인스턴스에 분석을 요청한다. 내부적으로 qwen2.5-coder:7b 모델을 호출하여 에러의 근본 원인과 해결책을 구조화된 텍스트로 렌더링한다. 이를 통해 개발자는 에러 발생 즉시 맥락에 맞는 진단 결과를 터미널 내에서 확인할 수 있다.
Sleuther가 터미널 에러를 감지하고 분석 결과를 출력하는 데모 애니메이션이다.
Screenshot실제 터미널 환경에서 에러가 발생했을 때 Sleuther가 어떻게 원인(Root Cause)과 해결책(Fix)을 시각적으로 렌더링하는지 보여준다. 사용자가 제안된 명령어를 확인하고 승인하는 과정을 직관적으로 파악할 수 있다.
02
민감한 터미널 데이터가 외부 클라우드로 유출되는 보안 위협을 방지하기 위해 로컬 우선 아키텍처를 채택했다. 모든 API 요청은 localhost:11434로 제한되며, 외부 URL 설정 시 자동으로 로컬 주소로 리셋되는 강제 로직이 포함됐다. 또한 제안된 명령어는 eval 대신 zsh 파싱을 통해 토큰 단위로 실행되며, 파괴적이거나 네트워크 지향적인 명령어는 실행 가드에 의해 차단된다. 보안이 중요한 기업 환경에서도 AI의 도움을 안전하게 받을 수 있는 구조를 갖췄다.
03
자동 감지 모드에서 캡처하지 못하는 상세한 에러 로그는 수동 모드를 통해 보완할 수 있다. 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의 주요 설정 파일 구성 예시

용어 해설

Zsh 훅(Zsh Hooks)
— Zsh 쉘에서 특정 이벤트(명령어 실행 전후 등)가 발생할 때 자동으로 실행되는 함수나 스크립트 메커니즘이다. Sleuther는 이를 통해 명령어가 실패한 시점을 감지하고 즉시 분석 프로세스를 시작한다.
종료 코드(Exit Code)
— 프로세스가 종료될 때 운영체제에 전달하는 정수 값이다. 0은 성공을 의미하며, 그 외의 값은 오류를 나타낸다. Sleuther는 이 코드를 LLM에 전달하여 어떤 유형의 오류가 발생했는지 판단하는 근거로 활용한다.
루프백 주소(Loopback Address)
— 자기 자신을 가리키는 네트워크 주소(127.0.0.1)이다. Sleuther는 보안을 위해 Ollama API 엔드포인트를 루프백 주소로 강제 제한하여, 터미널 데이터가 외부 네트워크로 유출되는 것을 원천 차단한다.
데이터 정제(Sanitization)
— 데이터에서 개인정보나 민감한 정보를 식별하여 제거하거나 마스킹 처리하는 보안 프로세스이다. Sleuther는 보고서 생성 시 사용자 이름, IP 주소, 비밀번호 패턴 등을 자동으로 삭제하여 외부 공유 시의 위험을 줄인다.

기술

  • Ollama
  • qwen2.5-coder:7b
  • Zsh
  • Python

활용 사례

  • 터미널 명령어 오류 분석
  • CLI 환경 문제 해결 가이드
  • 로컬 AI 에이전트

언급된 리소스

AI 분석 전체 내용 보기

AI 요약 · 북마크 · 개인 피드 설정 — 무료

출처 · 인용 안내

원문 발행 2026. 03. 24.수집 2026. 03. 24.출처 타입 RSS

인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.