HistoryLite

한국어 터미널 AI 에이전트의 Token Premium을 완화하는 PTY 기반 입력 변환 도구

터미널 AI 에이전트의 대화 기록을 가볍게 유지하기 위한 PTY 기반 입력 재작성 도구입니다. HistoryLite는 Claude Code, Gemini CLI, Codex CLI 같은 터미널 코딩 에이전트 앞단에서 동작합니다. 사용자는 한국어로 입력하지만, 에이전트에는 토큰 효율적인 영어 프롬프트만 제출되도록 하여 history에 한국어 입력이 그대로 누적되는 것을 줄입니다.

📌 프로젝트 소개

문제 배경

생성형 AI가 학업·업무·개발 도구로 확산되면서, 유료 구독료와 여러 AI 서비스 동시 사용이 개인에게 고정 지출로 자리잡고 있습니다.

무료 버전은 사용 횟수와 성능에 제한이 있고, 더 좋은 모델과 긴 문맥을 쓰기 위한 더 높은 요금제와 더 많은 Token 사용량은 새로운 장벽으로 떠오르고 있습니다.

문제 정의

한국어는 영어보다 더 긴 Token Sequence로 분해되는 경향이 존재하며, 터미널 에이전트에서는 이 차이가 매 요청마다 반복 참조되며 비용 부담으로 이어질 수 있다는 사실에 주목했습니다.

💡 제안 방식

본 프로젝트에서는 Token Premium을 완화하기 위해 영어로 AI를 사용하는 방식을 제안합니다.

사용자는 한국어로 입력하지만, 제출 직전에 영어 prompt로 변환하여 Token Premium이 붙는 한국어가 history에 누적되지 않도록 합니다.

⚙️ 동작 방식

/usage, /login, /resume, /compact 같은 slash command는 변환하지 않고 그대로 통과시켜, 에이전트의 native command 흐름을 유지합니다.

🚀 설치 및 사용

# 1) 설치
pip install -e .

# 2-a) 로컬 Ollama 백엔드
historylite --translator ollama --ollama gemma4:e4b --lang ko --translation-mode selective

# 2-b) Gemini 백엔드 (historylite/.env 에 GEMINI_API_KEY 설정)
historylite --translator gemini --lang ko --translation-mode selective

기본적으로 claude를 감싸 실행하며, --child로 다른 터미널 에이전트를 지정할 수 있습니다. 환경 변수는 historylite/.env에서 읽습니다 (.env.example 참고).

cd proxy
pip install -r requirements.txt
python server.py
# 에이전트가 Gateway를 거치도록: ANTHROPIC_BASE_URL=http://127.0.0.1:6543

🎥 데모 영상

demo3.mp4

🔎 효과 검증

한국어 원문과 제안 방식을 입력 단위와 작업 흐름 단위로 나누어 비교했습니다.

1. 단일 입력 Token Count 비교

2. 연속 작업에서의 사용량 비교

동일한 파일 편집 작업 시나리오를 Claude Code에서 실행하고, request별 토큰 사용량을 비교했습니다.

• 줄어든 입력이 캐시에 한 번 기록된 뒤 이후 요청에서 반복 반영되어, 턴이 진행될수록 차이가 누적됩니다.
• 비용 절감률 = (입력 변환으로 줄인 비용) ÷ (한국어 원문 전체 비용), Claude 공식 단가 기준.

🗂️ 프로젝트 구조

historylite/
├─ historylite/            # 코어 패키지
│  ├─ cli.py               # CLI 엔트리포인트
│  ├─ pty_wrapper.py       # PTY 중계 / 입력 버퍼링 / 제출
│  ├─ translation.py       # 입력 변환
│  ├─ protection.py        # 코드/경로 placeholder 보호·복원
│  ├─ context_hints.py     # Gateway 용어 힌트 로드
│  ├─ translator.py        # 백엔드 디스패치
│  ├─ ollama.py / gemini.py# 번역 백엔드
│  └─ dotenv.py            # .env 로더
├─ proxy/                  # Gateway (요청 관찰 + 용어 추출)
│  └─ server.py
├─ tests/                  # PTY·번역 회귀 테스트
├─ pyproject.toml
└─ README.md

🎯 향후 계획

• 검증 방식 보완 — 같은 의도의 prompt여도 에이전트의 작업 과정은 달라질 수 있으므로, 다양한 시나리오와 반복 실행을 포함한 테스트 보완.
• 입력 보존 개선 — 사진 첨부, 파일 경로 등 특수한 입력에서도 안정적으로 동작하도록 보존 방식 개선.
• 적용 범위 확대 — Codex CLI, Antigravity CLI 등 다른 터미널 에이전트로 확장.