Git Out: 개발자가 자유롭게 생각하도록 돕는 로컬 음성 비서

_이 글은 Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass 제출물입니다.

제가 만든 것 (What I Built)

Git Out은 화면에 붙어있지 않고도 기술적인 문제를 생각하고 싶은 개발자를 위한 로컬 우선(local-first) 음성 비서입니다.

아이디어는 간단합니다. 산책을 하면서 질문하고, 노트북을 열거나, 목소리를 클라우드 서비스로 보내거나, 수많은 탭에 사고의 흐름을 잃지 않으면서 유용한 답변을 얻는 것입니다.

Git Out은 걸어 다니거나, 통근하거나, 휴식을 취하거나, 책상에서 떨어진 곳에서 일하는 개발자를 위해 만들어졌습니다. 다음과 같은 질문들에 도움을 줄 수 있습니다:

“이 모듈을 리팩토링(refactor)하는 가장 안전한 방법은 무엇인가요?”
“이 풀 리퀘스트(pull request)는 어떻게 생각해야 할까요?”
“이 변경 사항에 어떤 Git 워크플로우를 사용해야 하나요?”

앱은 의도적으로 한 번의 명확한 음성 발화(voice turn)를 녹음하고, 안드로이드 기기에서 이를 전사(transcribe)하며, 로컬 Qwen 모델을 사용하여 답변을 생성하고, 설치된 안드로이드 음성으로 완성된 답변을 소리 내어 읽어줍니다.

스크린은 의도적으로 경험의 가장 짧은 부분입니다. 포켓 모드(Pocket Mode)는 Ready, Listening, Transcribing, Thinking, Speaking, Error에 대한 크고 대비가 높은 컨트롤과 명시적인 상태를 가지고 있습니다. 웨이크 워드(wake word)가 없으며, 항상 켜진 마이크도 없고, 백그라운드에서 자동 마이크 재시작 기능도 없습니다.

Git Out은 또한 선택적 읽기 전용 GitHub 작업 공간을 포함합니다. 백엔드가 구성되면 앱은 연결된 계정, 리포지토리(repositories), 할당된 이슈(assigned issues), 풀 리퀘스트(pull requests), 그리고 최근 커밋(recent commits)을 표시할 수 있습니다. GitHub 토큰은 서버에 보관되며 모바일 앱에 포함되지 않습니다.

데모 (Demo)

비디오 데모:

데모는 다음을 보여주어야 합니다:

Android 설정에서 Qwen GGUF 모델 로드.
포켓 모드를 시작하고 음성으로 질문하기.
화면에 표시되는 온디바이스(on-device) 녹취록.
로컬 답변이 생성되어 Android TTS를 통해 음성으로 출력됨.
답변이 재생되는 동안 휴대폰을 잠그거나 백그라운드로 전환함.
앱으로 돌아와서도 답변 내용이 읽기 가능함을 보여줌.
선택적으로 GitHub 탭을 열어 리포지토리 컨텍스트를 표시함.

이는 Android 개발 빌드이기 때문에, 짧은 화면 녹화가 가장 유용한 데모 형식입니다. 이 프로젝트는 설치된 음성 팩, TTS 목소리, 오디오 포커스(audio focus), 헤드셋 이벤트, 그리고 잠금 화면 동작이 기기마다 다르기 때문에 실제 Android 장치에서 테스트하도록 설계되었습니다.

코드

완전한 오픈 소스 프로젝트는 다음에서 확인할 수 있습니다:

GitHub의 Git Out

이 리포지토리에는 React Native/Expo 모바일 앱, FastAPI 백엔드, 로컬 AI 추상화 계층(abstraction), Android 음성 및 TTS 통합 기능, GitHub API 서비스, 테스트 코드, 그리고 설정 문서가 포함되어 있습니다.

구축 방법 (How I Built It)

Git Out은 Expo로 구축된 Android 우선 React Native 앱이며, 선택적 GitHub 작업 공간을 위해 작은 FastAPI 백엔드를 사용합니다.

로컬 AI

핵심 모델은 Qwen2.5-1.5B-Instruct Q4_K_M GGUF이며, llama.rn을 사용하여 Android 장치에 로드됩니다. 모델 파일은 사용자가 선택하여 로컬에 저장하며, 리포지토리에 번들링되거나 앱에 의해 자동으로 다운로드되지 않습니다.

모바일 대화 경로는 다음과 같습니다:

음성 질문
    ↓
Android 온디바이스 음성 인식
...

음성 입력 및 출력

expo-speech-recognition은 녹음 전에 설치된 Android 온디바이스 언어 팩을 확인합니다.
애플리케이션은 요청된 오프라인 언어가 사용 불가능할 경우 네트워크 인식으로 조용히 전환하는 것을 거부합니다.
수기로 작성된 GitOutTts Expo 모듈이 Android의 TextToSpeech를 감싸고 있습니다.
TTS 경로는 정확한 설치 음성 일치, 오디오 포커스, 헤드셋 제거, 중지/취소 동작 및 지원되는 미디어 세션 제어를 처리합니다.
스코프된 미디어 재생 포그라운드 서비스는 이미 시작된 답변이 말해지는 동안에만 사용됩니다. 마이크를 절대 시작하지 않습니다.

Pocket Mode

