opencode를 쓰다 보면 기능 자체는 좋은데, TUI에서 바로 처리하기 애매한 작은 불편들이 있습니다.
opencode 후기, Claude Code 갈아탈만한 이유 WSL 설치부터 MCP까지 정리
opencode가 처음 나왔을 때는 그냥 또 흔한 Claude Code 계열 CLI 클론이려니 하고 넘겼습니다. 그런데 요즘 정말 많은 CLI도구들 출시와함께 "Claude Code 정리하고 갈아탔다"는 글이 부쩍 보이길래 의심
newstroyblog.tistory.com
1편에서 opencode 설치와 인증까지 다뤘다면, 이번 글은 그 다음 단계입니다. 설치만으로 끝내지 않고, 실제로 자주 쓰게 되는 설정과 숨겨진 내장 도구를 TUI 안에서 켜고 관리하는 방법을 정리합니다.
예를 들어 provider를 연결하는 것은 /connect 명령어로 쉽게 할 수 있습니다. 그런데 이미 연결된 provider 중 하나만 끊고 싶을 때는 생각보다 애매합니다. opencode 안에서 바로 끊는 명령어가 없어서 결국 인증 파일을 직접 열어 수정하게 됩니다.
또 하나 헷갈리는 부분은 websearch와 LSP입니다. opencode에는 웹 검색과 AI용 LSP tool이 있지만, 설치만 하면 항상 바로 보이는 구조는 아닙니다. websearch는 OPENCODE_ENABLE_EXA, AI용 lsp tool은 OPENCODE_EXPERIMENTAL_LSP_TOOL 같은 시작 환경변수가 필요합니다. 이런 설정을 매번 직접 기억해서 .bashrc나 opencode.json을 편집하는 것도 번거롭습니다.
~/.local/share/opencode/auth.json처음에는 저도 그냥 이 파일을 열어서 provider 항목 하나 지우면 되겠다고 생각했습니다.
{
"github": { "type": "copilot-free" },
"anthropic": { "type": "api-key" },
"openai": { "type": "api-key" }
}여기서 github만 지우면 원하는 provider 하나만 끊을 수 있습니다. 하지만 매번 JSON 파일을 직접 수정하는 방식은 별로 좋은 사용 경험이 아닙니다. 쉼표 하나를 잘못 지우거나, 파일 구조가 깨지면 opencode가 인증 정보를 제대로 읽지 못할 수도 있습니다.
그래서 만든 것이 opencode-tui-utils입니다.
이 프로젝트는 단순히 명령어 몇 개를 추가하는 것만 목표로 하지 않습니다. 더 정확히는 opencode TUI가 이미 가지고 있는 정보와 기능을 사용자가 더 쉽게 꺼내 쓸 수 있도록 작은 명령어로 연결하는 것이 목표입니다.
opencode에는 이미 provider, 세션, diff, plugin, todo 같은 정보가 존재합니다. 하지만 어떤 정보는 메뉴를 찾아가야 하고, 어떤 작업은 설정 파일을 직접 수정해야 하고, 어떤 것은 터미널 명령어를 따로 쳐야 합니다. opencode-tui-utils는 이런 사이의 빈틈을 TUI 안의 slash command로 메우려는 프로젝트입니다.
이 프로젝트가 해결하려는 방향
opencode-tui-utils의 방향은 크게 세 가지입니다.
첫 번째는 설정 파일 직접 수정 줄이기입니다.
auth.json, opencode.json, shell profile 같은 파일을 매번 직접 열지 않아도 되도록, 자주 쓰는 작업을 명령어로 제공합니다. /disconnect, /lsp-toggle, /websearch-toggle, /permissions 같은 명령어가 여기에 해당합니다.
두 번째는 세션 정보를 빠르게 확인하기입니다.
AI에게 작업을 시키다 보면 어떤 파일이 바뀌었는지, 현재 세션에 어떤 todo가 남았는지, 대화 내용을 남기고 싶은 상황이 생깁니다. /session-diff, /session-todos, /export-chat 같은 명령어는 이런 흐름을 보조합니다.
세 번째는 opencode 플러그인 생태계의 예시 만들기입니다.
opencode는 플러그인을 통해 TUI를 확장할 수 있습니다. 하지만 실제로 어떤 식으로 명령어를 만들고, 어떻게 TUI dialog를 띄우고, 어떤 API를 써야 하는지 처음 보면 감이 잘 안 올 수 있습니다. 이 프로젝트는 작은 명령어들을 하나씩 추가하면서 opencode TUI 플러그인을 만드는 참고 예시 역할도 하려고 합니다.
즉, 이 프로젝트는 "대단한 올인원 자동화 도구"라기보다는 opencode TUI 생태계에서 빠진 작은 편의 기능을 하나씩 채워가는 유틸리티 모음에 가깝습니다.
설치 방법
설치는 opencode CLI에서 바로 할 수 있습니다.
opencode plugin opencode-tui-utils이 명령어는 opencode 안에서 입력하는 슬래시 명령어가 아니라, 터미널에서 실행하는 CLI 명령어입니다.
흐름은 아래와 같습니다.
# 터미널에서 플러그인 설치
opencode plugin opencode-tui-utils
# opencode 실행 또는 재시작
opencode그 다음 opencode TUI 안에서 아래 명령어들을 사용할 수 있습니다.
/disconnect
/lsp-toggle
/websearch-toggle
/tool-status
/export-chat
/session-diffopencode CLI의 plugin 명령어는 npm module name을 받습니다. opencode-tui-utils는 npm에 배포된 패키지이기 때문에 위 명령어로 설치할 수 있습니다.
현재 제공하는 명령어
현재 제공하는 명령어는 총 10개입니다.
| 명령어 | 설명 |
|---|---|
/disconnect |
연결된 provider 하나를 선택해서 안전하게 제거 |
/lsp-toggle |
LSP 서버와 AI용 experimental lsp tool 환경변수를 함께 전환 |
/websearch-toggle |
OpenCode built-in websearch 환경변수를 전환 |
/tool-status |
websearch, AI용 lsp, LSP 서버 상태 확인 |
/tool-env |
시작 환경변수를 한 메뉴에서 관리하는 고급 메뉴 |
/plugin-list |
설치된 플러그인과 활성화 상태 확인 |
/export-chat |
현재 세션 대화를 마크다운 파일로 저장 |
/session-diff |
현재 세션에서 변경된 파일 목록 확인 |
/session-todos |
현재 세션의 todo 목록 확인 |
/permissions |
opencode 권한 설정을 TUI로 관리 |
제목을 "플러그인 10가지"라고 쓰면 플러그인이 10개인 것처럼 보일 수 있습니다. 실제로는 opencode-tui-utils라는 하나의 플러그인 안에 여러 slash command가 들어있는 구조입니다.
/disconnect - provider를 안전하게 제거
가장 먼저 만든 명령어입니다.
opencode에는 provider를 연결하는 /connect 명령어가 있습니다. 하지만 연결된 provider 하나만 끊고 싶을 때는 직접 auth.json을 수정해야 하는 경우가 있었습니다.
/disconnect를 실행하면 연결된 provider 목록이 TUI dialog로 뜹니다. 여기서 제거할 provider를 선택하면 해당 provider 키만 인증 파일에서 제거합니다.
/disconnect토큰 값은 화면에 출력하지 않습니다. provider 이름과 인증 타입만 보여주고, 실제 API key나 token 값은 노출하지 않습니다.
이 명령어 하나만으로도 auth.json을 직접 열어서 수정하는 과정을 줄일 수 있습니다.
/lsp-toggle - LSP 서버와 AI용 LSP tool 함께 켜기
opencode 설정 파일에는 LSP 관련 설정이 있습니다.
~/.config/opencode/opencode.json/lsp-toggle을 실행하면 현재 LSP 설정이 켜져 있는지 꺼져 있는지 확인한 뒤, 반대로 전환할 수 있습니다.
/lsp-toggle이 명령어는 두 가지를 함께 처리합니다.
{
"lsp": true
}그리고 shell profile에는 AI용 LSP tool을 켜기 위한 환경변수를 저장합니다.
export OPENCODE_EXPERIMENTAL_LSP_TOOL=1opencode의 LSP는 두 층으로 나뉘어 있습니다. 하나는 언어 서버를 시작하는 LSP 서버 설정이고, 다른 하나는 모델이 goToDefinition, findReferences, hover 같은 LSP query를 직접 호출할 수 있게 하는 experimental lsp tool입니다.
/lsp-toggle은 이 둘을 같이 켜고 끄도록 만들었습니다. 다만 opencode는 설정과 환경변수를 시작 시점에 읽기 때문에, 이 명령어로 값을 바꾼 뒤에는 새 터미널에서 opencode를 재시작해야 반영됩니다.
/websearch-toggle - 웹 검색 tool 켜기
opencode에는 webfetch뿐 아니라 websearch도 있습니다. 둘은 역할이 다릅니다.
| 도구 | 역할 |
|---|---|
webfetch |
이미 알고 있는 URL을 가져와 읽기 |
websearch |
검색어로 웹에서 관련 문서 찾기 |
다만 websearch는 기본 설치 직후 항상 바로 보이지 않을 수 있습니다. OpenCode provider를 쓰거나, 아래 환경변수가 켜져 있어야 합니다.
export OPENCODE_ENABLE_EXA=1/websearch-toggle은 이 환경변수를 shell profile에 저장하거나 제거합니다.
/websearch-toggleOpenCode 공식 문서 기준으로 websearch는 별도 API key가 필요 없습니다. Exa AI hosted MCP service에 인증 없이 연결한다고 되어 있습니다. 즉 사용자가 따로 Exa key를 발급받아 넣는 방식이 아니라, OpenCode의 built-in tool을 켜는 기능 플래그에 가깝습니다.
이 역시 시작 시점에 결정되는 기능이라, 토글 후에는 새 터미널에서 opencode를 다시 실행해야 합니다.
/tool-status - 지금 뭐가 켜져 있는지 확인
websearch와 AI용 lsp tool은 헷갈리기 쉽습니다. permission에 allow가 있어도 실제 tool 목록에 뜨지 않을 수 있고, lsp: true가 있어도 AI용 lsp tool은 별도 환경변수가 필요합니다.
그래서 상태 확인용으로 /tool-status를 추가했습니다.
/tool-status이 명령어는 아래 내용을 한 번에 보여줍니다.
opencode.json의 LSP 서버 설정- 현재 실행 중인 환경변수 상태
- shell profile에 저장된 다음 실행용 환경변수 상태
websearch, AI용lsptool, LSP 서버의 활성화 여부
터미널에서는 아래 명령어로도 실제 tool 목록을 확인할 수 있습니다.
opencode debug agent build여기서 websearch와 lsp가 보이면 모델에게 실제로 tool이 노출된 상태입니다.
/tool-env - 시작 환경변수 고급 관리
평소에는 /lsp-toggle, /websearch-toggle을 쓰면 됩니다. /tool-env는 websearch와 AI용 lsp tool 환경변수를 한 메뉴에서 켜고 끄고 싶을 때 쓰는 고급 메뉴입니다.
/tool-env예를 들어 둘 다 한 번에 켜거나, 둘 다 끄는 식으로 관리할 수 있습니다.
/permissions - 권한 설정을 TUI로 관리
opencode는 외부 디렉토리 접근이나 파일 수정, bash 명령어 실행 같은 작업을 할 때 권한을 물어보는 경우가 있습니다. 매번 승인 버튼을 누르는 것이 번거로울 때가 있습니다.
/permissions를 실행하면 TUI dialog를 통해 권한 설정을 관리할 수 있습니다.
/permissions메뉴는 아래와 같이 구성되어 있습니다.
- View current permissions - 현재
opencode.json의permission설정을 확인 - Set global permission mode - 전체 도구의 기본 권한을
ask/allow/deny중 하나로 설정 - Toggle per-tool permission -
read,edit,bash,external_directory등 개별 도구의 권한 설정 - Manage pattern permissions - 특정 경로 패턴에 대해서만 권한을 다르게 지정
- Reset permissions - 권한 설정을 초기화
예를 들어 /tmp/workspace/*나 /home/shell/* 경로에 대해 매번 권한을 묻지 않고 자동으로 허용하고 싶다면, pattern permissions에 해당 경로를 allow로 추가하면 됩니다.
/permissions → Manage pattern permissions → external_directory
→ Add new pattern → /tmp/workspace/* → allow
이렇게 하면 opencode.json에 아래처럼 자동으로 반영됩니다.
{
"permission": {
"external_directory": {
"/tmp/workspace/*": "allow"
}
}
}/permissions는 설정 파일을 직접 편집하지 않아도 권한을 세밀하게 관리할 수 있게 해줍니다.
/plugin-list - 설치된 플러그인 확인
플러그인을 여러 개 테스트하다 보면 지금 어떤 플러그인이 로드되어 있는지 헷갈릴 때가 있습니다.
/plugin-list는 현재 설치된 플러그인 목록과 활성화 상태를 보여줍니다.
/plugin-list로컬 파일 경로로 플러그인을 테스트하거나, npm 패키지 형태로 설치한 플러그인을 함께 쓸 때 확인용으로 괜찮습니다.
/export-chat - 현재 세션 대화를 마크다운으로 저장
개인적으로 가장 실용적이라고 느끼는 명령어입니다.
AI 코딩 도구를 쓰다 보면 대화 자체가 작업 기록이 됩니다. 어떤 문제를 물어봤고, 어떤 판단을 했고, 어떤 파일을 수정했는지 나중에 다시 봐야 할 때가 있습니다.
opencode에는 /share 명령어가 있어서 대화를 공유 링크로 만들 수 있습니다. 하지만 로컬 파일로 남기고 싶을 때도 있습니다. 예를 들어 팀원에게 전달하거나, 블로그 글을 쓸 때 참고하거나, 작업 기록을 보관하고 싶을 때입니다.
/export-chat를 실행하면 현재 세션 대화를 프로젝트 디렉토리에 마크다운 파일로 저장합니다.
/export-chat
파일 이름은 아래와 같은 형식입니다.
opencode-chat-1715421000000.md저장 위치는 현재 opencode를 실행한 프로젝트 디렉토리입니다. 실행 후에는 토스트 알림으로 전체 저장 경로를 보여줍니다.
예를 들어 아래처럼 프로젝트 폴더에서 opencode를 실행했다면,
cd ~/projects/my-app
opencode파일은 대략 아래 위치에 저장됩니다.
~/projects/my-app/opencode-chat-1715421000000.md처음에는 파일명만 보여주게 만들었는데, 직접 써보니 어디 저장됐는지 헷갈렸습니다. 그래서 전체 경로가 토스트에 표시되도록 수정했습니다.
/session-diff - 현재 세션에서 바뀐 파일 보기
AI에게 여러 번 작업을 시키면 어느 파일이 바뀌었는지 한 번에 보고 싶을 때가 있습니다.
git status나 git diff를 직접 치면 되긴 하지만, opencode TUI 안에서 빠르게 확인하고 싶을 때도 있습니다.
/session-diff이 명령어는 현재 세션에서 변경된 파일 목록을 보여주고, 각 파일의 추가/삭제 라인 수도 같이 표시합니다.
src/index.tsx (+6/-1)
src/plugins/export-chat.tsx (+98/-0)AI가 여러 파일을 수정했을 때 작업 범위를 빠르게 확인하는 용도로 좋습니다.
/session-todos - 세션 todo 확인
opencode 세션 안에서 todo가 생길 때가 있습니다. 작업이 길어지면 남은 일이 뭔지 다시 확인하고 싶을 수 있습니다.
/session-todostodo가 없는 세션에서는 없다고 알려주고, todo가 있는 세션에서는 목록을 dialog로 보여줍니다.
GitHub와 npm 저장소
https://github.com/Blue-B/opencode-tui-utilsGitHub 저장소는 위에 있습니다.
https://www.npmjs.com/package/opencode-tui-utilsnpm 패키지는 위에서 확인할 수 있습니다.
opencode plugin opencode-tui-utils설치는 위 명령어로 하면 됩니다.
앞으로의 방향
지금은 10개의 명령어가 들어있습니다. 하지만 방향은 명확합니다.
opencode가 이미 가지고 있는 정보인데 TUI에서 빠르게 꺼내기 어려운 것, 또는 설정 파일을 직접 수정해야 하는 작업을 작은 slash command로 바꾸는 것입니다.
예를 들어 앞으로는 세션 상태 요약, provider 상태 확인, 작업 기록 정리 같은 기능을 더 추가할 수 있습니다. 단, opencode에 이미 있는 기능을 중복해서 만들기보다는 실제로 빠져 있는 부분만 채워 넣는 것이 목표입니다.
이 프로젝트가 커지면 opencode 사용자들이 자주 겪는 작은 불편을 모아두는 유틸리티 모음이 될 수 있습니다. 동시에 opencode TUI 플러그인을 만들고 싶은 사람들에게는 참고할 수 있는 예제 저장소 역할도 할 수 있습니다.