처음 열어서, 첫 커밋까지

설치와 첫 실행

다운로드 페이지에서 받습니다. 맥은 .dmg — macOS 13 Ventura 이상, Apple Silicon과 Intel 모두 같은 설치본입니다. 리눅스는 .AppImage 한 파일이고, 받아서 실행 권한을 주면 그대로 돕니다.

어느 쪽이든 앱이 스스로 갱신합니다 — 새 버전이 나오면 알림 카드가 뜨고, 받아서 검증하고 적용한 뒤 다시 켭니다. 설치 파일을 다시 받을 일은 없습니다.

설치 직후 필요한 것은 git 하나뿐입니다. 에이전트를 쓸 생각이라면 쓰던 CLI(Claude Code, Codex 등)가 PATH에 있으면 됩니다 — codeme는 무엇도 대신 설치하지 않고, 이미 있는 것만 씁니다. 언어 서버, 데이터베이스 클라이언트, 도커도 같은 규칙입니다.

첫 실행에서 로그인 화면은 없습니다. 계정이 없기 때문입니다.

VS Code · IntelliJ 에서 왔다면

codeme 는 IDE 를 대신하지 않습니다. worktree 는 평범한 폴더라 쓰던 IDE 로 그대로 열립니다 — 큰 리팩터링은 IDE 에서 하고, 에이전트 여럿을 돌리고 결과를 읽는 일만 여기서 하면 됩니다. 손에 익은 것은 대부분 그대로 옵니다.

• 단축키 — 기본은 IntelliJ 배치입니다. workbench.keymap 을 vscode 로 바꾸면 VS Code 배치가 됩니다. 두 제품이 실제로 싣는 키맵 파일에서 옮겨 왔고, 두 표는 단축키에 있습니다.
• 안 맞는 키 — 설정의 「단축키」에서 명령마다 원하는 조합을 눌러서 기록합니다. 이미 다른 명령이 쓰던 키라면 저장하기 전에 누구의 키인지 알려 줍니다. 저장되는 곳은 workbench.keybindings 한 줄입니다.
• 디버그 설정 — .vscode/launch.json 이 있으면 그대로 읽습니다. 새로 만든다면 자리는 .codeme/launch.json 입니다.
• 언어 서버 · 포매터 · 린터 — 이미 깔린 것만 씁니다. 포매터와 린터는 프로젝트가 선언한 것을 저장할 때 돌리고, 선언이 없으면 아무것도 돌리지 않습니다.

프로젝트 열기

사이드바 위쪽의 프로젝트 목록에서 폴더를 엽니다. 최근 목록은 CtrlR 로 다시 부릅니다. 프로젝트는 여러 개를 동시에 열어 둘 수 있고, 각 프로젝트 아래에 그 프로젝트의 worktree가 쌓입니다.

사이드바 배치는 두 가지 중에 고릅니다 (workbench.sidebar):

• two-rails — 왼쪽에 프로젝트마다 worktree, 오른쪽에 파일. 기본값입니다.
• one-rail — 프로젝트 · worktree · 파일이 왼쪽 한 줄에 쌓입니다.

다음에 열 때 마지막 프로젝트로 돌아갈지는 workbench.restoreLastProject가 정합니다.

worktree 만들기

프로젝트 행의 ＋ 로 worktree를 만듭니다. 브랜치 이름을 새로 주면 그 브랜치를 만들면서 worktree를 함께 만들고, 이미 있는 브랜치를 고르면 그 브랜치의 worktree만 만듭니다.

여러 worktree 나란히

worktree 마다 개발 서버를 띄워 두면, 레일의 카드가 각자의 상태를 말해 줍니다.

