Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Agenttrail은 코딩 에이전트가 로컬 환경에서 어떤 작업을 수행하는지 실시간으로 시각화하여 보여주는 도구입니다. 여러 터미널의 정보를 하나의 브라우저 탭에 통합하며, Claude Code나 Codex 같은 에이전트의 활동과 파일 변경 사항을 읽어 관측성을 제공합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기AI 코딩 에이전트를 위한 로컬 관측성(Local observability for AI coding agents).
</div>Agenttrail은 프로젝트의 실시간 지도를 그리고 코딩 에이전트들이 어디에서 작업하고 있는지 보여줍니다. 어떤 부분이 변경되고 있는지, 각 세션이 보고한 작업 내용이 무엇인지, 그리고 현재 무엇을 하고 있는지를 한 브라우저 탭에서 확인할 수 있습니다. 여러 터미널 창에서 정보를 조합할 필요가 없습니다.
사용자의 에이전트는 Claude Code나 Codex 같은 도구 내에서 계속 실행됩니다. Agenttrail은 로컬 파일, 사용자의 계획(plan), 그리고 에이전트의 로컬 로그를 읽어 그 증거들을 보여줍니다. 이 도구는 에이전트를 직접 실행하거나, 작업을 할당하거나, 특정 작업이 완료되었다고 결정하지 않습니다.
Agenttrail Map showing live sessions, component progress and file changes
**Node.js 20+**와 로컬 프로젝트 폴더가 필요합니다.
cd your-repo
npx agenttrail
지도는 localhost:5330, 또는 다음 사용 가능한 포트에서 브라우저에 열립니다. 코딩 에이전트 작업을 계속 진행하세요. 이 저장소의 Claude Code 및 Codex 세션은 로컬 로그에서 실행 카드(run cards) 형태로 나타나며, 별도의 설치가 필요하지 않습니다. 파일 변경 사항은 발생하는 즉시 표시됩니다.
관측 기능은 사용자의 저장소를 변경하지 않습니다. 대화형 터미널에서 PLAN.md 없이 시작하면 설정할지 여부를 묻고, 이는 거절할 수 있습니다.
파일 활동(File activity)과 실행 카드(run cards)는 독립적으로 작동합니다. 계획이 없으면, 이 지도는 읽기 전용으로 모든 브랜치와 작업 트리(worktree)를 거쳐 Git으로부터 추론됩니다. 최근 작업이 있는 소수의 브랜치와 작업 트리는 '계획의 카드'로 그려지며, 이는 무엇에서 자라났는지에 따라 트렁크(trunk)로부터 흘러나옵니다. 각 카드는 해당 폴더가 건드린 곳, 최신 커밋, 가장 바쁜 브랜치 대비 창에 표시되는 커밋 막대, 그 안의 모든 에이전트 세션, 그리고 아래쪽에 더 많은 커밋 주제를 보여줍니다. 커밋 주제는 사용자의 장치에 남아 있습니다.
브랜치가 하나인 리포지토리(repo)는 코드 영역만 보여주며, 커밋이 없는 폴더는 일반적인 관찰(Watching) 보기 상태를 유지합니다. 실제 작업과 진행 상황을 위한 계획을 추가하세요.
npx agenttrail init을 실행하고 설정을 검토한 다음, 보드에서 에이전트에게 백필(backfill) 프롬프트를 제공합니다. 이는 CLAUDE.md와 AGENTS.md에 규칙을 추가하고, 시작 계획을 생성하며, 로컬 Claude Code 훅을 제공하고, .agenttrail/를 .gitignore에 추가합니다. 설정 시에만 이 파일들이 작성되며, 일반적인 관찰(watching) 작업에서는 그렇지 않습니다. 비대화형 init은 '예'로 간주하므로, 리포지토리를 구성할 의도가 있을 때만 실행하세요.
이 지도는 PLAN.md에 선언된 의도와 관찰된 파일 변경 사항을 결합합니다. 완료된 컴포넌트는 파일이 다시 변경될 때 빛납니다. 또한 실시간 파일 트리, 종속성 링크(dependency links), 세션 기록(session trails) 및 여러 리포지토리에 대한 개요를 제공합니다. npx agenttrail up은 재부팅 후 저장된 보드를 다시 실행하며, npx agenttrail autostart는 로그인 시 시작 설정을 구성합니다.
# my project
## Capture the audio {#capture}
...
컴포넌트는 안정적인 {#id} 값과 명확하고 소유자가 읽기 쉬운 이름을 사용합니다.
files:는 관측된 쓰기를 해당 컴포넌트에 연결합니다.
[~]은 진행 중을 의미하고, [x]는 완료를 의미하며, [!]는 막힘(stuck)을 의미합니다.
needs:는 의존성 화살표를 그리고, links:는 점선 연결을 그립니다.
by:는 누가 작업을 수행했는지 기록하며, from:은 에이전트의 의도와 로드맵의 의도를 분리합니다.
kind: knowledge는 컴포넌트를 보라색 지식 기관으로 렌더링하고, kind: human은 그것이 사람의 루프에 진입하는 단계임을 나타내기 위해 자체 색상으로 점선 처리합니다. http(s) 주소가 있는 url:은 카드를 클릭 가능하게 만들어 해당 아티팩트를 열어줍니다.
백필된 완료된 작업은 구현 파일을 증거로 인용합니다.
에이전트는 행동하기 전에 계획에 영향을 미치는 결정을 기록합니다.
| 도구 (Tool) | Map의 관측 방식 (How Map sees it) | 얻을 수 있는 정보 (What you get) |
|---|---|---|
| Claude Code | ~/.claude/projects 내 로컬 로그를 자동으로 관측합니다. 훅(Hooks)은 선택 사항입니다. | 세션, 도구 활동, 파일 추적 기록, 서브 에이전트, 그리고 TaskCreate/TaskUpdate 또는 TodoWrite로부터의 작업 목록 |
| ... |
클로드 코드 훅을 사용하지 않아도 세션을 관측할 수 있습니다. 하지만 다음 세 가지를 추가합니다: 몇 초 내에 발생하는 것이 아니라 발생 즉시의 이벤트, 계획이 코드를 따라잡지 못했을 때 에이전트에게 알림을 제공하고, 터미널이 HC_TERMINAL_ID를 설정할 때 Map 데이터에 터미널 ID를 기록하는 기능입니다. 훅과 로그 모두를 통해 관측된 세션은 하나의 실행으로 유지됩니다.
Map은 지난 두 시간 동안 수정된 로그와 각 로그의 최대 2 MiB만 읽습니다. 이 장치에 로그가 없는 클라우드 세션은 표시되지 않습니다. 로컬 로그 형식은 에이전트 버전에 따라 변경될 수 있습니다. 관측성 작동 방식 (How observability works)
Herdr 데스크톱 앱용 모드는 Map을 에이전트 옆에 네이티브로 표시합니다. 이 Map은 PLAN.md의 카드와 커넥터를 사용하며, 사이드 패널 형태로 존재하다가 전체 크기로 확장되며 초점화된 터미널의 레포지토리(repo)를 따라갑니다. 계획(plan)이 없으면 git에서 가져온 간단한 뷰로 대체됩니다. 읽기 전용만 가능합니다. herdr/README.md를 참조하세요.
Map은 127.0.0.1에 바인딩됩니다. 계정(account), 원격 측정(telemetry), 스크립트 업로드, 모델 호출 또는 클라우드 서비스가 필요 없으며, 에이전트 로그를 읽기 전용으로 엽니다. 실행 카드(Run cards)는 간소화된 명령어 텍스트, 검색어 및 기타 도구 세부 정보를 보여줄 수 있으며, Map은 최근 활동을 ~/.agenttrail 아래에 저장합니다. 녹화본을 공유하기 전에 보이는 내용을 검토하세요. Data sources and local storage
Map은 의존성 없는(dependency-free) Node 데몬이자 정적 페이지입니다. 에이전트를 제어하거나, 프롬프트를 보내거나, 작업을 승인하거나, 그들의 작업을 완료로 표시하지 않습니다.
Agenttrail이 에이전트 프레임워크인가요? 아닙니다. 사용자는 기존 도구에서 에이전트를 실행하며, Agenttrail은 그들이 수행하고 있는 작업에 대한 이용 가능한 증거를 보여줍니다. 토큰 청구(Token billing) 및 전체 모델 추적(full model traces)은 구현되지 않았습니다.
기존 레포지토리에서 작동할까요? 예, 해당 폴더에서 실행하세요. Git과 PLAN.md는 선택 사항입니다.
세션이 누락된 이유는 무엇인가요? 새 세션은 나타나는 데 약 10초가 걸릴 수 있습니다. 이 세션은 감시 중인 레포지토리 내부에서, 로그가 이 기기에 있어야 작동합니다. 두 시간 동안 조용했던 세션은 실시간 보기(live view)에서 사라집니다.
완료된 작업이 작업물이 배포되었다는 의미인가요? 아닙니다. 이는 에이전트가 작업을 완료했다고 보고했다는 것을 의미합니다. 턴 종료나 파일 변경 역시 결과물을 증명하지 않습니다.
제 레포지토리에서 무엇이 변경되나요? 감시하는 것만으로는 아무것도 변경되지 않습니다. init은 계획(plan)과 에이전트 지침을 생성하고, .claude/settings.local.json에 훅(hook)을 제공하며, .gitignore 항목을 추가합니다.
아직 검증되지 않은 것은 무엇인가요? Windows는 테스트되지 않았습니다. 자동화된 확인은 Linux와 macOS에서 실행됩니다.
Kitchen은 어떻게 되었나요? 이 실험적인 3D 뷰는 프로젝트가 Map에 집중할 수 있도록 폐기되었습니다. 마지막 릴리스는 추가 업데이트 없이 npm에서 agenttrail-kitchen으로 유지됩니다.
프로젝트 코드와 원본 에셋은 MIT 라이선스를 따릅니다.