remorses/tuistory

TMUX for agents. let agents control & test terminal user interfaces. Like Playwright & agent-browser but for TUIs

tuistory – “AI 에이전트를 위한 tmux”

그것은 무엇인가 – Node‑JS CLI(및 라이브러리)로 관리되는 PTY 세션 내에서 모든 터미널 명령을 실행합니다. 세션은 백그라운드에서 실행되며, AI 기반 에이전트가 검사, 대기, 입력, 스크린샷을 찍을 수 있고, 인간은 언제든지 같은 세션에 연결하여 에이전트가 보는 것을 정확히 볼 수 있습니다.

AI/ML에 중요한 이유 – 현재 LLM 기반 코딩 에이전트는 종종 개발 서버나 REPL을 시작한 다음 프로세스가 준비될 때까지 폴링하거나 슬립해야 합니다. tuistory는 이러한 에이전트에게 결정적이고 이벤트 기반의 제어를 제공합니다:

로그 읽기 (tuistory read),
특정 출력 대기 (tuistory wait "ready"),
터미널 화면의 스냅샷 또는 스크린샷 캡처,
프로세스에 타이핑 또는 키 입력,
프로세스 재시작/종료 – 모두 즉시 반환되는 빠른 CLI 호출로 수행됩니다.

작동 방식

tuistory -- <command>는 백그라운드 PTY에서 명령을 실행하고 세션 이름을 등록합니다 (cwd와 명령에서 자동 파생, 예: myapp-next-dev).
작은 데몬이 모든 세션을 메모리에 유지하고 CLI 도구와 에이전트가 PTY와 통신할 수 있도록 로컬 WebSocket 서버(127.0.0.1에 바인딩)를 노출합니다.
인간은 tuistory attach로 모든 세션에 연결할 수 있으며, tmux attach처럼 동작합니다 – 라이브 터미널을 보고, 상호작용하고, Ctrl+C를 두 번 눌러 분리할 수 있습니다.
에이전트는 동일한 CLI(또는 프로그래매틱 API)를 사용하여 출력 읽기, 패턴 대기, 입력, 키 누르기, 스크린샷 캡처 등을 수행합니다.

주요 CLI 명령어

명령어	목적
`tuistory -- <cmd>`	새 세션 시작 (이미 존재하면 다시 연결).
`tuistory read -s <name> [--all]`	마지막 읽기 이후의 새 stdout 반환 (또는 전체 버퍼).
`tuistory wait -s <name> <pattern>`	주어진 텍스트/정규식이 나타날 때까지 차단.
`tuistory wait-idle -s <name>`	터미널이 설정 가능한 지연 동안 조용해질 때까지 차단.
`tuistory snapshot -s <name> [--trim]`	현재 화면을 일반 텍스트로 가져오기.
`tuistory screenshot -s <name>`	화면을 PNG 이미지로 저장.
`tuistory type -s <name> "text"`	프로세스에 문자를 하나씩 입력.
`tuistory press -s <name> <key>`	키 또는 코드 전송 (예: `ctrl c`).
`tuistory restart -s <name>`	같은 세션에서 원래 명령을 재시작.
`tuistory close -s <name>`	프로세스를 종료하고 세션을 삭제.
`tuistory attach -s <name>`	인간 전용 대화형 연결 (tmux처럼).
`tuistory sessions`	활성 세션 목록 표시.

프로그래매틱 API – 동일한 기능이 TypeScript 라이브러리로 제공됩니다:

import { launchTerminal } from 'tuistory'
const sess = await launchTerminal({ command: 'claude', cols:150, rows:45 })
await sess.waitForText('Claude Code')
await sess.type('what is 2+2?')
await sess.press('enter')
const out = await sess.read()
sess.close()

API는 CLI를 반영합니다: type, press, text, read, waitForText, click, close 등.

LLM 기반 코딩 에이전트의 일반적인 워크플로우

# 1️⃣ 도구를 백그라운드 세션에서 시작 (예: 웹 개발 서버)
tuistory -s dev -- pnpm dev

# 2️⃣ 서버가 "ready"를 출력할 때까지 대기
tuistory -s dev wait "ready" --timeout 30000

# 3️⃣ 에이전트는 추가 작업을 실행할 수 있습니다 (예: 브라우저 열기, 테스트 실행 등)
# 4️⃣ 인간이 상황을 확인하려면:
#    $ tuistory attach -s dev

모든 단계는 에이전트에게 비차단적이며, 임의의 sleep 호출이 필요 없습니다.

설치

npm install -g tuistory   # 전역 CLI
# 또는 프로젝트 의존성으로
npm install tuistory

전체 옵션 목록은 tuistory --help를 실행하세요.

사용 대상

LLM 오케스트레이션 자동화 (예: Claude Code, Auto‑GPT 스타일 에이전트)를 개발하고 신뢰할 수 있는 터미널 상호작용이 필요한 개발자.
플래키한 슬립 없이 대화형 CLI 도구(REPL, 디버거)를 스크립트화하려는 테스트 엔지니어.
백그라운드 프로세스에 이미 tmux를 사용하지만 기계가 읽을 수 있는 인터페이스를 원하는 사람.

관련 프로젝트 – tuistory는 저자의 termcast(Raycast 스타일의 터미널 UI)와 kimaki(TUI를 제어하는 Discord 봇 에이전트)를 구동합니다.

라이선스 – MIT.