• 포트 — 그 worktree 가 켠 서버의 포트가 카드에 :5173 처럼 붙고, 카드의 ⋯ 메뉴나 우클릭 메뉴에서 바로 엽니다.
• CI — 그 브랜치에서 연 PR 의 CI 결과가 「✓ CI」 · 「✕ CI」 · 「… CI」로 붙습니다. 지금은 GitHub PR 만 됩니다.
• 부딪힘 — origin/main 에 합치면 충돌할 파일이나 다른 worktree 도 고치고 있는 파일이 있으면 카드에 경고가 붙습니다. 1분마다, 그리고 창으로 돌아올 때 다시 잽니다(git 2.38 이상).
• 포트 겹침 막기 — git.worktreeShiftPorts 를 켜면 새 worktree 로 복사한 .env 같은 설정 파일의 포트를 다른 worktree 와 겹치지 않게 옮깁니다. 기본은 꺼져 있습니다.

개발 서버는 브라우저 탭으로 코드 옆에 띄웁니다. 탭 줄의 ＋ 메뉴나 포트 패널의 「열기」로 열고, 주소창에 3000 만 넣어도 localhost 가 열립니다. 개발자 도구도 그 탭 안에 붙습니다.

리뷰 패널에서 PR 을 읽다 고칠 것이 보이면, 그 브랜치의 worktree 에 에이전트가 있을 때 스레드마다 「에이전트에 붙여넣기」로 코멘트를 그대로 넘깁니다.

에이전트 붙이기

worktree 카드의 ＋ 메뉴에서 에이전트를 고릅니다. 이 메뉴는 두 가지를 다른 항목으로 보여 줍니다.

• 새로 시작 — 빈 세션을 엽니다.
• 이어서 — 그 worktree에서 돌던 세션을 이어 받습니다.

목록에 무엇이 뜨는지는 이 기계에 실제로 설치된 것이 정합니다. 직접 손보고 싶으면 agents.offered로 후보를, terminal.agents로 각 항목이 실행할 명령을 바꿉니다.

그보다 오래된 대화는 같은 메뉴의 에이전트 이름 아래에 있습니다. Claude Code 와 Codex 가 자기 파일에 남긴 지난 대화를 골라 그 자리에서 이어 시작합니다 — 앱은 그 파일을 읽기만 합니다. 시작 화면의 하던 것 이어서에는 최근 다섯 개가 먼저 뜹니다.

앱을 다시 켤 때 돌던 세션을 자동으로 이어 받을지는 agents.resumeOnRestart가 정합니다.

에이전트가 돌고 있는지, 나를 기다리는지는 메뉴 막대에 숫자로 뜹니다. 창이 앞에 없을 때는 OS 알림이 대신 말합니다 — 창이 앞에 있을 때는 모서리 토스트가 그 일을 하므로 기본값은 알림을 보내지 않는 쪽입니다.

갈래가 여럿일 때 쓰는 것이 둘 있습니다.

• 여러 에이전트에게 한 번에 (⌘⌥⇧A) — 같은 지시를 고른 세션들에 함께 보냅니다. 「main 을 머지해 줘」를 네 번 타이핑하지 않습니다.
• 에이전트 출력에서 찾기 (⌘⌥⇧F) — 세션을 가로질러 찾습니다. 그 얘기를 어느 세션에서 했는지는 탭을 하나씩 열어 보며 찾던 것입니다.

일 맡기기와 검사

Ctrl⌥Q 가 큐입니다. 자리를 비우기 전에 할 일을 적어 두면, 일마다 브랜치 · worktree · 에이전트가 하나씩 생기고 한 번에 하나씩 돕니다. 일마다 방식을 고릅니다.

• 한 번 돌고 끝내기 (기본) — 에이전트가 답을 내고 멈춥니다. 돌아와서 결과만 읽습니다.
• 열어 두고 지켜보기 — 보통 세션처럼 열려 있어서 중간에 끼어들 수 있습니다.

갈래를 2 이상으로 올리면 같은 지시가 최대 여덟 갈래로 따로 돕니다. 끝난 것들을 견주어 보고 한 갈래에서 이것만 남기기를 누르면 나머지 갈래의 worktree 와 브랜치가 지워집니다. 커밋하지 않은 변경이 있는 갈래는 지우지 않고 목록으로 보여 줍니다 — 그래도 지우는 것은 한 번 더 눌러야 합니다.

