OYAKATA: AI 세션 관리 앱 개발기

서론

여러 개의 Claude Code 세션을 띄우는 것은 당연한 일입니다. 게다가 여러 리포지토리의 개발을 동시에 진행하거나, 자료 작성을 맡기는 등 엔지니어의 일상에서 AI가 필수적이라는 것은 더 말할 필요도 없습니다.

최근에는 세션 관리를 위한 도구들이 난립하며 편리한 것들이 많이 나오고 있습니다. 하지만 개인적인 사용 편의성 측면에서 완벽한 것은 없었고, 답답함을 느끼면서도 왠지 모르게 직접 만들어보고 싶다는 마음이 생겨 무거운 몸을 일으키게 되었습니다.

그래서 만든 것이 바로 코딩 에이전트 세션을 브라우저에 통합하고, 그 자리에서 지시도 보낼 수 있는 사령탑입니다. 이것의 이름은 OYAKATA(親方) 입니다. 처음에는 Claude Code 용으로 만들기 시작했지만, 지금은 Codex CLI, Gemini CLI, Copilot CLI, OpenCode의 세션까지 같은 화면에 나열됩니다.

왼쪽이 세션 목록(Claude Code・Codex・Gemini・Copilot의 세션이 나열됨), 오른쪽이 에이전트의 답변입니다. 표, 그림, 코드가 그대로 렌더링됩니다.

본문에서는 어떤 점이 불편했는지, Orca나 공식 Agent View 같은 기존 도구들로 왜 해결되지 않았는지 등을 작성해 가겠습니다.

어려웠던 점

어느 터미널에서 무엇이 돌아가고 있는지 알 수 없다

터미널 탭을 4개 열어두면, '어떤 것이 대기 중인지', '어떤 것이 권한 확인으로 멈춰 있는지' 외부에서 파악하기 어렵습니다. 순서대로 탭을 클릭하며 확인해야 합니다. Claude Code는 판단 대기 시 소리를 내주지만, 어느 탭인지는 알려주지 않기 때문에 결국 클릭해서 돌아다녀야 합니다.

시간이 지난 후 터미널을 확인해 보니 Claude가 무언가를 질문하여 작업이 멈춰있었던 경우도 드물지 않습니다.

표와 그림이 터미널에서는 읽기 어렵다

이것이 개인적으로 가장 큰 문제였습니다.

Claude는 요청하면 비교표나 Mermaid 다이어그램을 작성해 주지만, 터미널에서는 보기 불편하거나 복사했을 때 표가 깨지거나, Mermaid 같은 것은 애초에 렌더링 자체가 불가능한 경우가 많았습니다. '그림으로 설명해 달라'고 부탁했는데 결과물이 구분선 문자열의 ASCII 아트로 돌아와서, '틀리진 않았는데 뭔가 다르다...!!'라는 생각이 들곤 했습니다.

긴 답변의 경우, 제목이나 목차가 없어서 답변 시작 부분을 필사적으로 스크롤하며 찾아야 합니다.

도구 호출 로그 때문에 대화가 흐려진다

Claude가 파일을 20번 읽고 테스트를 5번 실행하면, 그에 해당하는 로그들이 대화 사이에 끼어듭니다. 자신이 보고 싶은 것은 '결국 어떻게 판단했는지' 몇 줄인데, 그것이 방대한 Read나 Bash 등의 로그 사이에 파묻혀 있습니다. 터미널의 스크롤백에도 한계가 있습니다.

기존 도구를 시도해 봤다

이러한 불만은 자신만이 아닌 것 같아, 많은 도구들이 존재합니다. 몇 가지를 사용해 보았습니다.

Orca

Orca는 Stably AI에서 만든 'Agent Development Environment'로, Claude Code와 Codex를 각각 다른 git worktree로 병렬 실행하는 데스크톱 앱입니다. 터미널 분할, 차이점 비교(diff), 내장 브라우저, GitHub 연동까지 갖추고 있어 잘 만들어졌습니다. orca-cli를 통해 Claude 자체에게 worktree를 분기시키거나, 코디네이터 역할을 하는 에이전트가 다른 에이전트에게 작업을 위임하게 할 수도 있습니다.

