lokkju/term-recorder

term-recorder은(는) 무엇을 하나요?

term-recorder는 고정된 크기의 터미널에서 명령어를 실행하고, 스텝 단계에 따라 구동하며 화면에 표시되는 내용을 캡처합니다. 코드만 읽어서는 알 수 없는 "화면에 실제로 어떻게 보이는가"라는 질문에 답할 때 사용합니다: 다이얼로그가 긴 텍스트를 어떻게 줄 바꿈하는지, 마크다운이 렌더링되는지, TUI가 100열에서 어떻게 동작하는지, 클릭이 어디에 적용되는지 등을 확인할 수 있습니다.

이 명령어는 자체 tmux 서버(tmux -L term-record-<pid>, 생성된 설정 파일, 상태 줄 없음)에서 최소한의 환경으로 실행되므로, 사용자의 tmux 세션에 전혀 영향을 주지 않으며 명령어가 이 세션의 변수를 상속받지도 않습니다. 실행이 종료되면 서버는 종료됩니다.

실행 방법

record 도구(term-recorder MCP 서버의 도구; Claude Code에서는 mcp__plugin_term-recorder_term-recorder__record)를 다음 인자와 함께 호출하세요:

• command: 프로그램과 그 인자를 리스트로 지정합니다. 예: ["claude", "--model", "haiku"].
• steps: 한 줄에 하나씩 인라인 스텝을 지정하거나, steps_file로 스텝 파일을 지정합니다. 둘 다 먼저 파일을 실행합니다. 스텝 내 ${EXAMPLES}는 번들된 예제 디렉터리입니다.
• cwd: 명령어가 시작될 작업 디렉터리(기본값: 프로젝트 디렉터리). 인라인 스텝의 include 및 paste 경로는 이 디렉터리를 기준으로 합니다.
• out: 스냅샷이 저장될 디렉터리(기본값: 새 임시 디렉터리). 디렉터리는 생성됩니다.

각 snap NAME은 <out>/NAME.txt 파일을 작성하며, 마지막에는 항상 final 스냅샷이 저장됩니다. 결과는 모든 스냅샷의 화면 텍스트와 함께 스냅샷이 저장된 위치입니다. 이를 읽으면 답을 얻을 수 있습니다. show: "final"은 최종 화면만 반환하고 show: "none"은 아무것도 반환하지 않습니다(파일은 어차피 작성됩니다). snaps 도구는 이전 실행의 스냅샷을 나열하거나 이름으로 하나를 읽습니다. 실패한 스텝(대기 시간 초과, 클릭할 텍스트가 화면에 없음, 명령어 종료)은 결과를 오류로 만들며, 해당 스텝의 이름과 그 시점의 화면을 표시합니다.

check_steps는 실제 실행 없이 스텝을 구문 분석하므로, 실제 Claude Code 대화 비용이 드는 실행 전에 저렴한 사전 검증으로 유용합니다.

기본값: 100x30(size), TERM screen-256color, 그리고 서버 환경에서 HOME, PATH, USER, LOGNAME, SHELL, LANG, LC_ALL, LC_CTYPE, TMPDIR만 유지합니다. env(객체) 또는 pass(이름 목록)로 변수를 추가하고, vars로 스텝 치환을 추가할 수 있습니다.

MCP 서버 없이 사용

서버가 없는 에이전트에서는 동일한 코드 위에서 CLI를 실행합니다. 스크래치 디렉터리에 스텝 파일을 작성한 후, 다른 명령어에 연결하지 않고 독립적으로 실행하세요:

"${CLAUDE_SKILL_DIR}/scripts/term-record" -C <작업디렉터리> -s <스텝파일> -o <출력디렉터리> -- <명령어> [인자...]

${CLAUDE_SKILL_DIR}은 이 SKILL.md가 있는 디렉터리입니다. Claude Code는 이를 자동으로 채웁니다. 그대로 작성된 상태로 남아 있는 에이전트의 경우 해당 디렉터리 경로를 직접 넣으세요. 스냅샷은 <출력디렉터리>에 저장될 뿐만 아니라 표준 출력으로도 출력됩니다. 종료 상태 1은 스텝 실패(화면은 stderr로 출력), 2는 사용법 또는 설정 문제를 의미합니다. 플래그는 도구의 인자와 일치합니다: --size, --env NAME=VALUE, --pass NAME, --var NAME=VALUE, --cast, --gif, --agg-arg, 그리고 -s -는 표준 입력에서 스텝을 읽습니다.