에이전트가 멈추면 검사가 그 worktree 에서 돕니다. 따로 적는 설정 파일은 없습니다 — package.json 의 typecheck · lint 스크립트와, 테스트 패널이 찾아내는 러너가 곧 검사 목록입니다. 그중 이 기계에 설치된 것만 돌고, 처음 빨개진 곳에서 멈춥니다. 큐로 맡긴 일은 늘 검사를 거칩니다. 보통 세션까지 검사하려면 agents.gate 를 켭니다(기본은 꺼짐). 손으로 돌리고 싶으면 worktree 카드의 검사 버튼을 누릅니다.

다른 앱에 있을 때 무엇을 알려 줄지는 notify.events 가 정합니다.

• waiting — 에이전트가 내 답을 기다립니다.
• finished — 에이전트가 일을 끝냈습니다. 기본으로는 꺼져 있습니다.
• review — 리뷰 요청이 왔습니다.
• checks — 에이전트가 부른 검사가 빨개졌습니다. 초록은 알리지 않습니다.
• mine — 내 PR 이 실패했거나, 변경 요청을 받았거나, 승인됐습니다. 같은 일은 한 번만 말합니다.

남은 사용량 읽기

상태바(또는 툴바)의 사용량 칩은 쓴 양이 아니라 남은 양을 말합니다. 이 앞에서 하는 질문은 "지금 큰 걸 시작해도 되나"이고, 30% 남았다는 말은 그 질문에 바로 답하지만, 70% 썼다는 말은 머릿속에서 한 번 빼야 답이 나오기 때문입니다.

칩에 마우스를 올리면 두 줄짜리 카드가 열립니다.

• 세션 — 지금 쓰고 있는 창. 칩이 보여 주는 숫자가 이것입니다.
• 주간 — 며칠 단위로 발목을 잡는 쪽. 카드에만 있습니다.

숫자 앞의 ~는 서버가 알려준 값이 아니라 이 기계에서 잰 값이라는 뜻입니다. 막대도 실선 대신 줄무늬로 그려집니다. 재는 기준은 최근 며칠 중 가장 바빴던 창이고, 자기 플랜의 실제 한도를 알고 있다면 agents.claudeWindowTokens · agents.claudeWeeklyTokens에 적어 두면 그 값이 이깁니다.

칩 자체를 끄거나 상태바와 툴바 중 어디에 둘지는 agents.usage와 agents.usagePlace로 정합니다.

바뀐 것 읽기

Ctrl⇧X 로 에이전트 변경 패널을 엽니다. 왼쪽에 에이전트가 건드린 파일, 오른쪽에 그 파일의 diff입니다.

• 기준점은 에이전트가 시작한 순간입니다. 그 전에 내가 해 둔 편집은 섞이지 않습니다.
• hunk 사이의 접힌 줄은 펼쳐서 "이 세 줄이 어느 함수 안인지"까지 봅니다.
• 좌우 분할 보기로 바꿀 수 있고, 가운데 경계를 잡아 끌면 한쪽을 넓힙니다.
• diff 머리줄의 크게 보기는 diff 를 창만 한 다이얼로그로 엽니다 — 히스토리 · 커밋 · 워크트리 견주기 패널에도 같은 버튼이 있습니다.
• 다 읽었으면 검토함으로 기준점을 앞으로 옮깁니다.

옆에 두고 읽는 것이 둘 더 있습니다. 문제 (⌘⇧M) 는 언어 서버가 이 프로젝트에 대해 말한 것을 한 목록으로 모읍니다 — 파일을 열어 봐야 알던 것입니다. 워크트리 견주기 (Ctrl⌥C) 는 갈래 둘을 나란히 놓고 무엇이 다른지 봅니다. 같은 일을 시킨 에이전트 둘 중 어느 쪽을 남길지가 그 앞에서 하는 질문입니다.

