opencode TUI에서 슬래시 커맨드와 키바인딩으로 빠르게 작업하기

opencode 명령을 실행하면 기본으로 열리는 화면이 TUI(Terminal User Interface)다. 터미널 이스케이프 시퀀스로 렌더링되는 채팅 환경이라 실시간 메시지 스트리밍, 자동완성, 스크롤, 다이얼로그, 키보드 내비게이션을 그대로 지원한다.

# TUI 시작
opencode

# 특정 프로젝트에서 TUI 시작
opencode ~/Work/my-project

입력 방식

프롬프트에 텍스트를 쓰고 Enter로 보내는 것이 가장 기본이다.

이 함수의 버그를 찾아줘

@를 입력하면 현재 작업 디렉토리에서 퍼지(fuzzy) 파일 검색이 열리고, 고른 파일의 내용이 메시지에 자동으로 딸려 들어간다.

@src/api/index.ts 이 파일에서 에러 처리가 빠진 곳을 찾아줘
@packages/functions/src/handler.ts 리팩토링 제안해줘

메시지 앞에 !를 붙이면 셸 명령이 실행되고, 그 출력이 툴 결과로 대화 컨텍스트에 추가된다.

!npm test -- --coverage
!git diff HEAD~1
!cat package.json

슬래시 커맨드

/로 시작하는 내장 커맨드는 총 17개다. 대부분 ctrl+x 리더 키 조합으로도 바로 실행할 수 있다.

커맨드	별칭	키바인딩	설명
`/connect`	—	—	AI 프로바이더 추가
`/compact`	—	`ctrl+x` → `c`	현재 세션을 요약해 컨텍스트 압축
`/details`	—	`ctrl+x` → `d`	툴 실행 상세 정보 토글
`/editor`	—	`ctrl+x` → `e`	외부 편집기로 메시지 작성
`/exit`	`/quit`, `/q`	`ctrl+x` → `q`	opencode 종료
`/export`	—	`ctrl+x` → `x`	대화를 마크다운으로 내보내기
`/help`	—	`ctrl+x` → `h`	도움말 다이얼로그 표시
`/init`	—	`ctrl+x` → `i`	AGENTS.md 초기 설정
`/models`	—	`ctrl+x` → `m`	사용 가능한 AI 모델 목록
`/new`	`/clear`	`ctrl+x` → `n`	새 세션 시작
`/redo`	—	`ctrl+x` → `r`	취소된 메시지 및 파일 변경 복원
`/sessions`	`/resume`, `/continue`	`ctrl+x` → `l`	세션 목록 조회 및 전환
`/share`	—	`ctrl+x` → `s`	현재 세션 공유
`/themes`	—	`ctrl+x` → `t`	사용 가능한 UI 테마 목록
`/thinking`	—	—	모델 추론 블록 표시 토글
`/undo`	—	`ctrl+x` → `u`	마지막 메시지 및 파일 변경 되돌리기
`/unshare`	—	—	세션 공유 중지

자주 쓰는 조합은 이런 식이다.

# 세션 컨텍스트가 길어졌을 때 요약
/compact

# 다른 모델로 전환
/models

# 실수한 AI 작업 되돌리기 (파일 변경 포함)
/undo

# 대화 내용을 마크다운 파일로 저장
/export

# 현재 프로젝트에 AGENTS.md 생성
/init

키바인딩: 리더 키와 내비게이션

opencode의 키바인딩은 리더 키 방식이다. 기본 리더 키는 ctrl+x이고, 이를 먼저 누른 뒤 액션 키를 입력한다. 터미널이 원래 쓰던 단축키와 충돌하지 않도록 한 설계다.

ctrl+x → n   # 새 세션
ctrl+x → l   # 세션 목록
ctrl+x → m   # 모델 선택

전체 리더 키 목록은 다음과 같다.

