6개의 AI 코딩 에이전트를 위한 로컬 익스플로러(Local Explorer)를 구축한 방법

AI 코딩 에이전트(AI coding agents)는 소프트웨어 개발의 일상적인 부분이 되어가고 있지만, 그 이력(history)을 다루는 것은 여전히 놀라울 정도로 어렵습니다.

세션은 보통 하나의 특정 도구 내에 머뭅니다. 세션이 길어지거나, 아카이브(archived)되거나, 다른 에이전트로 전환하게 되면, 이전의 결정, 명령, 오류 또는 코드 변경 사항을 찾는 것이 불필요하게 어려워집니다.

저는 원래 저의 Claude Code 세션을 위한 작은 뷰어(viewer)로서 Claudescope를 구축했습니다.
그 이후 이 프로젝트는 6개의 코딩 에이전트에 의해 생성된 세션을 위한 로컬 읽기 전용 익스플로러(read-only explorer)로 성장했습니다:

Claude Code
OpenAI Codex
JetBrains Junie
pi
opencode
GitHub Copilot CLI

이 프로젝트는 오픈 소스이며 GitHub github.com/vladar107/claudescope에서 확인할 수 있습니다.

코딩 에이전트 이력의 문제점

코딩 에이전트는 방대한 양의 유용한 컨텍스트(context)를 생성합니다:

프롬프트(prompts) 및 응답(responses)
명령(commands) 및 도구 호출(tool calls)
생성된 코드(generated code)
파일 편집(file edits)
아키텍처 결정(architectural decisions)
실패한 시도(failed attempts)
디버깅 이력(debugging history)
토큰 사용량(token usage)
프로젝트 메모리(project memory)

하지만, 모든 에이전트는 이 정보를 서로 다르게 저장합니다.

어떤 것은 JSONL 파일을 사용합니다. 어떤 것은 SQLite를 사용합니다. 이들의 스키마(schemas), 디렉토리 구조(directory structures), 도구 호출 형식(tool-call formats), 그리고 메타데이터(metadata)는 모두 다릅니다.

데이터는 존재하지만, 이는 다음과 같은 질문에 답하려는 개발자가 아닌 에이전트 런타임(agent runtime)에 최적화되어 있습니다:

왜 이 구현 방식이 선택되었는가?
어떤 세션에서 이 변경 사항이 도입되었는가?
어떤 명령이 이 문제를 해결했는가?
이 프로젝트의 비용은 얼마나 들었는가?
이 저장소(repository)에서 이전에 작업한 에이전트는 누구인가?
에이전트가 향후 세션을 위해 어떤 컨텍스트를 보존했는가?

grep을 사용하여 원본 파일(raw files)을 검색하는 것도 가능하지만, 세션에 중첩된 도구 호출(tool calls), 긴 출력(long outputs), 하위 에이전트(subagents), 생성된 디프(diffs), 그리고 서로 다른 형식을 사용하는 여러 에이전트가 포함되기 시작하면 이는 빠르게 불편해집니다.

Claude 뷰어에서 멀티 에이전트 익스플로러로

첫 번째 버전은 오직 Claude Code 트랜스크립트(transcripts)만 이해할 수 있었습니다.

더 많은 에이전트를 지원하려면 내부 모델을 변경해야 했습니다. Claudescope는 더 이상 Claude의 형식을 애플리케이션 형식으로 취급할 수 없었습니다.

대신, 이제 각 에이전트는 다음과 같은 역할을 담당하는 커넥터(connector)를 가집니다:

로컬 세션 저장소(local session storage) 위치 파악
아무것도 수정하지 않고 읽기
고유 형식(native format) 파싱
이벤트를 공유 세션 모델(shared session model)로 변환
세션을 프로젝트와 연결

이는 Claude Code, Codex, opencode가 작업한 저장소(repository)가 세 개의 서로 관련 없는 기록이 아니라 하나의 프로젝트로 나타남을 의미합니다.

각 세션은 여전히 에이전트의 정체성을 유지하므로, 출처를 잃지 않고 세션을 필터링하고 비교할 수 있습니다.

다른 에이전트를 추가하는 것은 애플리케이션의 나머지 부분을 변경하기보다는 주로 또 다른 커넥터를 구현하는 문제입니다.

세션을 대화로 읽기

원본 트랜스크립트 파일은 기계에게는 유용하지만, 인간에게는 그다지 즐겁지 않습니다.

Claudescope는 세션을 다음과 같은 요소가 포함된 스레드형 대화(threaded conversation)로 렌더링합니다:

마크다운(Markdown) 렌더링
구문 강조(syntax-highlighted)된 코드
결과와 쌍을 이루는 도구 호출(tool calls)
접을 수 있는 추론(reasoning) 및 긴 출력(long outputs)
하위 에이전트(subagent) 및 사이드체인(sidechain) 턴
첨부 파일
토큰(token) 정보
명령(command) 및 터미널 블록
구문 강조된 파일 디프(file diffs)

Claude Code의 슬래시 명령(slash commands)과 셸(shell) 턴 또한 원본 표현에서 더 깔끔한 명령 및 터미널 블록으로 변환됩니다.