커밋과 푸시

Ctrl⇧G 가 커밋 패널, Ctrl⇧H 가 히스토리 그래프입니다. 스테이징 · 커밋 · 푸시가 한 자리에 있고, 푸시는 커밋과 같은 화면에 삽니다 — 커밋하고 나서 밀어 올릴 곳을 따로 찾아가지 않습니다.

히스토리는 브랜치가 갈라지고 합쳐지는 모양을 그대로 그립니다. 십만 커밋짜리 저장소로 실측했습니다.

받아오기가 merge인지 rebase인지는 git.pullMode가 정합니다. 충돌이 나면 양쪽을 나란히 놓고 한 덩어리씩 고르는 화면이 열립니다.

지금 바꾼 것을 버리지도 커밋하지도 않으려면 커밋 패널의 변경 전부 임시 보관을 누릅니다. 추적하지 않던 새 파일까지 같이 보관되고, 아래의 임시 보관한 변경 목록에서 되돌리거나 버립니다. worktree 를 지울 때도 임시 보관하고 삭제를 고를 수 있습니다.

히스토리에서 커밋 하나의 되돌리기…는 네 가지를 묻습니다. revert 는 그 커밋을 거꾸로 하는 커밋을 하나 더 쌓고, reset 은 soft · mixed · hard 로 브랜치를 그 커밋까지 되돌립니다. hard 는 작업 트리까지 지우므로 한 번 더 확인합니다. 히스토리 위의 커밋 검색 상자(패널에서 ⌘F)는 sha · 작성자 · 제목 · 브랜치 이름으로 전체 이력을 찾습니다.

로컬 히스토리

앱에서 파일을 저장할 때마다 저장하기 전의 내용을 남깁니다. git 은 커밋한 것만 기억하므로, 커밋과 커밋 사이에 이 파일이 무엇이었는지 — 에이전트가 덮어쓰기 전, 내가 지우기 전 — 는 여기에만 있습니다.

• Ctrl⌥⇧H 또는 툴바의 로컬 히스토리 — 이력이 있는 파일을 트리로 봅니다.
• 에디터 머리줄의 버튼, 또는 파일 트리의 오른쪽 클릭 메뉴 — 그 파일 하나의 버전들을 봅니다.

버전을 고르면 지금 내용과의 diff 가 나오고, 이 버전으로 되돌리기가 그 내용을 다시 씁니다. 쓰기 직전에 디스크에 있던 것도 한 버전으로 남으므로 되돌린 것을 다시 되돌릴 수 있습니다. 그 파일에 저장하지 않은 편집이 있으면 되돌리지 않고 먼저 저장하라고 말합니다 — 그 편집은 어디에도 남아 있지 않기 때문입니다.

테스트 · 빌드 · 컨테이너 · 데이터베이스

에이전트가 고친 코드가 초록인지, 빌드가 지나가는지, 붙어야 할 서비스가 떠 있는지, 그 안의 행이 어떻게 생겼는지는 전부 터미널에서 끝나던 질문입니다. 네 패널이 그 질문들을 맡습니다.

테스트 패널도 빌드 패널도 실행한 명령을 그대로 보여 줍니다. 결과가 뜻밖일 때 그것이 앱의 의견인지 러너의 출력인지 한눈에 갈리게 하기 위해서입니다.

빌드 패널의 작업 목록은 Gradle 자신에게 물어서 채웁니다 — 여기에 적어 둔 목록이 아니라 gradle tasks --all 의 답이라, Spring 프로젝트면 bootRun 이 거기 있고 아닌 프로젝트면 없습니다. Maven 은 물어볼 방법이 없으므로 라이프사이클을 씁니다. 빌드가 실패하면 컴파일 오류가 줄 목록으로 따로 나오고, 한 줄을 누르면 그 파일의 그 줄이 열립니다 — 사백 줄을 스크롤해서 세 줄을 찾는 일이 터미널에서 하던 일입니다. 목록은 화살표로 다니고 Return 으로 엽니다.