키	기능
`ctrl+x` → `h`	도움말
`ctrl+x` → `n`	새 세션
`ctrl+x` → `l`	세션 목록
`ctrl+x` → `m`	모델 선택
`ctrl+x` → `a`	에이전트 목록
`ctrl+x` → `t`	테마 선택
`ctrl+x` → `b`	사이드바 토글
`ctrl+x` → `s`	세션 공유
`ctrl+x` → `e`	외부 편집기 열기
`ctrl+x` → `c`	세션 요약(compact)
`ctrl+x` → `d`	툴 상세 토글
`ctrl+x` → `i`	AGENTS.md 초기화
`ctrl+x` → `x`	대화 내보내기
`ctrl+x` → `u`	되돌리기(undo)
`ctrl+x` → `r`	다시 실행(redo)
`ctrl+x` → `q`	종료

리더 키 없이 바로 쓰는 내비게이션 키도 따로 있다.

키	기능
`↑` / `↓`	서브에이전트 세션에서 부모/자식 이동
`←` / `→`	자식 에이전트 간 전환
`Page Up` / `Page Down`	메시지 스크롤

입력창 편집 단축키

프롬프트 입력창은 Readline/Emacs 스타일 단축키를 그대로 따른다. 커서 이동은 다음과 같다.

단축키	기능
`ctrl+a`	줄 시작으로 이동
`ctrl+e`	줄 끝으로 이동
`alt+b`	단어 단위 뒤로 이동
`alt+f`	단어 단위 앞으로 이동

텍스트 삭제는 다음과 같다.

단축키	기능
`ctrl+k`	커서 이후 줄 끝까지 삭제
`ctrl+u`	커서 이전 줄 시작까지 삭제
`ctrl+w`	커서 앞 단어 삭제

멀티라인 입력은 Enter와 Shift+Enter로 구분한다.

단축키	기능
`Enter`	메시지 전송
`Shift+Enter`	줄바꿈 (멀티라인 입력)