세션이 길어질 경우, 모든 내용을 한꺼번에 렌더링하는 것은 비용이 많이 듭니다. Claudescope는 턴(turns)을 점진적으로 렌더링하며, 매우 큰 도구 출력(tool outputs)은 모두 보기 (Show all) 동작 뒤로 숨겨 처리합니다.

세션 내 검색창도 제공됩니다. 이 검색창은 일반 메시지, 접힌 추론(reasoning), 도구 호출(tool calls), 도구 결과(tool results), 그리고 서브 에이전트(subagent) 콘텐츠를 검색한 뒤, 관련 섹션을 자동으로 확장하여 보여줍니다.

에이전트가 변경한 내용 검토하기

대화 기록은 에이전트 세션의 한 측면일 뿐입니다. 많은 경우, 가장 중요한 출력물은 수정된 파일 세트입니다.

변경 파일 (Files changed) 뷰는 세션 동안 이루어진 편집 사항을 집계하여 코드 리뷰와 유사한 방식으로 보여줍니다:

변경된 파일 탐색 (changed-file navigation)
파일별 추가 및 삭제 사항
차이 통계 (diff statistics)
구문 강조(syntax-highlighted)가 적용된 빨간색 및 초록색 차이(diffs)
지연 로딩(lazily loaded)되는 파일 내용

이는 이전 세션으로 돌아가 전체 대화를 다시 읽지 않고도 실제 효과를 파악하고 싶을 때 유용합니다.

또한 에이전트가 논의한 내용과 최종적으로 변경한 내용을 분리하는 데에도 도움이 됩니다.

모든 세션에 걸친 검색

Claudescope는 정규화된 세션 이벤트 위에 로컬 DuckDB 인덱스를 구축합니다.

전체 텍스트 검색(Full-text search)은 DuckDB BM25를 사용하며, 지원되는 모든 에이전트와 프로젝트에 걸쳐 작동합니다.

결과는 세션별로 그룹화되며 강조된 스니펫(snippets)을 포함합니다. 결과를 선택하면 일치하는 메시지가 있는 원본 세션이 열립니다.

이를 통해 세션 아카이브를 엔지니어링 지식 베이스(knowledge base)로 유용하게 활용할 수 있습니다.

예를 들어, 다음과 같이 검색할 수 있습니다:

몇 주 전에 마주쳤던 에러 메시지
에이전트가 리팩터링(refactored)한 클래스의 이름
다른 세션에서 논의되었던 아키텍처 트레이드오프 (architectural trade-off)
로컬 환경 문제를 해결했던 명령어
유용한 결과를 만들어낸 프롬프트 패턴 (prompt pattern)

새로운 세션이 나타나면 인덱스(index)는 자동으로 갱신됩니다.

에이전트 메모리는 히스토리의 일부입니다

트랜스크립트(Transcripts)가 에이전트 컨텍스트(context)의 유일한 소스는 아닙니다.

서로 다른 에이전트들은 다음과 같은 지침(instruction) 및 메모리(memory) 파일들을 유지하기도 합니다:

CLAUDE.md
AGENTS.md
Copilot 지침 파일 (instruction files)
에이전트별 프로젝트 메모리 (agent-specific project memory)

Claudescope에는 이러한 파일들을 세션 히스토리와 함께 보여주는 메모리 브라우저(memory browser)가 포함되어 있습니다.

Claude Code의 정제된 프로젝트 사실(distilled project facts)의 경우, 메모리 항목이 해당 내용을 생성한 세션으로 다시 연결될 수 있습니다. 이는 메모리를 설명되지 않은 텍스트로 보여주는 대신 출처(provenance)를 제공합니다.

이는 여러 에이전트를 추가한 후에 특히 유용해졌습니다. 지침과 메모리는 동일한 프로젝트를 설명하더라도 여러 파일에 파편화되어 있는 경우가 많기 때문입니다.

이전 세션 이어가기

세션 뷰어(session viewer)가 반드시 또 다른 코딩 에이전트 클라이언트(coding-agent client)가 될 필요는 없습니다.

Claudescope는 읽기 전용(read-only) 상태를 유지하지만, 원래의 에이전트 CLI를 위한 적절한 재개(resume) 또는 포크(fork) 명령어를 생성할 수 있습니다.

명령어를 복사하여 터미널로 돌아가면, 해당 세션을 생성했던 도구에서 세션을 계속할 수 있습니다.

이를 통해 책임 소재를 분리할 수 있습니다:

에이전트는 코드를 실행하고 수정하는 책임을 유지합니다.
Claudescope는 히스토리를 탐색하고 분석하는 책임을 유지합니다.

토큰, 비용 및 효율성 분석

에이전트 세션은 운영 데이터(operational data)이기도 합니다.

Claudescope은 다음 항목들을 추적합니다:

입력 및 출력 토큰 (input and output tokens)
캐시 읽기 및 캐시 생성 (cache reads and cache creation)
예상 비용 (estimated cost)
프로젝트별 비용 (cost by project)
모델별 비용 (cost by model)
에이전트별 비용 (cost by agent)
시간에 따른 활동 (activity over time)
캐시 히트 비율 (cache-hit ratios)