디버그

⌘⇧D 가 실행과 디버그 패널입니다. 디버그하는 것은 Go · Python · Java · C · C++ · Rust 이고, 어댑터는 테스트 · 빌드와 같이 이미 깔린 것만 씁니다.

무엇을 띄울지는 이 순서로 찾습니다 — .codeme/launch.json, 그다음 .vscode/launch.json, Rust 면 cargo 에게 물은 바이너리와 테스트, 마지막으로 열려 있는 파일. 두 launch.json 은 VS Code 와 같은 형식이고 이름이 겹치면 .codeme 쪽이 이깁니다. 쓰는 것은 "request": "launch" 뿐입니다 — 이미 돌고 있는 프로세스에 붙는 attach 는 아직 없습니다.

중단점은 에디터 여백을 눌러 겁니다(F9). 오른쪽 클릭하면 셋 중 하나로 바꿉니다 — 이 조건일 때만 멈춤, 이 횟수일 때만 멈춤, 멈추지 말고 출력(로그포인트). 걸어 둔 중단점은 앱을 다시 켜도 남고, 프로젝트 폴더에는 아무것도 쓰지 않습니다. 패널에는 호출 스택 · 변수 · 감시식 · 예외에서 멈추기가 있습니다.

F5 시작 · 계속, ⇧F5 멈춤, F10 한 줄, F11 안으로, ⇧F11 밖으로.

내 작업 연결 (선택)

Ctrl⇧Y 로 내 작업 패널을 엽니다. 리뷰 요청이 위, 내가 맡은 것이 아래입니다. GitHub · Forgejo · Gitea · Bitbucket · Jira를 각자의 API로 직접 읽습니다.

연결은 브라우저에서 로그인합니다. 토큰을 만들러 각 서비스의 설정으로 갔다가 어느 권한을 켜야 하는지 읽고 복사해 오는 일은 하지 않아도 됩니다. 서비스마다 요구하는 것이 달라서 길은 셋입니다.

• GitHub — 브라우저에 코드를 한 번 적습니다. 우리 서버를 거치지 않습니다.
• Forgejo · Gitea — 이 컴퓨터로 되돌아오는 주소를 씁니다. 역시 거치지 않습니다.
• Bitbucket · Jira — 그 둘이 다 막혀 있어, 토큰을 바꾸는 그 한 번만 사이트가 대신합니다. 암호화되어 10분간 놓였다가, 로그인을 시작한 앱이 한 번 가져가면 그 자리에서 지워집니다.

토큰 상자는 없어지지 않았습니다 — 등록되지 않은 자체 호스팅 인스턴스에서는 그대로 그것이 뜹니다. 만료되는 토큰(Bitbucket 은 두 시간)은 거절당했을 때 한 번 갱신하고 다시 묻습니다.

• 토큰은 OS 자격증명 저장소에 들어갑니다 — 맥은 키체인, 윈도우는 자격 증명 관리자, 리눅스는 Secret Service. 여러 곳에 로그인해도 항목은 하나라, 키체인이 묻는 것도 한 번뿐입니다.
• 설정 파일에는 주소만 남습니다. 어떤 IPC 명령도 토큰을 창으로 돌려주지 않습니다.
• 로그인되지 않은 연결은 실패가 아니라 호출한 주소 한 줄 + 로그인 버튼으로 표시됩니다.

PR 하나를 클릭하면 브라우저에서 열거나, 그 PR의 브랜치로 worktree를 만듭니다. 이 머신에 없는 브랜치면 가져온 다음 만듭니다.

티켓도 같습니다. 티켓에서 만든 worktree 의 브랜치 이름은 work.branch 틀을 따르고, 그 worktree 에서 PR 을 열면 본문이 그 티켓으로 채워집니다. 에이전트에 붙여넣기는 티켓 내용을 그 worktree 의 에이전트 입력칸에 넣기만 하고 보내지는 않습니다 — 한 줄 더 적고 보내는 것은 내가 합니다.