다만, 자신의 사용 방식과는 두 가지 점에서 달랐습니다.

첫째는 Orca에서 시작한 세션만 보인다는 점입니다. Orca는 'Orca에서 태스크를 시작하고 worktree별로 병렬 실행하는' 구조이기 때문에, Orca 외부, 예를 들어 VS Code의 터미널이나 일반 셸에서 시작된 claude 세션은 Orca에서는 보이지 않습니다. 전부 Orca에서 시작하면 해결되지만, 이는 도구에 맞춰 자신의 방식을 바꿔야 함을 의미합니다. (worktree로 작업을 분할하는 메커니즘 자체는 나중에 OYAKATA에도 적용했습니다. 후술하겠습니다.)

둘째는 내용물이 터미널이라는 점입니다. 렌더링은 빠르지만, 보이는 것은 터미널의 문자열이므로 표나 Mermaid를 읽을 수 없는 문제는 그대로 남아있습니다. (Claude의 Artifact로 넘기는 것도 편리했지만, 그것 역시 다루기 어려워 포기했습니다.)

공식 Agent View와 원격 제어 (Remote Control)

Claude Code 본체에도 claude agents로 열 수 있는 Agent View가 추가되었습니다(2026년 5월, 리서치 프리뷰). 백그라운드 세션을 일람하고, 입력이 필요한 것을 찾아 지시를 보낼 수 있습니다. '어떤 것이 멈춰 있는지 알 수 없다'는 문제에 상당히 효과적입니다.

다만 이것 역시 TUI(Text User Interface)이기 때문에, 읽는 사람의 문제는 변하지 않습니다. 또한, Agent View에서 시작된 백그라운드 세션이 대상이며, 자신이 직접 터미널에서 일반적으로 시작한 것과는 별도의 관리 시스템입니다.

Remote Control(/remote-control)은 스마트폰이나 claude.ai/code에서 현재 사용 중인 세션을 조작할 수 있는 메커니즘으로, 외부에서 확인하기에는 이것이 가장 좋습니다. 다만 세션 하나씩 연결하는 구조이기 때문에 '모든 것을 한눈에 보기' 용도로는 적합하지 않습니다.

tmux 계열과 worktree 관리 시스템

Claude Squad, ccmanager, crmux, cmux 등은 tmux의 페인(pane)을 사용하여 세션을 나열하는 접근 방식입니다. maedana 님의 비교 기사 분류로 따지자면 'worktree 관리형'과 '기존 환경 감시형'이 있는데, 제가 원하는 것은 후자에 가까웠습니다.

다만, 제 개발기는 Windows입니다. tmux가 전제 조건인 것은 애초에 작동하지 않거나, WSL(Windows Subsystem for Linux) 안에 가두어야 합니다.

Vibe Kanban이나 Conductor 같은 worktree 관리 시스템은 칸반 보드나 GUI로 작업을 관리하는 구조이며, 이 역시 태스크를 해당 툴에서 시작하고 태스크 단위로 worktree를 분리하는 방향입니다. Conductor는 macOS 전용이라 사용해 볼 수 없었습니다.

원했던 것들

정리하자면, 다음과 같은 조합이 필요했습니다.

• 실행 방식을 바꿀 필요가 없다. 터미널에서 시작한 것도, VS Code에서 시작한 것도 모두 보인다(감시형)
• 브라우저에서 HTML 형태로 읽을 수 있다. 기본적으로 표, 그림, 코드가 렌더링된다.
• 볼 뿐만 아니라, 그 화면에서 지시를 보낼 수 있다. 권한 확인에 대한 답변도 받을 수 있다.
• Windows에서 작동한다.
• 리포지토리를 넘나들며 일람할 수 있다.
• 에디터로서 최소한의 편집 기능이 있어야 한다.

모두 충족하는 것을 찾을 수 없어서 만들게 되었습니다.

만든 것: OYAKATA (親方, 현장 책임자)

이름은 현장 책임자가 현장을 돌아다니며 지시를 내린다는 설정에서 붙였습니다.

할 수 있는 것은 4가지로 요약됩니다.