가격 정보는 LiteLLM의 커뮤니티 가격표 (community pricing table)에서 새로고침할 수 있으며, 로컬 오버라이드 (local overrides)도 가능합니다.

새로운 세션 효율성 (session-efficiency) 뷰는 비용에 따라 세션의 순위를 매기며 다음과 같은 컨텍스트를 제공합니다:

응답 횟수 (response count)
응답당 비용 (cost per response)
도구 호출 횟수 (tool-call count)
응답당 도구 수 (tools per response)
캐시 사용량 (cache usage)
통계적 이상치 지표 (statistical outlier indicators)

이는 특정 에이전트나 세션이 객관적으로 "더 낫다"고 선언하기 위한 것이 아닙니다. 대신, 유난히 비용이 많이 들거나 도구 사용이 과도한 세션을 더 쉽게 식별하고 조사할 수 있도록 돕습니다.

세션 내보내기 및 공유

세션은 문서화, 버그 보고 또는 기술적 논의를 위해 마크다운 (Markdown) 형식으로 내보낼 수 있습니다.

트랜스크립트 (transcripts)에는 로컬 경로와 자격 증명 (credentials)이 포함될 수 있으므로, 내보내기 흐름에는 다음 항목에 대한 선택적 비식별화 (redaction) 모드가 포함되어 있습니다:

홈 디렉토리 경로 (home-directory paths)
유력한 비밀 정보 (likely secrets)
민감한 환경 변수 값 (sensitive environment values)

비식별화는 필연적으로 휴리스틱 (heuristic) 방식이므로, 내보낸 콘텐츠는 게시하기 전에 여전히 검토해야 합니다.

설계 단계부터 로컬 및 읽기 전용 방식 적용

코딩 에이전트 트랜스크립트에는 소스 코드, 프롬프트 (prompts), 파일 경로, 명령어, 메모리, 그리고 때로는 비밀 정보가 포함될 수 있습니다.

그러한 이유로, Claudescope은 로컬에서 실행되며 127.0.0.1에 바인딩됩니다.

Claudescope은 모든 에이전트 소스를 읽기 전용 (read-only)으로 취급합니다. 자체적인 영구 상태(persistent state)—주로 DuckDB 인덱스와 가격 파일—는 ~/.claudescope 아래에 별도로 저장됩니다.

트랜스크립트 콘텐츠는 호스팅된 서비스로 업로드되지 않습니다.

서버는 또한 루프백(loopback)이 아닌 Host 헤더를 거부합니다. localhost에만 바인딩하는 것만으로는 악성 웹사이트로부터의 DNS 리바인딩 (DNS-rebinding) 공격을 방지할 수 없으므로, 추가적인 호스트 검증을 통해 로그인 흐름을 도입하지 않고도 로컬 트랜스크립트 (local transcript) API를 보호합니다.

유일한 선택적 외부 요청은 버전 및 모델 가격 확인입니다. 두 요청 모두 트랜스크립트 콘텐츠를 포함하지 않습니다.

설치 (Installation)

Claudescope는 npm, Homebrew, 그리고 Nix를 통해 배포됩니다.

npm

Node.js 22.12 이상의 버전이 필요합니다.

npm install -g @vladar107/claudescope
claudescope

글로벌 설치 없이도 다음과 같이 실행할 수 있습니다:

npx @vladar107/claudescope

Homebrew

brew tap vladar107/tap
brew install claudescope
claudescope

Nix

nix run github:vladar107/claudescope

기본 명령은 애플리케이션을 백그라운드 프로세스로 시작하고 브라우저에서 엽니다.

기타 라이프사이클 (lifecycle) 명령은 다음과 같습니다:

claudescope status
claudescope open
claudescope logs -f
...

첫 번째 출시 이후 변경된 사항

초기 출시는 주로 Claude Code 세션 뷰어였습니다.

그 이후로 Claudescope에는 다음 기능들이 추가되었습니다:

5개의 추가 코딩 에이전트 (coding agents) 지원
통합 멀티 에이전트 프로젝트 (unified multi-agent projects)
Windows 지원
Homebrew 및 Nix 설치 지원
매우 큰 세션에 대한 더 나은 처리
메모리 및 지침 파일 (instruction-file) 브라우저
세션 재개 (resume) 및 포크 (fork) 명령
재구축된 코드 리뷰 스타일의 변경된 파일 (Files changed) 보기
선택적 비식별화 (redaction) 기능이 포함된 Markdown 내보내기
실시간 모델 가격 업데이트
세션 효율성 분석 (session-efficiency analytics)

방향성 또한 약간 변경되었습니다.

목표는 단순히 개별 트랜스크립트를 읽기 쉽게 만드는 것이 아닙니다. 코딩 에이전트의 기록을 도구 전반에 걸쳐 검색 가능하고, 검토 가능하며, 재사용 가능하게 만드는 것입니다.

다음 단계는 무엇인가요?

여전히 가능한 방향은 많습니다.