Skip to content
프로젝트

mjjo16/marmonitor has 27 GitHub stars and 8 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 20:33 UTC. Last push 2026-11-08.

이 수치를 측정하는 방법

측정된 스타 증가

in 24h
0
in 7 days
업데이트 지연
in 15 days
업데이트 지연
in 1 month
업데이트 지연

서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.

소개

tmux status bar monitor for AI coding agents — track Claude, Codex, Gemini sessions in real time

개발 도구

README.ko.md

Original

marmonitor

Claude Code · Codex · Gemini용 tmux 상태바 모니터 — AI 코딩 세션을 실시간으로 추적하세요

npm version license node version platform

English | 한국어


왜 marmonitor인가?

tmux에서 여러 AI 코딩 에이전트를 동시에 실행하는 건 이제 일상입니다 — Claude Code가 백엔드를 리팩토링하고, Codex가 다른 패널에서 테스트를 작성하고, Gemini가 문서를 검토합니다. 하지만 세션이 늘어날수록 같은 문제에 부딪힙니다:

  • 패널로 전환했더니 에이전트가 10분째 allow 승인을 기다리고 있었다
  • 방금 작업하던 Codex 세션이 어느 윈도우에 있는지 기억나지 않는다
  • 여러 세션에서 토큰을 얼마나 소모했는지 알 수 없다

이걸 보여주는 대시보드가 없습니다. 패널을 하나하나 돌아가며 직접 확인해야 합니다.

marmonitor가 이 문제를 해결합니다. tmux.conf에 한 줄만 추가하면, 상태바가 로컬 머신에서 실행 중인 모든 AI 세션을 실시간으로 보여주는 컨트롤 패널이 됩니다.

marmonitor tmux 상태바
에이전트 수, 단계 뱃지, 번호 붙은 어텐션 필 — 모두 tmux 상태바에서 확인할 수 있습니다

주요 기능

tmux 상태바 — 터미널 하단에 항상 표시:

  • 에이전트 수 (Cl 12, Cx 2, Gm 1) — 실행 중인 세션 수
  • 실행 수는 세션 파일 연결 여부와 별개입니다. 아직 메타데이터를 연결하지 못한 CLI도 포함하며, GUI 본체·서버·보조 프로세스는 제외합니다.
  • 단계 알림 (⏳ 1, 🤔 2, 🔧 1) — 주의가 필요한 세션
  • 번호 필 (1 ⏳Cl my-project allow, 2 •Cx api-server 6m) — Option+1~5로 세션 바로 이동

어텐션 우선순위 — 입력이 필요한 세션이 먼저 표시:

  • ⏳ permission (승인 대기)이 항상 #1 — 승인이 필요합니다
  • 🤔 thinking (AI 응답 중)이 #2 — 곧 결과가 나옵니다
  • 이후 최근 활성 세션 순으로 정렬

빠른 이동 — Option+1을 누르면 #1 어텐션 세션의 tmux 패널로 바로 이동합니다. 윈도우를 뒤질 필요가 없습니다.

전체 상태 확인 — marmonitor status로 모든 정보 확인:

marmonitor status 출력
모든 세션의 상태, 토큰, 단계, CPU/MEM, 워커 프로세스 트리

에이전트 수정 불필요 — API 키, 플러그인, 코드 변경 없이 바로 쓸 수 있습니다. marmonitor는 외부에서 로컬 프로세스 정보와 세션 파일을 읽습니다. 명령어 두 개만 실행하면 됩니다: npm install -g marmonitor, marmonitor setup tmux.

tmux + AI 멀티세션 워크플로우에 맞춰 만들었습니다. 매일 5개 이상의 AI 코딩 세션을 여러 프로젝트에서 실행한다면, marmonitor가 컨텍스트 전환을 추측에서 상태바 한 번 확인으로 바꿔줍니다.

🔩 내부 구조: 에이전트 세션 바인딩

문제

