chojs23/lazyagent

lazyagent는

AI 에이전트(AI agents)가 무엇을 하고 있는지 관찰하기 위한 TUI/웹 앱(tui/web app)입니다. 프로젝트, 세션, 에이전트, 서브에이전트(subagents), 도구(tools), 프롬프트(prompts) 및 출력(outputs)을 한곳에서 검사할 수 있습니다.

이 도구는 일상적인 관측성(observability)을 위해 구축되었습니다. 어떤 세션이 어떤 프로젝트에 속해 있는지, 어떤 에이전트나 서브에이전트가 활성화되어 있는지, 어떤 도구가 실행되었는지, 그리고 그 다음에 어떤 일이 일어났는지 확인할 수 있습니다.

또한 각 에이전트가 자신의 역할에 맞는 작업을 수행하고 있는지 확인하는 데 도움을 주므로, 실행 과정이 경로를 벗어날 때 더 쉽게 발견할 수 있습니다.

각 세션에 대한 토큰 사용량 내역(token usage breakdowns)을 확인할 수 있어, 모델에 사용된 토큰이 얼마인지, 캐시 재사용(cache reuse)을 통해 얼마나 절약되었는지, 그리고 캐시 생성(cache creation)에 사용된 토큰이 얼마인지 확인할 수 있습니다.

멀티 런타임 지원 (Multi-runtime support)-- Claude, Codex, OpenCode 세션을 지원합니다.
서브에이전트 계층 구조 (Subagent hierarchy)-- 어떤 에이전트가 어떤 서브에이전트를 생성했는지 시각적 트리(visual tree) 형태로 볼 수 있습니다.
필터링 기능이 포함된 이벤트 스트림 (Event stream with filtering)-- 이벤트 유형(도구, 사용자, 세션, 시스템, 코드) 또는 에이전트별로 이벤트를 필터링할 수 있습니다. 이벤트 페이로드(event payloads) 전체에 대한 전문 검색(Full-text search)을 지원합니다.
구문 및 차이점 강조 (Syntax and diff highlighting)-- 가독성을 위해 이벤트 페이로드 내의 코드 블록과 차이점(diffs)에 구문 강조(syntax-highlighted)가 적용됩니다.
웹 UI (Web UI)-- lazyagent --web 명령어로 실행하며, TUI와 동일한 데이터를 제공하는 읽기 전용 브라우저 대시보드입니다.

lazyagent는 아직 개발 초기 단계이므로, 일부 중대한 변경 사항(breaking changes)이 발생할 수 있습니다.

npm install -g @chojs23/lazyagent

또는 설치 없이 실행하려면:

npx @chojs23/lazyagent

Homebrew tap을 통해 설치하려면:

brew tap chojs23/homebrew-tap
brew install --cask lazyagent

go install github.com/chojs23/lazyagent/cmd/lazyagent@latest

이 명령어들은 해당 저장소의 flake를 통해 빌드됩니다. 바이너리 버전은 저장소의 VERSION 파일에서 가져오며, 설치되는 정확한 소스 코드는 선택한 ref에 따라 달라집니다.

직접 실행:

nix run github:chojs23/lazyagent

프로필에 설치:

nix profile install github:chojs23/lazyagent

Nix를 통해 특정 릴리스 태그를 고정하려면:

nix run github:chojs23/lazyagent/v0.2.0
nix profile install github:chojs23/lazyagent/v0.2.0

기본값인 github:chojs23/lazyagent는 기본 브랜치 (default branch)를 따르므로, 고정된 릴리스를 사용하려면 태그 참조 (tag ref)를 사용하세요.

최신 릴리스 에셋 (release asset)을 ~/.local/bin에 설치하려면:

curl -fsSL https://raw.githubusercontent.com/chojs23/lazyagent/main/scripts/install.sh | sh

특정 릴리스를 사용자 정의 디렉토리에 설치하려면:

curl -fsSL https://raw.githubusercontent.com/chojs23/lazyagent/main/scripts/install.sh | \
sh -s -- --version v0.2.0 --bin-dir /usr/local/bin

설치 프로그램 옵션:

--version <tag>
또는 --version <tag>

특정 릴리스를 설치하기 위한 VERSION=<tag>

--bin-dir <dir>
또는 --bin-dir <dir>

설치 디렉토리를 선택하기 위한 BIN_DIR=<dir>

go build -o ./bin/lazyagent ./cmd/lazyagent

lazyagent는 보통 런타임 훅 (runtime hooks) 및 플러그인 (plugins)을 통해 사용됩니다.

lazyagent init claude

이 명령은 다음을 업데이트합니다:

~/.claude/settings.json

이는 다음 Claude 훅 (hook) 이벤트들에 대해 lazyagent ingest --runtime claude를 등록합니다:

PreToolUse

PostToolUse

SessionStart

SessionEnd

Stop

SubagentStop

Notification

UserPromptSubmit

기존의 lazyagent가 아닌 훅들은 보존됩니다.

lazyagent init codex

이 명령은 다음을 업데이트합니다:

~/.codex/config.toml
~/.codex/hooks.json

이는 features.codex_hooks = true를 활성화하고, 지원되는 Codex 훅 (hook) 이벤트들에 대해 lazyagent ingest --runtime codex --quiet를 등록합니다.

lazyagent init opencode

이 명령은 OpenCode 플러그인 (plugin)을 다음 위치에 작성합니다:

~/.config/opencode/plugins/lazyagent.ts

원한다면 플러그인을 위해 특정 lazyagent 바이너리 (binary)를 가리키도록 환경 변수 (environment variable)를 설정할 수 있습니다:

LAZYAGENT_BIN

Go 바이너리 (binary) 빌드:

go build -o ./bin/lazyagent ./cmd/lazyagent

Go 테스트 스위트 (test suite) 실행:

go test ./...

유지 관리되는 OpenCode 플러그인 (plugin) 소스에서 직접 작업해야 하는 경우:

cd plugins/opencode
npm install
npm run build

배포되는 플러그인 (plugin)은 Go 바이너리 (binary)에 내장되어 있으므로, 소스를 변경할 때는 유지 관리되는 소스와 내장된 복사본을 동기화 상태로 유지하세요.

인터페이스는 5개의 창(pane)으로 나뉩니다.

Projects (프로젝트)-- 루트 세션(root sessions)과 함께 모든 프로젝트를 나열합니다. 각 세션은 다음과 같은 런타임(runtime) 표시기를 보여줍니다: [C]는 Claude, [X]는 Codex, [O]는 OpenCode를 의미합니다. 활성화된 세션은 애니메이션 스피너(spinner)를 표시합니다.

Session summary (세션 요약)-- 선택된 세션의 메타데이터(metadata)를 보여줍니다: 런타임, 프로젝트 경로, 세션 ID, 시작 시간, 마지막 이벤트 시간, 그리고 이벤트/에이전트(event/agent) 개수.

Agents / subagents (에이전트 / 서브에이전트)-- 선택된 세션의 에이전트 트리(agent tree)를 표시합니다. 활성화된 에이전트는 스피너를 표시합니다.

Events (이벤트)-- 선택된 세션의 이벤트 목록입니다. 각 행은 이벤트 유형(event type), 도구 이름(tool name), 에이전트 ID(agent ID), 그리고 타임스탬프(timestamp)를 보여줍니다.

Event detail (이벤트 상세)-- 선택된 이벤트에 대한 전체 검사(inspection)를 수행합니다. 상태 표시기(status indicators), 메타데이터 필드, 그리고 이벤트 페이로드(event payload)를 보여줍니다.

주요 단축키:

tab, shift+tab: 창(pane) 사이를 이동
1, 2, 3, 4, 5: 특정 창으로 바로 이동
j, k: 목록 이동
g, G: 맨 위 또는 맨 아래로 이동
ctrl+u, ctrl+d: 반 페이지씩 이동
enter, space: 현재 항목 선택
/: 검색 열기
t, shift+t: 이벤트 유형 필터 순환
b: 선택된 세션의 토큰/도구 사용량 오버레이(token/tool usage overlay) 열기
a: 에이전트 창에 포커스가 있을 때 현재 에이전트 필터 삭제
d: 프로젝트 창에서 선택된 프로젝트 또는 세션 삭제
D: 선택된 세션 트리의 이벤트 삭제
F: 이벤트 창에서 자동 따라가기(auto follow) 토글
r: 데이터 새로고침
?: 도움말 토글
q: 종료