패널 위의 대시보드는 지금 스프린트가 얼마나 끝났는지와, 무언가를 기다리며 막혀 있는 티켓을 말합니다. 티켓을 열면 댓글 · 이력 · 하위 작업 · 연결된 이슈 · 첨부까지 앱 안에서 읽고, 담당자를 바꿉니다. PR 줄은 검사가 통과했는지와 승인됐는지를 같이 적습니다. 보드는 디스크에 남아서, 창을 열면 지난번에 읽은 것이 먼저 뜹니다.

Ctrl⌥Y 는 리뷰 패널입니다. 나에게 리뷰를 요청한 PR(GitHub · Forgejo)을 앱 안에서 읽고, 줄마다 할 말을 달고, 총평과 함께 승인 · 변경 요청 · 댓글 중 하나로 한 번에 보냅니다. 내 PR 에는 댓글만 답니다.

보기 고르기

테마는 하나입니다. 고르면 코드와 창이 같이 바뀝니다.

창의 사이드바와 툴바는 테마 색으로 칠해지지 않습니다 — 정해진 색 한 쌍이 있고, 테마는 그중 어느 쪽을 쓸지만 정합니다. 시스템을 따라가고 싶으면 workbench.themeLight에 밝은 테마를 하나 고릅니다.

그 밖에 창의 말과 크기를 정하는 것들 — workbench.language(한국어 · English), workbench.fontSize, editor.fontSize, workbench.keymap(IntelliJ · VS Code).

단축키

기본은 IntelliJ 배치이고, workbench.keymap 을 vscode 로 바꾸면 VS Code 배치가 됩니다. 같은 명령이 그 제품의 자리에 붙습니다 — 아래 스위치로 두 표를 오가며 볼 수 있습니다.

막혔을 때

완성 · 호버 · 정의로 이동이 안 됩니다

그 언어의 언어 서버가 이 기계에 설치돼 있어야 합니다 — rust-analyzer, gopls, clangd, pyright-langserver 중 이미 있는 것만 씁니다. 없으면 상태바가 그렇게 말합니다. TypeScript와 JavaScript는 에디터가 자체 서비스로 답하므로 목록에 없습니다.

디버거가 시작되지 않습니다

그 언어의 어댑터가 없는 경우입니다. 패널이 무엇이 없는지 이름으로 말합니다 — Go 는 dlv, Python 은 가상환경의 debugpy, C · C++ · Rust 는 lldb-dap. Java 는 언어 서버에 넣을 플러그인이 따로 필요하고, 받는 명령을 패널이 그대로 보여 줍니다.

데이터베이스 패널이 연결을 거부합니다

그 엔진의 클라이언트가 없는 경우입니다. 패널이 어떤 명령을 찾다가 실패했는지 이름으로 말해 주니, 그것을 설치하면 됩니다.

내 작업 패널이 비어 있습니다

토큰이 없거나 만료됐습니다. 실패가 아니라 호출한 주소 한 줄 + 로그인으로 표시되니, 그 줄에 적힌 주소가 맞는지부터 봅니다.

사용량이 ~로만 나옵니다

서버에서 한도를 받지 못했다는 뜻입니다. 로그아웃됐거나, 그 창에서 아직 한 번도 돌리지 않았거나, 네트워크가 막혀 있습니다. 이때 보이는 숫자는 이 기계에서 잰 추정값입니다.

터미널 글자가 깨집니다

GPU 렌더러가 없는 기계에서는 코어가 그것을 판정해 CPU 렌더러로 떨어집니다. 그래도 이상하면 설정에서 렌더러를 직접 고를 수 있습니다.

그 밖의 문제

설치본을 받은 경로로 알려 주세요. 어떤 진단 데이터도 자동으로 전송되지 않으므로, 무슨 일이 있었는지는 적어 주셔야 압니다.