주요 AI 코딩 에이전트 중 외부 세션 조회 API를 제공하는 것은 없습니다. claude sessions list 같은 명령어도, 세션 상태 변경 웹훅도 존재하지 않습니다. 실시간 토큰 사용량, phase, lastResponseAt을 표시하려면 marmonitor는 각 에이전트의 내부 데이터 포맷을 직접 읽고 해석해야 합니다 — 에이전트마다 포맷이 완전히 다르고, 공식 문서도 없으며, 언제든 바뀔 수 있습니다.

하지만 더 어려운 문제는 파일 파싱이 아닙니다. 실행 중인 OS 프로세스를 올바른 세션 파일에 안정적으로 연결하고, 세션이 변화하는 동안에도 그 연결을 유지하는 것입니다.

바인딩이 어려운 이유

"에이전트 프로세스를 찾아 가장 최신 세션 파일을 읽는다"는 단순한 접근은 실제 환경에서 자주 깨집니다:

  • Claude Code의 /clear — /clear 실행 시 PID는 그대로인 채로 새 session UUID와 새 JSONL 파일이 생성됩니다. 재매핑 없이는 이전 파일을 계속 읽어 토큰과 lastResponseAt이 frozen 상태로 표시됩니다.
  • Stale PID 메타데이터 — Claude는 ~/.claude/sessions/{pid}.json에 현재 session ID를 기록하지만, /clear 직후에는 이 파일이 새 세션을 반영하지 못하고 잠시 지연되는 구간이 있습니다.
  • 같은 cwd의 다중 세션 — 동일 프로젝트 디렉터리에서 두 Claude 세션을 실행하면, mtime 기반 파일 선택이 조용히 잘못된 JSONL을 잡아 한 세션의 활동이 다른 세션에 귀속됩니다.
  • 지연된 파일 생성 — 프로세스가 처음 감지될 시점에 세션 파일이 아직 디스크에 없을 수 있어, 파일이 생성될 때까지 잠정적(provisional) 바인딩을 유지하다 승격해야 합니다.

이 중 하나라도 실패하면 하위 메트릭 전체가 오염됩니다 — 토큰 사용량, phase 감지, lastResponseAt 모두 바인딩된 파일에서 읽기 때문입니다.

바인딩 파이프라인

감지된 모든 에이전트 프로세스에 대해 marmonitor는 다섯 단계를 순서대로 처리합니다:

PID
 └─ Identity Resolver   → session identity (sessionId 또는 thread index)
     └─ File Binding     → session file 경로 (direct 또는 provisional)
         └─ Reconciliation → stale/clear 보정
             └─ Binding Cache    → 인메모리, 현재 바인딩만 유지
                 └─ Binding History  → 디스크 registry, 세션별 누적 이력

에이전트별 처리 방식:

Identity Resolver File Binding Reconciliation
Claude Code ~/.claude/sessions/{pid}.json → sessionId {sessionId}.jsonl (direct) 또는 mtime 근접도 매칭 (provisional) chooseStaleSessionOverride() — /clear 및 stale 메타 감지
Codex cwd + processStartedAt를 SQLite thread index와 매칭 pid + processStartedAt 키의 binding registry를 통해 rollout JSONL 또는 SQLite row binding registry TTL 기반 freshness 보정
Gemini cwd → ~/.gemini/tmp/ 하위 project dir 탐색 mtime 기준 최신 chats/session-*.json 경량 — 프로젝트 디렉터리당 단일 활성 세션

왜 중요한가

바인딩 레이어가 상태바에 표시되는 숫자의 신뢰성을 결정합니다. direct 바인딩은 세션 메타데이터로 파일 경로가 확인된 상태 — 근거 없이는 교체되지 않습니다. provisional 바인딩은 direct 파일이 확인될 때까지 유지되다 자동으로 승격됩니다. Reconciliation은 특정 조건(mtime 격차, 메타데이터 확인, 활성 파일 가드)이 충족될 때만 override를 실행하며, 매 스캔마다 재판단하지 않습니다.