• 텍스트를 선택하고 복사하려면 드래그하는 동안 shift 키를 누르세요.

패닉(panic)이 아닌 내부 앱 오류가 발생하면, TUI는 오른쪽 하단에 약 5초 동안 작은 토스트(toast) 메시지를 표시하는 동시에 오류를 lazyagent.log에 기록합니다.

상세 창(Detail pane) 단축키:

J: 원시 JSON(raw JSON) 토글
e: 긴 콘텐츠 블록 확장

터미널에서 lazyagent를 실행하세요:

lazyagent

lazyagent는 TUI와 동일한 SQLite 저장소에서 데이터를 읽어오는 읽기 전용 브라우저 대시보드(browser dashboard)를 함께 제공합니다. 다음과 같이 시작하세요:

lazyagent --web # 127.0.0.1:7777에 바인딩
lazyagent --web --port 8080 # 사용자 정의 포트
lazyagent --web --host 0.0.0.0 # 네트워크에 노출
...

--web 플래그는 설계상 읽기 전용(read-only)입니다. 데이터 수집(ingestion)은 여전히 런타임 훅(runtime hooks)/플러그인(plugins)에 의해 처리됩니다.

프로젝트 그룹화는 자동으로 이루어집니다. lazyagent는 먼저 cwd 또는 project_dir와 같은 작업 디렉터리(working directory)를 기준으로 세션(session)을 매칭하려고 시도하며, 필요한 경우 트랜스크립트(transcript) 경로 정보로 대체(fallback)합니다. 이는 동일한 워크트리(worktree)에서 생성된 Claude, Codex, OpenCode 세션이 대개 동일한 프로젝트 아래로 그룹화됨을 의미합니다.

타입 필터 (Type filter) -- t를 눌러 다음 항목들을 순환하며 선택합니다: All(전체), User(사용자), Message(메시지), Code(코드), System(시스템), Tool(도구), Session(세션).

에이전트 필터 (Agent filter) -- 에이전트 창(agents pane)에서 특정 에이전트를 선택하면 해당 에이전트의 이벤트만 표시됩니다. a를 누르면 필터가 해제되어 다시 모든 에이전트가 표시됩니다.

텍스트 검색 (Text search) -- /를 누르고 패턴을 입력하여 이벤트 페이로드(payload)를 검색합니다.

선택된 세션에서 b를 누르면 토큰 사용량 오버레이(token usage overlay)가 열립니다.

이 오버레이는 가공되지 않은 대시보드(raw dashboard) 대신 컴팩트한 세션 감사 시트(session audit sheet)로 설계되었습니다. 메인 TUI를 아래에 보이게 유지하면서 데이터를 몇 가지 순위가 매겨진 섹션으로 그룹화합니다:

• 세션 (Session) -- 선택된 실행(run)에 대한 런타임(runtime), 세션 라벨(session label), 프로젝트 컨텍스트(project context).
• 개요 (Overview) -- 비용(cost), 모델 호출(model calls), 직접 입력(direct input), 총 입력(total input), 출력(output), 캐시(cache) 수치.
• 시그널 (Signals) -- 캐시 공유(cache share), 출력 비율(output ratio), 주요 모델(top model), 주요 도구(top tool), 주요 명령(top command)과 같은 파생된 힌트.
• 모델 원장 (Model Ledger) -- 점유율(share), 호출(calls), 총 입력(total input), 출력을 포함하여 모델별로 순위가 매겨진 사용량.
• 실행 구성 (Execution Mix) -- 세션에서 사용된 도구(tools) 및 명령(commands)의 순위.
• 모델 호출 (Model Calls) -- 선택된 런타임에 대해 집계된 모델 사용 이벤트.
• 직접 입력 (Direct Input) -- 캐시되지 않은 입력 토큰(non-cache input tokens)만 포함.
• 총 입력 (Total Input) -- 직접 입력 (Direct Input) + 캐시 읽기 (Cache Read) + 캐시 쓰기 (Cache Write).
• 캐시 읽기 (Cache Read) -- 캐시 재사용을 통해 제공된 입력 토큰.
• 캐시 쓰기 (Cache Write) -- 캐시 가능한 프롬프트 상태(cacheable prompt state)를 생성하는 데 사용된 토큰.
• 모델 (Model) -- Total Input의 모델별 total in 버전.