스텝

한 줄에 하나, 셸 따옴표 사용 가능, # 주석:

스텝	기능
wait REGEX [TIMEOUT]	화면이 정규식과 일치할 때까지 대기(Python re, 여러 줄, 90초)
gone REGEX [TIMEOUT]	더 이상 일치하지 않을 때까지 대기
idle REGEX [QUIET] [TIMEOUT]	REGEX(바쁨 표시기)가 QUIET초 동안 나타나지 않을 때까지 대기(3초, 240초)
keys KEY...	tmux 키 이름 전송: Enter, Down, Escape, C-c
type TEXT [DELAY]	TEXT를 문자 그대로, DELAY초 간격으로 입력(0.03초, 0이면 한 번에 전송)
paste FILE	FILE을 하나의 브래킷 붙여넣기로 전송(여러 줄 프롬프트에 적합)
click TEXT	화면에서 첫 번째로 발견된 TEXT를 왼쪽 클릭
sleep SECONDS
snap NAME	화면을 텍스트로 캡처
resize COLSxROWS	실행 중 터미널 크기 변경. 레이아웃이 깨지는 지점을 확인하려면 각 변경 후 snap
record on|off	캐스트 프레임 켜기/끄기
include FILE	FILE의 스텝을 현재 위치에서 실행
when REGEX STEP...	현재 화면이 REGEX와 일치할 때만 STEP 실행

include 및 paste의 경로는 스텝 파일 기준(인라인 스텝의 경우 cwd 기준)입니다.

대상: Claude Code

include ${EXAMPLES}/claude-start.steps를 사용하면 폴더 신뢰 대화창을 건너뛰고 빈 프롬프트로 새 세션을 시작합니다. 먼저 넣으세요. ${EXAMPLES}/ask-dialog.steps는 질문 다이얼로그를 열고 스냅샷을 찍는 완전한 예제입니다.

• 스크래치 디렉터리(cwd)에서 시작하고, 모델이 중요하지 않다면 저렴한 모델(--model haiku)을 사용하며, env에 DISABLE_AUTOUPDATER=1을 추가하여 업데이트 알림이 화면에 나타나지 않도록 합니다.
• 체크아웃된 플러그인을 시도하려면 --plugin-dir <path>를 추가하고, --settings <file>로 설치된 복사본을 비활성화합니다("enabledPlugins": {"<name>@<marketplace>": false}).
• 작업 도구(TaskCreate 등)는 Claude 5 모델에서 비활성화되어 있습니다(대화형 또는 -p 사용 시). 단, CLAUDE_CODE_ENABLE_TODO_TOOLS=1이 env에 설정된 경우는 예외입니다. Claude Code 2.1.300부터 --model haiku는 Haiku 5.5이므로 haiku도 포함됩니다. 이러한 도구는 지연 도구(deferred tool)로, 초기 도구 목록이 아닌 지연 도구 목록에 표시되며 ToolSearch를 통해 로드됩니다.
• 프롬프트가 화면에 에코되므로, 결과에만 나타나는 텍스트(예: 다이얼로그의 번호 옵션 '[0-9]\. Accept')를 대기하고, 프롬프트 자체의 단어는 절대 대기하지 마세요.
• 바쁨 표시기(idle용): '\([0-9]+m? ?[0-9]*s · |esc to interrupt'.
• 각 실행은 사용자 계정의 실제 대화입니다. 필요한 턴(turn)만 수행하세요.

녹화

cast는 asciicast v2 파일을 작성하고, gif는 agg를 통해 렌더링합니다(agg_args로 인자 변경 가능). 결과는 두 경로를 모두 제공합니다. 프레임은 화면이 변경될 때 캡처됩니다. idle 대기 중에는 캐스트 시계가 8배 느리게 실행되므로(busy_timescale), 1분의 생각 시간이 몇 초 만에 재생됩니다.