Windows Terminal에서는 Shift+Enter가 바로 동작하지 않을 수 있는데, settings.json에 이스케이프 시퀀스 [13;2u를 설정해야 정상 작동한다.

커스텀 커맨드

자주 쓰는 프롬프트는 슬래시 커맨드로 직접 등록할 수 있다. .opencode/commands/ 디렉토리에 마크다운 파일을 만들면 파일명이 곧 커맨드 이름이 된다.

.opencode/commands/
├── review.md       → /review
├── test.md         → /test
└── component.md    → /component

파일 내용은 그대로 프롬프트로 쓰인다.

전체 테스트 스위트를 커버리지 리포트와 함께 실행하고, 실패한 테스트를 보여줘.

/test

$ARGUMENTS, $1, $2 같은 플레이스홀더를 쓰면 동적 인수를 받을 수 있다.

다음 이름의 React 컴포넌트를 생성해줘: $ARGUMENTS

- TypeScript 사용
- props 타입 정의 포함
- 스토리북 스토리 파일 포함

/component Button
/component UserProfileCard

커스텀 커맨드 안에서도 !셸명령과 @파일참조 문법을 그대로 쓸 수 있다.

현재 git 변경 사항을 리뷰해줘:
!git diff HEAD

@src/types/index.ts 타입 정의도 참고해서 타입 안전성 확인해줘.

마크다운 파일 대신 opencode.jsonc에서 커맨드를 직접 등록하는 방법도 있다.

{
  "commands": [
    {
      "name": "review",
      "description": "코드 리뷰 실행",
      "prompt": "변경된 파일들의 코드 품질, 보안, 성능을 검토해줘",
    },
  ],
}

내장 커맨드와 같은 이름으로 정의하면 내장 커맨드를 그대로 덮어쓴다.

설정 파일 tui.json

TUI 동작은 tui.json(또는 tui.jsonc)으로 커스터마이징한다. 테마, 스크롤 속도(기본값 3), 마우스 캡처, diff 스타일, 리더 키, 개별 키바인딩까지 조정 대상이다.

{
  "$schema": "https://opencode.ai/tui.json",

  // 테마 설정
  "theme": "catppuccin-mocha",

  // 스크롤 설정
  "scroll_speed": 5, // 기본값: 3
  "scroll_acceleration": true, // macOS 스타일 가속 스크롤

  // 마우스 캡처
  "mouse_capture": true,

  // diff 스타일
  "diff_style": "inline",

  // 리더 키 변경
  "leader": "ctrl+o",

  // 키바인딩 커스터마이징
  "keybinds": {
    "new_session": "ctrl+o n",
    "sessions": "ctrl+o l",
    "models": "ctrl+o m",
    "exit": "ctrl+o q",

    // 특정 키바인딩 비활성화
    "share": "none",
  },
}

설정 파일 경로를 다른 곳으로 바꾸고 싶으면 환경변수로 지정한다.

OPENCODE_TUI_CONFIG=~/my-tui-config.json opencode

Vim 키바인딩

Vim 스타일 입력을 선호하면 설정에서 켤 수 있다. 다만 NORMAL과 INSERT 두 모드만 지원한다.

{
  "vim": true,
}

NORMAL 모드의 주요 키는 다음과 같다.

키	기능
`i`	INSERT 모드 진입
`a`	커서 뒤에서 INSERT 모드 진입
`I`	줄 시작에서 INSERT 모드 진입
`A`	줄 끝에서 INSERT 모드 진입
`h` / `l`	커서 좌/우 이동
`w` / `b`	단어 단위 앞/뒤 이동
`0` / `$`	줄 시작/끝 이동
`x`	현재 문자 삭제
`dw`	단어 삭제
`dd`	줄 삭제
`Esc`	NORMAL 모드 복귀

Visual 모드, Command 모드, ex 커맨드는 지원하지 않는다.

실전 워크플로우

버그를 디버깅할 때는 에러 로그를 컨텍스트에 넣고, 관련 파일을 참조시킨 뒤, 필요하면 되돌리고 마지막에 세션을 저장하는 흐름이 자연스럽다.

# 1. 에러 로그를 컨텍스트에 추가
!cat logs/error.log

# 2. 관련 파일 참조
@src/services/payment.ts 이 에러를 분석해줘

# 3. AI가 수정 후 되돌리고 싶을 때
/undo

# 4. 세션을 마크다운으로 저장
/export

코드 리뷰는 diff를 넘기고 질문한 뒤, 세션이 길어지면 압축하는 순서로 진행한다.

# 변경사항 전달
!git diff HEAD~1

# 리뷰 요청
이 변경사항에서 보안 이슈나 성능 문제가 있으면 알려줘

# 긴 리뷰 세션에서 컨텍스트 압축
/compact

새 프로젝트에 들어갈 때는 AGENTS.md부터 초기화하고 구조를 파악한 뒤 복잡한 작업이면 모델을 바꾼다.

# 1. AGENTS.md 초기화
/init

# 2. 프로젝트 구조 파악
!find . -name "*.ts" | head -20

# 3. 아키텍처 분석
@src/index.ts @src/types.ts 이 프로젝트 구조를 분석해줘

# 4. 모델 전환 (복잡한 작업)
/models

여러 세션을 오가며 작업할 때는 리더 키와 /sessions를 함께 쓴다.

# 현재 작업 세션 유지하면서 다른 세션으로 전환
ctrl+x → l

# 새 세션에서 독립적인 작업 수행
ctrl+x → n

# 이전 세션으로 복귀
/sessions

긴 프롬프트는 외부 편집기로 작성하는 편이 낫다.

# $EDITOR 환경변수에 설정된 편집기로 열기
ctrl+x → e

# 편집기에서 작성 후 저장·종료하면 TUI 프롬프트에 자동 삽입

빠른 참조 카드

입력 방식
  텍스트      → 일반 메시지 전송
  @파일명     → 파일 내용 참조 (퍼지 검색)
  !명령어     → 셸 명령 실행 후 결과 삽입
  /커맨드     → 슬래시 커맨드 실행

필수 단축키
  ctrl+x → n  새 세션
  ctrl+x → l  세션 목록
  ctrl+x → m  모델 선택
  ctrl+x → u  되돌리기
  ctrl+x → h  도움말
  ctrl+x → q  종료

입력창
  ctrl+a / ctrl+e   줄 시작/끝
  ctrl+k / ctrl+u   줄 끝/시작까지 삭제
  ctrl+w            단어 삭제
  Shift+Enter       줄바꿈 (멀티라인)

ctrl+x → h 또는 /help를 입력하면 TUI 안에서 언제든 최신 도움말을 볼 수 있다.