지원하는 에이전트는 다음 5가지입니다. 포함된 것은 자동으로 찾아 표시하며, 보여줄지 여부는 설정으로 전환할 수 있습니다.

| 에이전트 | 읽는 기록 위치 | 브라우저에서 시작할 때 |
|---|---|
Claude Code | ~/.claude/projects | claude -p (작업 중에도 지시를 끼워 넣을 수 있음) |
Codex CLI | ~/.codex/sessions | codex exec (지시 1개가 1턴) |
Gemini CLI | ~/.gemini/tmp/*/chats | gemini (지시 1개가 1턴) |
Copilot CLI | ~/.copilot/session-state | copilot (지시 1개가 1턴) |
OpenCode | | opencode db를 통해 데이터베이스 연결 |
| | | opencode run (지시 1개가 1턴) |

화면은 일본어와 영어 중에서 선택할 수 있습니다(최초에 질문함).

한눈에 보기 (見渡す)

왼쪽 사이드바에는 현재 실행 중인 세션이 상단에, 그 아래로 리포지토리별 이력이 나열됩니다. 점의 색깔은 상태를 나타내며, 주황색은 작업 중(作業中), 초록색은 대기 중(待機中), 보라색은 판단 대기(判断待ち)입니다. Claude Code 외의 세션에는 'Codex CLI'처럼 에이전트 이름이 표시되고, worktree에서 작업하는 세션에는 ⎇와 브랜치 이름이 붙습니다. 가장 아래에는 '작업 중 1 · 판단 대기 1'과 같이 건수도 표시됩니다.

대기 상태나 판단 대기 상태가 되면 데스크톱 알림을 받을 수 있도록 하여, 다른 일을 하고 있어도 알아차릴 수 있습니다. 작업이 끝나면 장단(拍子木)이 '깡, 깡' 소리를 냅니다. 이것은 순전히 취미입니다.

읽기

툴 호출 로그는 기본적으로 숨겨져 있어 대화 내용만 흐릅니다. 현재 무엇을 하고 있는지는 입력창 위의 한 줄(예: Bash: Run the filter tests … esc로 중단)에서 알 수 있습니다. 로그를 보고 싶다면 설정에서 표시할 수 있습니다.

표는 표대로, mermaid 는 다이어그램으로, 코드는 하이라이트와 함께 렌더링됩니다. 대화 속의 src/main.rs:42 같은 파일 참조는 클릭하면 에디터에서 해당 줄이 열립니다.

지시하기

헤더의 '＋'를 눌러 에이전트와 폴더를 선택하면 빈 채팅창이 열리고, 첫 번째 지시를 보내는 시점에 에이전트가 구동됩니다.

Git 리포지토리에서는 새로운 세션이 기본적으로 전용 worktree에서 작동합니다. OYAKATA는 현재 커밋부터 oyakata/<이름> 브랜치를 잘라내어 ~/.oyakata/worktrees/<리포지토리>/<이름>에 가져가고, 그곳에서 에이전트를 구동합니다. 같은 리포지토리에서 세션을 2개, 3개를 나란히 두어도 서로의 파일이나 현재 체크아웃을 덮어쓰지 않습니다. 목록에서는 원래 리포지토리 아래에 나열되며, 파일 트리・차이(差分)・Git 뷰는 worktree 내부 내용을 표시합니다.

폴더에서 그대로 작업하고 싶을 때는 첫 지시를 보내기 전에 상태 줄의 '⎇'로 전환합니다(설정에서 일괄적으로 끌 수도 있습니다). 작업이 끝나면 세션을 종료하고 채팅의 '⋯' 메뉴에서 'worktree 삭제'를 선택합니다. 폴더가 사라지고 브랜치도 병합되었다면 함께 사라집니다. 병합하지 않았다면 브랜치는 남습니다.

Claude Code의 경우, 작업 중에도 지시를 보낼 수 있으며 다음 툴 호출 분기점에서 전달됩니다. 권한 확인, AskUserQuestion에 대한 답변, 계획 승인은 채팅창 안에 카드로 나타나며, 그곳에서 답할 수 있습니다. 승인하면 주홍색의 '승인', 반송하면 남색의 '반송' 도장이 찍힙니다. 이것 역시 취미입니다.

다른 에이전트는 지시 1개를 1턴으로 작동시키기 때문에, 작업 중에 보낸 지시는 현재 턴이 끝난 후에 다음 턴으로 전달됩니다. 권한 확인 카드는 나타나지 않는 대신, 상태 줄의 권한 모드(auto / acceptEdits / default / plan)가 각 CLI의 샌드박스나 승인 설정에 반영됩니다.

에이전트 체제 시각화

채팅 오른쪽 상단의 '👥'를 누르면 체제도가 열리고, 해당 세션의 메인 에이전트와 Agent 툴로 구동된 서브 에이전트 간의 관계가 트리 형태로 표시됩니다(Claude Code 세션). 서브 에이전트별로 전달된 작업 내용과 현재 작업 중인지 완료했는지 여부가 나옵니다. 작업 중인 것은 지금 실행하는 툴이, 완료된 것은 부모에게 보고한 내용의 시작 부분이 표시됩니다. 같은 타이밍에 병렬로 구동된 서브 에이전트는 하나의 그룹으로 묶이며, 그중 몇 개가 아직 작동하고 있는지도 알 수 있습니다. 표시는 세션 진행에 맞춰 업데이트됩니다.

Agent 툴로 서브 에이전트를 3개 병렬로 돌렸을 때, 터미널에서는 '3개가 돌아가고 있구나' 정도만 알 수 있었는데, 여기서 각자의 진척도를 볼 수 있게 되었습니다.

에디터로서의 기능

![에디터와 차이점과 Git]AI(https://raw.githubusercontent.com/ShintaroOba/oyakata/main/docs/images/workbench.png)

대화 옆에 에디터와 차이점을 열 수 있습니다. 페인은 VS Code처럼 탭을 드래그하여 분할할 수 있으며, 배치는 리포지토리별로 기억합니다. 사이드바의 Git 뷰에서 commit / push / pull까지 가능합니다. worktree에서 작동하는 세션이라면 대상은 그 worktree의 브랜치입니다. Ctrl+P로 파일 검색, F12

디렉토리 정의(定義) 점프도 추가했습니다 (git grep\n\n베이스이기 때문에 언어 서버는 필요 없습니다).\n
"Claude가 worktree에서 수정한 내용. 차이점을 보고 싶다. 문제없다. 커밋하고 푸시하고 싶다"까지 브라우저를 벗어나지 않고 처리할 수 있도록 여기까지 구현했습니다.\n\n## 어떻게 작동하는가\n\n### 각 에이전트의 기록을 읽기만 하면 된다\n\n핵심은 여기서, OYAKATA는 각 에이전트가 남긴 파일을 읽고 있다는 것입니다. Claude Code의 경우 다음과 같습니다.\n\n-\n~/.claude/projects/<cwd>/<session>.jsonl\n\n이것이 대화 본문입니다. 시작 시 한 번 메타데이터(제목, cwd, 왕복 횟수, 토큰, 수정된 파일 등)를 생성하고, 이후에는 증분만 읽어옵니다.\n-\n~/.claude/sessions/<pid>.json\n\n이것은 작동 중인 세션입니다. pid가 살아있는 것을 '작동 중'으로 간주하며, status: waiting을 '판단 대기'로 봅니다.\n-\n<session>/subagents/agent-*.jsonl\n\n이것이 서브 에이전트 기록입니다. 호출한 원본 Agent의 도구 호출과 맞춰서 위의 트리 보기(tree view)에 사용합니다.\n\nCodex CLI, Gemini CLI, Copilot CLI, OpenCode 역시 각각의 기록을 읽어 Claude Code와 같은 형태의 줄로 변환한 후, 동일한 인덱스에 넣습니다. 따라서 표시 측에서는 에이전트별로 분리하여 만들지 않습니다. 이 에이전트들은 작동 중인 기록을 남기지 않으므로, 세션 파일이 20초 이내에 업데이트되면 '다른 프로세스로 실행 중'으로 간주하고 끝날 때까지 읽기만 합니다.\n\n따라서 에이전트 측의 설정이나 시작 방법을 바꿀 필요가 없습니다. 터미널에서 평소처럼 claude나 codex라고 입력한 것도, VS Code 확장 프로그램에서 시작한 것도 모두 목록에 표시됩니다. 이것이 '모니터링형'으로 만든 이유입니다.\n\n### 브라우저에서 시작하는 세션\n\nClaude Code의 경우, '+' 버튼부터 시작된 세션은 claude -p --input-format stream-json --output-format stream-json --permission-prompt-tool stdio의 자식 프로세스입니다. 지시는 stdin으로 흘러가고, 권한 확인은 stdout에 control_request로 반환되므로, 브라우저 카드에서 답하여 control_response를 반환합니다. 대화 자체는 Claude Code가 평소처럼 ~/.claude/projects에 작성하므로, 뷰어 측에서는 다른 세션과 동일하게 그리기만 합니다.\n\nClaude가 작업하는 동안 보낸 지시는 Claude Code 측에서 유지하고 있다가 다음 도구 호출의 경계에서 가져옵니다. 터미널에서 작업 중 입력하는 것과 같은 동작입니다.\n\n다른 에이전트들은 지시마다 codex exec / gemini / copilot / opencode run을 실행하여, 지시를 stdin으로 전달하고 JSON 이벤트 목록으로 상태를 추적합니다. 다음 지시는 동일 세션의 재개로 시작하므로 대화가 연결됩니다. 이 역시 대화는 에이전트 자신이 작성하므로, 표시 경로도 같습니다.\n\n### 새로운 세션은 worktree로\n\n새로운 세션을 Git 리포지토리에서 시작하면, OYAKATA는 먼저 git worktree add -b oyakata/<이름> <폴더> HEAD를 실행하여 해당 폴더에서 에이전트를 시작합니다. 이름은 영어 지시라면 첫 단어부터, 그 외에는 시간으로부터 만듭니다.\n\nworktree의 .git 파일은 원래 리포지토리를 가리키므로, 그것을 따라가서 목록에서는 원래 리포지토리 아래에 나열됩니다. 'worktree 삭제'는 git worktree remove 다음에 git branch -d를 호출하기만 하면 되기 때문에, 병합하지 않은 브랜치는 사라지지 않습니다.\n\nworktree가 잘리는 것은 OYAKATA에서 시작한 세션뿐입니다. 터미널에서 시작한 세션은 지금까지처럼 해당 폴더 그대로 목록에 나옵니다.\n\n### 터미널에서 작동하는 세션에 입력하기 (Windows)\n\n이것은 힘으로 하는 것입니다.

터미널에서 작동하는 Claude Code의 대화 세션에 외부에서 지시를 내릴 공식적인 방법이 없기 때문에, OYAKATA는 사람이 하는 행동을 그대로 합니다. 콘솔 입력 버퍼에 키 입력을 쓰는 방식(AttachConsole + WriteConsoleInputW)을 사용합니다. 입력하기 전에 프로세스의 시작 시간을 대조하여, PID가 다른 프로세스에 재사용되고 있다면 입력하지 않도록 처리했습니다.

Windows 전용이며, 권한 확인은 터미널 측에서 응답해야 하지만, '브라우저로 읽고 그대로 다음 지시를 내릴 수 있게' 되면서 왕복 횟수가 상당히 줄었습니다.

Skill을 통해 에이전트에게 '브라우저로 읽히고 있음'을 전달하기

또 하나 은근하게 효과적인 것이 /oyakata 스킬입니다.

스킬을 호출하면 oyakata가 실행되고 브라우저가 열리는데, 동시에 에이전트에게 '이후의 응답은 브라우저에서 HTML로 렌더링된다. 그림은 Mermaid를 사용하고, 비교는 표로 하며, ASCII 아트는 사용하지 말라'고 전달합니다. 이렇게 하면 처음부터 에이전트 측의 출력이 읽기 쉬운 형태가 됩니다. 터미널에 맞춰 전각 공백으로 너비를 맞추는 같은 일도 없어집니다.

뷰어 측에서 애써 렌더링하는 것뿐만 아니라, 작성하는 쪽(서술자)에게도 '읽히는 방식'을 알려주는 것이 생각보다 효과적이었습니다.

Rust 단일 바이너리

본체는 Rust (axum + tokio)로 작성되었으며, 런타임 의존성이 없는 단일 바이너리입니다. 렌더링에 사용되는 라이브러리(marked, DOMPurify, highlight.js, Mermaid, CodeMirror)들은 바이너리에 포함되어 오프라인으로 작동합니다. 서버는 127.0.0.1에서 대기하며 데이터를 어딘가로 보내지 않습니다.

상시 구동은 하지만, 본문을 메모리에 보유하는 것은 표시 중인 세션만입니다.

사용 방법

Claude Code의 플러그인으로 추가하는 것이 가장 쉽습니다. Rust 빌드는 필요 없습니다.

/plugin marketplace add ShintaroOba/oyakata
/plugin install oyakata@oyakata
/oyakata

첫 사용 시에는 oyakata 명령어가 없으므로, 에이전트가 스킬이 포함된 스크립트를 통해 GitHub Releases에서 빌드된 바이너리(Windows / macOS / Linux)를 넣고 상시 구동을 시작하며, 현재 세션이 열린 상태로 브라우저가 실행됩니다. 처음에 브라우저에서 표시 언어(일본어 / English)를 선택합니다.

Codex CLI・Gemini CLI・Copilot CLI・OpenCode에서 사용할 때는 아래 스크립트로 본체를 넣은 후 oyakata install을 한 번 실행해 주세요. 이러한 에이전트들이 읽는 공통의 스킬 저장소(~/.agents/skills)에 같은 스킬이 배치되어, 'oyakata를 열어줘'라고 요청하면 똑같이 작동합니다.

터미널에서는,

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ShintaroOba/oyakata/main/scripts/install.sh | sh
# Windows
...

`oyakata new

| UI | 보이는 세션 | 표/도 | 지시 보내기 | Windows | |
|---|---|---|---|---|
OYAKATA | 브라우저 | 5종 에이전트의 기록 전체 (어떤 방식으로 시작했는지 불문) | HTML 렌더링 | ◯ 본인이 직접 시작한 것 / 종료됨 / 터미널에서 실행 중인 Claude Code (Windows) | ◯ |
| Orca | 데스크톱(터미널) | Orca에서 시작한 것 | 터미널 문자 | ◯ | ◯ |
Agent View（claude agents ） | TUI | Agent View의 백그라운드 세션 | 터미널 문자 | ◯ | ◯ |
| Remote Control | 스마트폰 / Web | 연결된 단일 세션 | HTML 렌더링 | ◯ | ◯ |
| Claude Squad / ccmanager | TUI（tmux） | 본인이 직접 시작한 것 | 터미널 문자 | ◯ | ✕ |
| ... |~/.claude 전체 | HTML 렌더링 | ✕ | ◯ |

worktree 관리 계열은 '해당 도구에서 시작한 작업을 병렬로 돌리기' 위한 장치이고, OYAKATA는 '어디서 시작했는지 포함하여 현재 실행 중인 것을 보기 쉽게 확인하고 지시하기' 위한 장치라는 차이가 있습니다. 그 위에 더해서, OYAKATA에서 시작하는 세션도 worktree로 분리될 수 있게 되었기 때문에, 같은 리포지토리 내에서 여러 개를 나란히 돌리는 사용 방식도 가능합니다.

맺음말

OYAKATA 자체도 Claude Code와 함께 만들었고, 중반부터는 그 Claude의 작업을 OYAKATA로 보면서 진행하는 순환이 되었습니다. 표나 그림이 깨지지 않고 읽을 수 있게 된 것만으로도, Claude의 답변을 끝까지 제대로 읽게 된 기분이 듭니다. 터미널에서는 긴 답변은 흘려보며 '일단 작동했는지'만 보고 있었기 때문입니다.

Windows에서만 동작하는 부분 등이 편향된 도구이지만, 같은 어려움을 겪는 사람에게 도움이 되었으면 좋겠습니다. 앞으로도 확장은 계속할 것이지만 Issue나 PR은 환영합니다.

Discussion