<div align="center">
ARIA — Termux용 AI 터미널 부조종사
Python
Shell
License
Termux를 실제로 이해하는 터미널 AI 비서입니다.
</div>
상태 (Status)
ARIA는 원래 Google Gemma 4 Challenge(write-up)를 위해 구축되었습니다. 이제는 그 단계를 넘어, 제공하는 모든 모델과 작동하는 일반적인 오픈 소스 도구가 되었습니다. 이 프로젝트는 한 사람이 구축하고 유지 관리하므로, 마감 기한보다는 이슈와 풀 리퀘스트(pull requests)에 의해 작업이 주도됩니다.
- 안정적 기능 (Stable): 핵심 루프, 슬래시 명령어(slash commands), Guardian, watch 모드, 오프라인 지식 기반, 그리고 세 가지 제공업체(Google AI Studio, OpenRouter, NVIDIA NIM).
이것은 무엇인가요? (What is this?)
ARIA는 터미널 내에 존재하는 AI 비서입니다. Termux, 안드로이드 파일 시스템의 특이점(quirks), proot 컨테이너, clang-not-gcc 등 휴대폰으로 개발할 때 마주치는 모든 이상한 문제들을 알고 있습니다.
Termux 내부의 슬래시 명령어 인터페이스를 통해 질문에 답하고, 오류를 진단하며, 해결책을 제안하고, 손상된 설치를 자동 복구할 수 있습니다.
가볍습니다. 의존성(dependency)은 하나(rich)뿐이며, 나머지는 표준 라이브러리(stdlib)로 구성되어 있습니다. 무거운 프레임워크는 없습니다.
스크린샷 (Screenshots)
<details>
<summary><b class="" >클릭하여 확장</b></summary>
시작 (Startup)
<img width="1080" height="2173" alt="Startup" src="https://github.com/user-attachments/assets/8ad4418c-72b1-4581-9dff-092006ff4b67" />
모델 선택 (Model Selection)
<img width="1080" height="2157" alt="Model Selection" src="https://github.com/user-attachments/assets/8f8a4674-ba89-4204-8f99-f54bbca52833" />
오류 분석 (Error Analysis)
<img width="1079" height="2162" alt="Error Analysis" src="https://github.com/user-attachments/assets/a216a5a2-9897-4e68-90ed-94dfe55bae00" />
</details>
데모 (Demo)
설치 (Install)
pkg update && pkg upgrade -y
pkg install python git -y
...
Google provider는 추가 패키지 없이 작동합니다. 만약 google-generativeai가 설치되어 있다면 ARIA가 이를 사용합니다. 그렇지 않다면, ARIA는 HTTPS를 통해 Google API와 직접 통신합니다. 이 패키지는 SDK 경로(path)가 필요할 때만 필요합니다:
pip install google-generativeai --break-system-packages
최초 실행 (First Run)
최초 실행 시, ARIA는 설정 파일이 없음을 감지하고 설정 과정을 안내합니다:
Choose provider [google/openrouter/nvidia_nim]: google
Enter API key: ••••••••••••••
Enter model (press Enter for the default):
...
여기서 키를 검증합니다. 문제가 있다면 나중에 알 수 없는 오류가 발생하는 대신 즉시 알게 됩니다.
무료 키 받기:
사용법 (Usage)
그냥 입력하세요. 일반 텍스트는 질문으로 모델에 전달됩니다. 또는 슬래시 명령어(slash command)를 사용하세요:
| 명령어 | 기능 |
|---|
/ask <question> | 모든 것을 물어보기 |
| ... | |
Watch Mode
/watch를 활성화한 후, 다른 Termux 세션에서 작업합니다. 해당 세션에서 명령어가 실패하면, 셸 훅(shell hook)이 이를 ~/.aria/last_fail.json에 기록합니다. ARIA로 돌아와 /fix를 입력하면, 자동으로 실패 내용을 읽어옵니다.
프로바이더 (Providers)
| 프로바이더 | 엔드포인트 | 인증 방식 |
|---|
google | Google AI Studio | aistudio에서 받은 API 키 |
| ... | | |
ARIA는 사용자가 어떤 프로바이더를 사용하든 이용 가능한 모델을 자동으로 감지합니다. /model list를 실행하여 목록을 확인하고, /model set <name>으로 전환할 수 있습니다. | | |
아키텍처 (Architecture)
aria/
├── main.py — 메인 루프, 명령어 분배, 설정 마법사
├── api_client.py — 프로바이더 추상화 계층 (Google, OpenRouter, NVIDIA)
...
API 계층은 Python의 urllib을 직접 사용합니다. requests, httpx와 같은 무거운 HTTP 라이브러리는 사용하지 않습니다. 프로바이더 전환은 단순히 어떤 기본 URL(base URL)과 인증 헤더(auth header)가 사용될지 변경하는 것입니다.
전체 설계는 ARCHITECTURE.md를 참조하세요.
Guardian
ARIA가 위험한 작업을 실행하도록 제안하기 전에, 위험도를 점수화합니다:
| 레벨 | 발생 내용 |
|---|
| Low (green) | 즉시 실행 |
| ... | |
rm -rf, chmod 777, 파이프를 통한 쉘 curl 등 — 모두 플래그가 지정됩니다. | |
Config
~/.aria/config.json에 저장되어 있습니다:
{
"provider": "google",
"api_key": "your-active-key",
...
}
환경 변수(env vars)를 통해 덮어쓸 수도 있습니다:
export ARIA_API_KEY="..."
export ARIA_PROVIDER="openrouter"
export ARIA_MODEL="your-model-name"
Dependencies
| 패키지 | 이유 | 필수 여부 |
|---|
rich | 터미널 UI, 구문 강조(syntax highlighting), 스피너 | 예 (Yes) |
google-generativeai | Google 제공업체용 선택적 SDK (ARIA는 이것 없이 일반 HTTPS로 폴백합니다) | 아니요 (No) |
나머지 모든 것(HTTP, JSON, 스레딩, 설정)은 표준 라이브러리(stdlib)입니다. 세 가지 제공업체 모두 추가 패키지 없이 작동합니다.
Testing
알려진 제한 사항(Known limitations)
- 감시 모드(Watch mode)는 파일 폴링(file polling)을 통해 작동합니다. 즉각적이지는 않지만 신뢰할 수 있습니다.
- AI 기능은 인터넷 연결이 필요합니다. 지식 기반(
/kb)은 오프라인으로 작동합니다.
- Android의 Termux용으로 구축되었습니다. Linux에서도 실행되지만, 그것이 초점은 아닙니다.
- 자동 수정 제안(Auto-fix suggestions)은 적용하기 전에 검토해야 합니다.
기여(Contributing)
Issue와 PR을 환영합니다. 현재로서는 버그 보고서가 가장 유용하며, 특히 사용 중인 Termux 버전, Android 버전, Python 버전, 그리고 어떤 제공업체를 사용했는지 포함된 보고서가 좋습니다.
git checkout -b feature/my-thing
git commit -m "수행한 작업 내용"
...
간단하게 유지하세요. PEP 8을 따르세요. 새로운 기능에 대한 테스트를 작성하세요. 절대적으로 필요하지 않은 경우에만 의존성을 추가하세요. 자세한 내용은 CONTRIBUTING.md를 참조하세요.
라이선스(License)
MIT. LICENSE를 참조하세요.
<div align="center">
Stars
GitHub
</div>