Pocket Mode는 지속적인 비서라기보다는 일회성 음성 워크플로우입니다. 각 탭은 하나의 질문을 시작하며, 수명이 보호되어 오래된 인식 또는 TTS 콜백이 실수로 두 번째 턴을 제출하는 것을 방지합니다.

상태 머신은 사용자가 이동 중일 때 상호 작용을 이해하기 쉽게 만듭니다:

Ready → Listening → Transcribing → Thinking → Speaking
                         ↘ Error

선택적 GitHub 작업 공간

FastAPI 서비스는 서버 전용 GITHUB_TOKEN과 GitHub의 REST API를 사용합니다. 이는 인증된 사용자, 저장소, 할당된 이슈, 풀 리퀘스트 및 커밋에 대한 정제된 읽기 엔드포인트를 노출합니다. 모바일 앱은 화이트리스트 처리된 응답 필드를만 받으며, 토큰을 절대 받지 않습니다.

GitHub는 의도적으로 로컬 추론과 분리되어 있습니다. 백엔드나 네트워크가 사용 불가능할 때에도 로컬 대화는 계속 작동합니다.

시각 디자인

애플리케이션은 어둡고 미니멀한 스큐어모픽 인터페이스를 사용합니다: 솟아오른 카드, 움푹 들어간 입력 창, 촉각 버튼, 은은한 그림자 및 명확한 상태 알약(status pills). 이는 무거운 UI 라이브러리나 이미지 에셋을 추가하지 않으면서 컨트롤에 물리적 장치 같은 느낌을 부여합니다.

Open Innovation이 왜 중요할까요?

Open innovation은 Git Out이 또 다른 클라우드 채팅 인터페이스가 되는 대신 'Touch Grass' 테마에 맞게 기능하도록 만드는 요소입니다.

오픈 웨이트(open-weight) Qwen 모델을 사용하면 메인 대화가 휴대폰에서 로컬로 실행될 수 있습니다.
이것은 여러 가지 중요한 기능을 가능하게 합니다:

오프라인 사용: 모델과 Android 음성/TTS 데이터가 설치되면, 사용자는 Wi-Fi나 모바일 데이터 없이 걸어 다닐 수 있습니다.
개인적인 음성 대화: 프롬프트, 스크립트, 답변이 로컬 AI 루프를 위해 기기를 벗어날 필요가 없습니다.
모델 제어: GGUF 모델은 사용자가 소유하는 파일이며, 호스팅된 API 주변으로 전체 제품을 재작성할 필요 없이 교체하거나 업그레이드할 수 있습니다.
요청당 의존성 없음: 핵심 경험이 유료 API 키나 공급업체의 가동 시간에 의존하지 않습니다.
검사 가능한 빌딩 블록: 이 앱은 오픈 웨이트 모델, llama.rn, Expo 모듈, 네이티브 Android 음성 API 및 로컬 우선 상태 기계(local-first state machine)를 결합하여 검사하고 변경할 수 있는 방식으로 구현되었습니다.

폐쇄된 호스팅 API는 빠른 프로토타입을 만들 수는 있지만, 중앙 대화를 원격 서비스로 옮기고 신호가 없는 환경에서의 워크플로우를 훨씬 덜 안정적으로 만듭니다. 오픈 컴포넌트 덕분에 개인 정보 보호 및 오프라인 동작을 마케팅 주장이 아닌 제품 기능으로 만들 수 있는 통제력을 얻었습니다.

여기에는 솔직한 트레이드오프가 있습니다: 작은 온디바이스(on-device) 모델은 대규모 클라우드 모델보다 용량이 적고, GGUF를 로드하려면 Android 휴대폰에 충분한 메모리가 필요합니다. Git Out은 이 트레이드오프를 선택했는데, 왜냐하면 걸으면서 이용할 수 있는 개인적인 답변이 네트워크 연결을 요구하는 더 큰 답변보다 여기에서 더 유용하기 때문입니다.

수상 부문 (Prize Categories)

저는 전체 Hacktoberfest 오픈 소스 AI 챌린지에 참가하고 있습니다. Git Out은 현재 파트너별 기술을 사용하지 않기 때문에 파트너 카테고리에는 신청하지 않았습니다.

제가 검증한 것 (What I Verified)

저장소에는 로컬 AI 가드, 음성 인식 동작, TTS 라이프사이클, 음성 대화 전환, Pocket Mode 상태 변경 및 중복 미디어-명령 처리(duplicate media-command handling)에 대한 자동화된 확인 기능이 포함되어 있습니다.

최종 프론트엔드 검사는 통과했습니다:

npm run typecheck ✓
npm test ✓ 50 tests passed
npx expo export --platform android ✓
...

최종 기기 데모를 위해 사용된 휴대폰 모델, Android 버전, 음성 서비스 및 TTS 엔진을 보고할 것입니다. 장치별 음성, 헤드셋, 백그라운드 재생 및 잠금 화면 동작은 기기에 따라 다를 수 있으므로, 이러한 세부 사항들은 모든 Android 폰에 대한 가정이라기보다는 데모 노트의 일부입니다.

마무리

Git Out은 개발자 도구를 책상에만 머무르게 하지 않으려는 작은 실험입니다. 목표는 사람들을 AI 채팅 창 안에 가두는 것이 아닙니다. 목표는 그들이 유용한 질문 하나를 하고, 실질적인 다음 단계를 듣고, 화면 밖의 세상으로 돌아가도록 하는 것입니다.