WinkTerm: 단순히 명령어를 제안하는 것을 넘어 터미널 세션을 공유하는 AI

저는 "터미널 내 AI" 도구들에 대해 한 가지 문제를 느끼고 있습니다.

그것들은 거의 모두 똑같습니다. 바로 채팅 사이드바(chat sidebar) 형태죠. 질문을 던지면 AI는 "이 명령어를 시도해 보세요"라고 답하고, 여러분은 그것을 복사해서 붙여넣습니다. AI는 여러분의 셸(shell)이 보는 것을 실제로 전혀 보지 못합니다. 여러분이 루트(root) 권한인지, 그 명령어가 성공했는지, $PWD가 무엇인지, 혹은 두 줄 위에서 발생한 에러가 무엇인지 전혀 알지 못합니다. 마치 전화로 모든 것을 일일이 불러줘야 하는 박학다식한 친구와 같습니다.

저는 그냥 손을 뻗어 직접 타이핑할 수 있는 친구를 원했습니다.

그래서 저는 **WinkTerm**을 만들었습니다. AI와 제가 동일한 PTY(Pseudo-Terminal)를 공유하는 MIT 라이선스 기반의 AI 터미널입니다.

실제 사용 느낌

여러분은 셸 프롬프트(shell prompt)에 있습니다. # 이 VPN 설정에 무엇이 잘못되었나라고 입력합니다. AI는 동일한 터미널 내에서 답변을 하고, 제안하는 수정 사항을 여러분의 입력 라인에 미리 채워 넣습니다(pre-fills). 실행하려면 Enter를 누르면 됩니다. 수정하려면 Backspace를, 취소하려면 Ctrl+C를 누르세요.

$ ipconfig
Command 'ipconfig' not found, did you mean: ...
$ # what's wrong
...

AI는 동일한 세션 안에 있기 때문에 여러분이 보는 것을 똑같이 봅니다. AI가 명령어를 실행하면, 그 출력은 실제 종료 코드(exit codes)를 포함한 실제 셸 출력이며, 여러분의 실제 cwd(current working directory)에서 실행됩니다. 여러분이 명령어를 실행하면, AI는 이를 다음 턴을 위한 컨텍스트(context)로 기억합니다.

이것이 중요한 이유

사이드바 챗봇은 현실적인 상황을 마주하기 전까지는 훌륭합니다. 예를 들어, 지난 명령어에서 설정한 환경 변수(env vars), 다단계 디버깅 세션, 혹은 부분적으로 적용된 마이그레이션(migration) 같은 상황 말이죠. 챗봇은 그 중 어떤 일이 일어났는지 전혀 알지 못합니다. 공유 PTY(shared-PTY) 모델은 AI가 여러분의 손이 겪는 것과 동일한 컨텍스트 드리프트(context drift)를 상속받는다는 것을 의미합니다.

또한 이는 여러분이 제어권을 유지하게 해줍니다. (기본 설정상) AI는 여러분이 Enter를 누르지 않고서는 명령어를 절대 실행하지 않습니다. 자동 실행이 아닌 미리 채우기(Pre-fill) 방식입니다. 여러분은 운영자(operator)로서 남습니다.

포함된 기능

• Shared PTY chat — # message 입력 시 AI가 인라인(inline)으로 트리거됩니다.
• Sidebar AI panel — 더 긴 대화를 원할 때 사용하는 사이드바 AI 패널로, 멀티 탭 채팅과 AI가 생성한 제목을 지원합니다.
• Multi-model — Anthropic / OpenAI / Ollama / 기타 OpenAI 호환 엔드포인트를 지원합니다.
• SSH — 파일 전송 기능이 포함된 내장 원격 접속 기능을 제공합니다.
• Persistent history — 재연결이나 백엔드 재시작 시에도 채팅 기록이 유지됩니다.
• Streaming resume — 응답 중간에 새로고침을 해도 토큰(tokens) 손실 없이 이어갑니다.
• HTTP Agent API — Claude Code / Cursor가 터미널과 SSH를 원격으로 제어할 수 있습니다.
• Deploy any way you want — Docker, Win/macOS 데스크톱 앱, 또는 Android 씬 클라이언트(thin client) 등 원하는 방식으로 배포할 수 있습니다.

Stack (기술 스택)

• Backend (백엔드): Python, FastAPI, 에이전트 상태 머신(agent state machine)을 위한 LangGraph, 네이티브 PTY (pty/winpty)
• Frontend (프론트엔드): Next.js 14 (App Router) + xterm.js
• Protocol (프로토콜): 터미널 스트림을 위한 WebSocket; #로 시작하는 라인은 셸(shell)에 도달하기 전에 가로채어 에이전트(agent)로 라우팅됩니다.

Data flow (데이터 흐름)

User keyboard input (사용자 키보드 입력)
    │
    ▼
...

에이전트의 출력은 PTY 출력으로 다시 기록됩니다. 즉, 다른 모든 내용과 동일한 스크롤백(scrollback)에 나타납니다. "AI"는 단지 동일한 파일 디스크립터(fd)에 쓰는 또 다른 작성자일 뿐입니다.

Status (상태)

MIT 라이선스, 약 3.5개월 된 프로젝트이며, 제가 직접 구축한 인프라에서 매일 실행 중입니다. 피드백을 환영합니다. 특히 사이드바 스타일의 AI 터미널 때문에 답답함을 느끼셨던 분들의 의견을 기다립니다.

GitHub: https://github.com/Cznorth/winkterm