이 설계 덕분에 marmonitor는 /clear, 재시작, 같은 프로젝트의 병렬 세션처럼 단순한 모니터가 조용히 틀린 데이터로 fallback하는 상황에서도 올바르게 추적할 수 있습니다.

지원 에이전트

에이전트 탐지 방식 세션 정보 단계 추적
Claude Code 네이티브 바이너리 토큰, 타임스탬프, 모델 thinking, tool, permission, done
Codex 바이너리 + cmd 폴백 토큰, 타임스탬프, 모델 thinking, tool, done
Gemini cmd 폴백 토큰, 타임스탬프, 모델 thinking, tool, done

설치

1. marmonitor 설치

npm install -g marmonitor

2. tmux 연동 설정

marmonitor setup tmux

marmonitor-tmux 플러그인을 ~/.tmux.conf에 추가합니다. tmux 안에서 prefix + I을 눌러 활성화하세요.

marmonitor를 업그레이드한 뒤에는 tmux 연동도 업데이트가 필요한지 확인하세요:

marmonitor update-integration

prefix + U로 TPM 플러그인을 업데이트했는데도 클릭 동작이나 팝업 키바인딩이 이전 버전처럼 남아 있다면, 실행 중인 tmux 서버에 플러그인을 다시 적용해야 합니다:

tmux run-shell ~/.tmux/plugins/marmonitor-tmux/marmonitor.tmux

이 증상은 주로 기존 tmux 세션에서 플러그인을 업그레이드할 때 발생합니다. 신규 설치에서 prefix + I로 처음 로드하는 경우에는 보통 바로 최신 바인딩이 적용됩니다.

직접 ~/.tmux.conf에 추가하기
set -g @plugin 'mjjo16/marmonitor-tmux'

tpm이 필요합니다.

수동 설치 (tpm 없이)
git clone https://github.com/mjjo16/marmonitor-tmux ~/.tmux/plugins/marmonitor-tmux

~/.tmux.conf에 추가:

run-shell ~/.tmux/plugins/marmonitor-tmux/marmonitor.tmux
소스에서 설치 (개발용)
git clone https://github.com/mjjo16/marmonitor.git
cd marmonitor
npm install && npm run build
npm link

빠른 시작

데몬 시작

marmonitor는 2초마다 AI 세션을 스캔하는 백그라운드 데몬으로 실행됩니다:

marmonitor start        # 데몬 시작
marmonitor stop         # 데몬 중지
marmonitor restart      # 데몬 재시작 (예: npm 업데이트 후)

모든 명령어가 동작하려면 데몬이 실행 중이어야 합니다. marmonitor setup tmux를 실행하면 자동으로 시작됩니다.

tmux 단축키

