Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
agent-tail은 개발 서버 및 브라우저 콘솔 로그를 로컬 파일로 파이프하여 AI 코딩 에이전트가 읽고 분석할 수 있도록 돕는 도구입니다. 이를 통해 명령 실행, 출력 캡처, 로그 파일 읽기라는 전체 개발 주기 과정을 통합적으로 관리합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기AI 코딩 에이전트(Claude Code, Amp, Cursor 등)가 읽고 grep할 수 있도록 개발 서버 및 브라우저 콘솔 로그를 로컬 머신의 로그 파일로 파이프합니다.
agent-tail demo
사용해보기!
npx agent-tail run 'server: echo "Hello world!"' && cat tmp/logs/latest/server.log
이것이 전체 주기입니다: 명령을 실행하고, 출력이 로그 파일에 캡처되며, 파일을 읽습니다.
전역 설치:
npm install -g agent-tail
프로젝트 설치:
npm install -D agent-tail
전역 설치는 CLI 호출 방식만 변경합니다. 로그는 여전히 기본적으로 현재 프로젝트를 기준으로 tmp/logs/에 저장됩니다.
agent-tail run 'fe: npm run dev' 'api: uv run server'
또는, 프로젝트 로컬 설치를 사용하는 경우:
npx agent-tail run 'fe: npm run dev' 'api: uv run server'
tail -f tmp/logs/latest/*.log
tail -f tmp/logs/latest/browser.log
...
직접 파일 경로를 원하면 일반 tail을 사용하세요. CLI가 최신 세션을 자동으로 해결하기를 원한다면 agent-tail tail을 사용하세요. 이는 -f 및 -n 50과 같은 플래그를 시스템 tail에 직접 전달합니다.
숨겨진 폴더를 선호한다면, CLI의 경우 --log-dir .agent-tail을, Vite/Next.js 플러그인 설정의 경우 logDir: ".agent-tail"을 사용하세요.
agent-tail은 두 가지 종류의 로그를 캡처합니다: 서버 측 출력(개발 명령어의 stdout/stderr)과 클라이언트 측 출력(브라우저 console.* 호출). CLI는 서버 로그를 처리하며 모든 스택에서 작동합니다. Vite 및 Next.js용 프레임워크 플러그인은 브라우저 로그를 처리합니다. 이들을 함께 사용하면 모든 것을 한 곳에서 얻을 수 있습니다.
agent-tail run 'fe: npm run dev' 'api: uv run server'
# tmp/logs/latest/fe.log — Vite 서버 출력
# tmp/logs/latest/browser.log — 브라우저 콘솔 (플러그인을 통해)
...
CLI는 모든 명령어를 감싸서 그 stdout/stderr를 로그 파일에 캡처합니다. 플러그인이나 설정이 필요 없으며, 어떤 언어나 프레임워크와도 작동합니다.
전역 설치:
npm install -g agent-tail
프로젝트 설치:
npm install -D agent-tail
전역 설치를 하더라도 기본적으로 현재 프로젝트의 tmp/logs/에 로그가 기록됩니다. 숨겨진 폴더로 전환하려면 --log-dir .agent-tail을 전달하거나 프레임워크 플러그인에서 logDir: ".agent-tail"로 설정하세요.
여러 명령어를 통합 로깅으로 감싸려면 package.json에 추가하세요:
세션 디렉터리를 생성하고 모든 서비스를 실행하며, 출력 앞에 [이름]을 접두사로 붙이고 개별 및 통합 로그 파일을 작성합니다.
Node에 국한되지 않고 어떤 명령어와도 작동합니다. Python, Go, Ruby 등 터미널에서 실행하는 모든 것:
npx agent-tail run 'api: uv run fastapi dev'
Vite 플러그인은 개발 중에 페이지에 작은 스크립트를 주입하여 브라우저의 console.* 호출을 캡처합니다. 로그는 CLI가 사용하는 동일한 세션 디렉터리의 browser.log 파일에 작성됩니다.
npm install -D agent-tail
// vite.config.ts
import { defineConfig } from "vite"
import { agentTail } from "agent-tail/vite"
...
그런 다음 다른 터미널에서:
tail -f tmp/logs/latest/browser.log
# 또는
agent-tail tail browser -f
Next.js 플러그인은 동일한 작업을 수행합니다. 즉, 브라우저의 console.* 출력을 캡처하지만, Next.js가 설정(config), 레이아웃(layouts), API 라우트(API routes)를 처리하는 방식 때문에 조금 더 많은 연결 작업이 필요합니다.
npm install -D agent-tail
1. Next.js 설정을 감싸기 (Wrap)
// next.config.ts
import { withAgentTail } from "agent-tail/next"
...
2. 레이아웃에 스크립트 추가하기
// app/layout.tsx
import { AgentTailScript } from "agent-tail/next/script"
...
3. API 라우트 생성하기
// app/api/__browser-logs/route.ts
export { POST } from "agent-tail/next/handler"
로그 디렉터리를 .gitignore에 추가하세요:
# .gitignore
tmp/
agent-tail은 로그 디렉터리가 gitignore 되어 있지 않으면 시작 시 경고합니다. warnOnMissingGitignore: false로 비활성화할 수 있습니다.
모든 것을 얻으려면 통합(umbrella) 패키지를 설치하세요:
npm install -D agent-tail
| 패키지 | 설명 |
|---|---|
agent-tail | 통합 패키지 — CLI, Vite 플러그인, Next.js 플러그인을 포함합니다 |
| ... |
로그는 일관된 형식을 가진 일반 텍스트 파일입니다. 타임스탬프, 레벨, 소스 위치, 스택 트레이스 등이 모두 포함되어 있어 사용자가 확인하기 쉽고 AI가 파싱하기도 쉽습니다.
[10:30:00.123] [LOG ] User clicked button
[10:30:00.456] [WARN ] Deprecated API call
[10:30:01.789] [ERROR ] Failed to fetch data (http://localhost:5173/src/api.ts:42:10)
...
레벨은 정렬을 위해 7자로 패딩됩니다. 스택 트레이스는 들여쓰기 됩니다. 에러의 경우 소스 URL이 포함됩니다.
모든 로그 라인이 유용한 것은 아닙니다. HMR 업데이트, 노이즈가 많은 디버그 출력, 프레임워크 내부 정보 등은 AI 컨텍스트를 낭비하는 잡음을 추가합니다. excludes 옵션을 사용하면 이들이 디스크에 기록되기 전에 필터링할 수 있습니다.
// vite.config.ts
agentTail({
excludes: [
...
CLI에서도 반복 가능한 --exclude 플래그를 통해 지원합니다:
agent-tail run --exclude "[HMR]" --exclude "/^DEBUG/" 'fe: npm run dev'
일반 문자열은 부분 일치(substring match)입니다. /로 시작하는 패턴은 정규식으로 파싱됩니다 (예: /^HMR/i).
로그 내용을 필터링하는 --exclude와는 다르게, --mute는 터미널과 combined.log에서 전체 서비스를 침묵시킵니다. 음소거된 서비스도 계속 실행되며 그 출력은 개별 로그 파일에 여전히 캡처되지만, 디버깅 중 다른 작업을 할 때 터미널을 어지럽히지는 않습니다.
agent-tail run --mute fe --mute worker 'fe: npm run dev' 'api: uv run server' 'worker: uv run worker'
터미널에는 api의 출력만 나타납니다. 세 서비스 모두 여전히 fe.log, api.log, 그리고 worker.log에 로그를 기록하므로 에이전트가 모든 것을 읽을 수 있습니다.
--exclude는 내용(예: HMR 메시지)으로 잡음이 많은 로그 라인을 필터링합니다. --mute는 이름으로 전체 서비스를 숨깁니다. 디스크에 기록되는 내용을 정리하려면
--exclude를 사용하세요. 디버깅 중 터미널을 특정 서비스에 집중시키려면--mute를 사용하세요.
대부분의 프로젝트는 프론트엔드, API, 워커 등 여러 프로세스를 실행합니다. agent-tail을 사용하면 이 모든 것을 하나의 세션 디렉터리로 통합할 수 있습니다.
1. agent-tail run 사용 (권장)
모든 것을 하나의 명령어로 실행하세요. 모든 출력은 자동으로 같은 세션으로 전송됩니다.
2. 서비스 개별 래핑(Wrap)
각 서비스를 별도의 터미널에서 실행합니다. wrap 명령어는 기존 세션을 감지합니다:
# Terminal 1: 프론트엔드 시작 (세션 생성)
npm run dev
...
3. 파일 직접 쓰기 (CLI 불필요)
서버의 로깅 출력을 latest 심볼릭 링크를 가리키도록 지정하세요. 모든 언어에서 작동합니다:
import os
import logging
...
import fs from "node:fs"
import path from "node:path"
...
log_dir = File.join(Dir.pwd, "tmp", "logs", "latest")
FileUtils.mkdir_p(log_dir)
...
logDir := filepath.Join(".", "tmp", "logs", "latest")
os.MkdirAll(logDir, 0755)
...
Turborepo, Nx, Lerna 또는 다른 모노레포 러너를 사용하는 경우, agent-tail init을 사용하여 모노레포 루트에 공유 세션을 생성한 다음, 러너가 각 패키지를 시작할 때 agent-tail wrap을 사용할 수 있습니다:
// Root package.json
{
"scripts": {
...
각 패키지의 dev 스크립트는 --log-dir이 루트 로그 디렉터리를 가리키도록 agent-tail wrap을 사용합니다:
// apps/web/package.json
{
"scripts": {
...
agent-tail init은 세션과 latest 심볼릭 링크를 한 번 생성하고, 이후 각 agent-tail wrap은 이 심볼릭 링크를 통해 기존 세션을 발견합니다. 모든 서비스는 동일한 세션 디렉터리(web.log, api.log, worker.log, combined.log, 그리고 프레임워크 플러그인을 사용하는 경우 browser.log)에 기록되며, 모두 tmp/logs/latest/ 안에 위치하게 됩니다.
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
--log-dir 경로는 각 패키지를 기준으로 하므로, 모노레포 깊이에 맞춰 조정해야 합니다. 이 패턴은 여러 패키지를 병렬로 시작하는 모든 러너(runner)에서 작동합니다.
두 가지 방법 모두 사용 가능합니다: 로그 파일 자체에 직접 Unix 도구를 사용하거나, CLI가 최신 세션을 자동으로 해결하도록 agent-tail tail을 사용할 수 있습니다.
# 실시간으로 모든 로그 추적하기
tail -f tmp/logs/latest/*.log
agent-tail tail -f
...
프레임워크 플러그인은 console.* 호출 외에도 더 많은 것을 캡처합니다:
window.onerror) — 전체 스택 트레이스를 포함하여 UNCAUGHT_ERROR로 기록됩니다.UNHANDLED_REJECTION으로 기록됩니다.이것들은 브라우저에서 앱을 조용히 망가뜨리는 오류들입니다. captureErrors: false 및 captureRejections: false로 비활성화할 수 있습니다.
각 agent-tail run (또는 프레임워크 플러그리를 사용한 개발 서버 시작)은 새로운 세션을 생성합니다. 이 세션은 tmp/logs/ 아래에 타임스탬프가 찍힌 디렉토리이며, 해당 실행의 모든 로그 파일을 담고 있습니다. latest 심볼릭 링크(symlink)는 항상 가장 최근 세션을 가리키므로, tmp/logs/latest/는 에이전트에게 제공해야 할 올바른 경로입니다.
2024-01-15T10-30-00-123Z/.gitignore에 없는 경우 경고합니다.agent-tail은 코드베이스에 접근할 수 있는 AI 도구(Claude Code, Cursor, Amp 등)와 가장 잘 작동합니다. 에이전트가 로그 파일을 읽을 때 얻는 정보는 다음과 같습니다:
agent-tail이 없다면, 브라우저 devtools에서 내용을 복사하여 붙여넣고, 에러를 서술("users 페이지에 500 에러가 있다")로 설명하며 에이전트가 맞히기를 바랄 수밖에 없습니다. 또는 실행 중인 연결을 요구하고, grep으로 파이프 처리할 수 없으며, 다른 도구와 조합할 수 없는 구조화된 결과를 제공하는 MCP 브라우저 도구를 설치해야 합니다.
agent-tail을 사용하면, dev 서버를 시작할 때마다 agent-tail이 새 세션 디렉토리를 생성하고 그곳에 tmp/logs/latest/를 심볼릭 링크(symlink)합니다. 에이전트는 grep ERROR tmp/logs/latest/를 실행하여 정확한 스택 트레이스(stack trace), 소스 파일, 라인 번호를 얻게 됩니다. 순수한 파일입니다. 연결 상태도 없고, 도구 등록도 없고, 토큰 오버헤드도 없습니다. 에이전트는 이미 파일을 읽는 방법을 알고 있습니다.
AI 코딩 에이전트에게 agent-tail을 설정하고 사용하는 방법에 대한 내장 지식을 제공하려면 다음 agent-tail 스킬을 설치하세요:
npx skills add gillkyle/agent-tail
이 스킬은 로그 캡처, 런타임 에러 디버깅 또는 콘솔 출력 확인에 대해 질문할 때 자동으로 활성화됩니다. Claude Code, Cursor, Codex 및 기타 지원되는 에이전트와 함께 작동합니다.
또는 프로젝트의 agent 지침 파일(CLAUDE.md, .cursorrules, .github/copilot-instructions.md 또는 이에 상응하는 파일)에 수동으로 스니펫을 추가할 수도 있습니다:
## Dev Logs
모든 dev 서버 출력은 `tmp/logs/`로 캡처됩니다. 최신 세션
...
모든 옵션은 합리적인 기본값과 함께 선택 사항입니다.