, 즉 직접 입력(direct input)과 캐시 토큰(cache tokens)을 포함합니다. -
도구 사용 (Tool Usage)-- 세션 내에서 어떤 도구가 호출되었으며 각 도구가 몇 번 실행되었는지 나타냅니다. -
셸 명령 (Shell Commands)-- Bash 또는 셸 도구 호출에서 감지된 셸 명령이 무엇인지, 그리고 각 명령이 몇 번 나타났는지 나타냅니다.

lazyagent

런타임(runtime)에 따라 다음 이벤트 유형(event types)을 추적합니다.

유형 (Type)	하위 유형 (Subtypes)	설명
User	UserPromptSubmit	사용자가 프롬프트를 전송함
Message	--	AI 응답 출력
Code	--	코드 변경 작업
System	Stop, SubagentStop, StopFailure, Notification, SessionStatus, PermissionReply, TodoUpdate, CommandExecuted, FileEdited 및 기타	에이전트 중단, 상태, 권한, 할 일(todo), 명령 및 기타 시스템 이벤트
Tool	PreToolUse, PostToolUse, PostToolUseFailure	도구 실행 시작, 성공 또는 실패
Session	SessionStart, SessionEnd, SessionUpdated, SessionDiff	세션 생명주기 (lifecycle)

PreToolUse 또는 PostToolUse 이벤트가 Agent 도구를 포함하는 경우, lazyagent는 자동으로 서브에이전트(subagent) 항목을 생성하고 이후의 이벤트들을 해당 항목에 연결합니다.

런타임 훅(hooks) 및 플러그인(plugins)을 설치하거나 새로고침합니다.

예시:

lazyagent init claude
lazyagent init codex
lazyagent init opencode

표준 입력(stdin)으로부터 런타임 이벤트 페이로드(payloads)를 읽어 데이터베이스에 저장합니다.

이 명령은 일반적으로 수동이 아닌 훅과 플러그인에 의해 호출됩니다.

예시:

lazyagent ingest --runtime claude
lazyagent ingest --runtime opencode
lazyagent ingest --runtime codex --quiet

SQLite 데이터베이스를 열 수 있는지 확인합니다.

lazyagent health

읽기 전용 웹 대시보드(web dashboard)를 제공합니다. 기본값은 127.0.0.1:7777입니다.

lazyagent web
lazyagent web --port 8080
lazyagent web --host 0.0.0.0
...

빌드 및 릴리스 메타데이터(metadata)를 표시합니다.

lazyagent version
lazyagent version --json
lazyagent --version

기본적으로 lazyagent는 다음 경로에 데이터를 저장합니다:

~/.lazyagent

기본 데이터베이스 경로(SQLite):

~/.lazyagent/observe.db

기본 로그 경로 (Default log path):

~/.lazyagent/lazyagent.log

지원되는 환경 변수 (Supported environment variables):

LAZYAGENT_DATA_DIR

• 기본 데이터 디렉터리 (base data directory)를 재정의합니다.

LAZYAGENT_DB_PATH

• 데이터베이스 경로 (database path)를 재정의합니다.
• 이 값이 설정되면, 해당 경로의 상위 디렉터리 (parent directory) 또한 로그를 위한 활성 데이터 디렉터리 (active data directory)가 됩니다.

TUI 새로고침 간격 (TUI refresh interval)은 기본적으로 1초입니다.

버그 리포트 (Bug reports), 기능 요청 (feature requests), 그리고 풀 리퀘스트 (pull requests)를 모두 환영합니다.

기여 가이드는 CONTRIBUTING.md를 참조해 주세요.

MIT