단축키 동작
prefix + a 어텐션 팝업 — 검토할 세션 선택
prefix + j 점프 팝업 — 이동할 세션 선택
prefix + y 활성 패널의 최신 AI 답변 턴 복사
prefix + m 독 — 컴팩트 모니터 패널
Option+1~5 어텐션 세션 #1~5로 바로 이동
`Option+`` 이전 패널로 돌아가기

CLI 명령어

marmonitor status       # 전체 세션 목록
marmonitor attention    # 입력이 필요한 세션 확인
marmonitor activity     # 각 세션의 활동 내역 (도구 호출 + 토큰)
marmonitor copy-latest-turn   # 활성 tmux 패널의 최신 AI/user 턴 복사
marmonitor watch        # 실시간 전체 화면 모니터
marmonitor jump-back    # 마지막 점프 이전 패널로 복귀
marmonitor help         # 모든 명령어 및 옵션

활동 로그

AI 세션이 실제로 수행한 작업을 추적합니다 — 파일 편집, bash 명령어, 사용 토큰:

marmonitor activity                  # 오늘의 활동
marmonitor activity --pid 1234       # PID로 필터링
marmonitor activity --session abc    # 세션 ID로 필터링
marmonitor activity --days 3         # 최근 3일
marmonitor activity --json           # JSON 출력

활동 내역은 데몬이 자동으로 수집하며 ~/.config/marmonitor/activity-log/에 저장됩니다 (7일 보관).

단계 아이콘

아이콘 단계 의미
⏳ permission AI가 도구 승인을 요청 중 — 사용자 입력 필요
🤔 thinking AI가 응답을 생성 중
🔧 tool 승인된 도구 실행 중
✅ done 응답 완료, 다음 지시 대기 중

상태 레이블

레이블 의미
[Active] CPU 활동 감지됨
[Idle] 프로세스는 살아 있지만 최근 활동 없음
[Stalled] 장기간 활동 없음
[Dead] 세션 파일은 있지만 프로세스가 종료됨
[Unmatched] 실행 중인 CLI의 세션 메타데이터를 아직 연결하지 못함 (실행 수에는 포함)

tmux 플러그인

marmonitor-tmux 플러그인이 tmux 설정을 자동으로 처리합니다:

  • 에이전트 뱃지와 어텐션 필이 포함된 2번째 상태 라인
  • 팝업, 점프, 최신 턴 복사, 독 키 바인딩
  • Option+1~5 다이렉트 점프

@marmonitor-* 옵션으로 원하는 대로 바꿀 수 있습니다. 자세한 내용은 플러그인 README를 참조하세요.

뱃지 스타일

integration.tmux.badgeStyle로 tmux 뱃지와 터미널 텍스트 출력의 스타일을 통일할 수 있습니다.

  • basic — 기본 컬러 필
  • basic-mono — Powerline 테두리의 단색 필
  • text — 배경 없는 컬러 텍스트
  • text-mono — 회색조 텍스트 전용

설정

다음 경로를 순서대로 찾아 먼저 발견된 파일을 적용합니다:

  1. $XDG_CONFIG_HOME/marmonitor/settings.json
  2. ~/.config/marmonitor/settings.json
  3. ~/.marmonitor.json
# 현재 설정 파일 경로 및 값 확인
marmonitor settings-path
marmonitor settings-show

# 기본 설정 파일 생성
marmonitor settings-init --stdout

설정 예시

{
  "display": {
    "attentionLimit": 10,
    "statuslineAttentionLimit": 5
  },
  "status": {
    "stalledAfterMin": 20,
    "phaseDecay": {
      "thinking": 20,
      "tool": 30,
      "permission": 0,
      "done": 5
    }
  },
  "integration": {
    "tmux": {
      "badgeStyle": "basic",
      "keys": {
        "attentionPopup": "a",
        "jumpPopup": "j",
        "dockToggle": "m",
        "directJump": ["M-1", "M-2", "M-3", "M-4", "M-5"]
      }
    }
  }
}

제거

marmonitor uninstall-integration    # tmux 설정 제거 + 상태바 복원
npm uninstall -g marmonitor         # CLI 제거

안전성

  • 기본적으로 읽기 전용 — 관찰만 하며, 세션을 수정하지 않습니다
  • 네트워크 미사용 — 외부로 연결하지 않으며, 모든 데이터는 로컬에 남습니다
  • 보수적인 기본값 — 모든 연동 기능은 옵트인 방식입니다
  • tmux 우선 — WezTerm/iTerm2 네이티브 지원은 현재 일시 중단 상태입니다

변경 이력

릴리스 이력과 호환성 변경사항은 CHANGELOG.md를 참조하세요.

기여하기

설정, 커밋 규칙, PR 가이드라인은 CONTRIBUTING.md를 참조하세요. 아키텍처 세부사항은 ARCHITECTURE.md를 확인하세요.

알려진 제한사항

  • 패널 점프 기능은 tmux가 필요합니다
  • WezTerm / iTerm2 네이티브 바 지원은 일시 중단 상태이며, 현재 tmux만 지원합니다
  • Gemini 권한 감지는 Ink TUI 아키텍처로 인해 제한적입니다
  • 단계 감지는 휴리스틱 기반으로, 에이전트별 정확도가 다를 수 있습니다
  • macOS 기준으로 개발했으며, Linux에서는 아직 테스트하지 않았습니다

라이선스

MIT — MJ JO