Simple agent room
사용 시점
룸(Room) 은 다대다 채팅 로그입니다. 여러 에이전트가 룸에 게시할 수 있고, 어떤 에이전트든 Monitor할 수 있습니다. 일반적인 사용 예:
- 관련 작업을 수행하는 여러 하위 에이전트가 중간 결과를 공유해야 할 때 (파서 버그를 보고하는 코더, URL을 보고하는 리서처, 실패한 어설션을 보고하는 테스터).
- 나중에 생성될 다른 에이전트가 발견할 수 있어야 하는 장기 실행 에이전트.
- 다단계 계획을 수행하는 "에이전트 팀"을 위한 조정 채널.
단일 장기 실행 하위 에이전트와의 일대일 통신에는 자매 스킬인 simple-agent-comms (두 개의 파일 + 모니터)가 더 가볍습니다.
에이전트가 알아야 할 사항
모두 $PATH에 있는 세 가지 명령어입니다. 파일 경로를 알 필요가 없습니다. 룸 이름만 전달하면 됩니다.
simple-room-send <room> [args] # 메시지 게시
simple-room-monitor <room> [args] # 새 메시지 스트리밍 (Monitor 친화적)
simple-room-scan <room> <subcmd> # count / tail / active / grep / ids / path
이것이 전부입니다. 룸 이름(영숫자, 점, 밑줄, 대시; 최대 64자)을 선택하고, 자신의 에이전트 ID를 선택한 후, 메시지를 보내고 읽습니다.
시스템의 나머지 부분이 룸이 저장된 위치를 알아야 하는 경우, 단일 표준 위치는 ~/.cache/simple-agent-room/<room>.log이며, $SIMPLE_AGENT_ROOM_DIR을 통해 재정의할 수 있습니다(드문 경우 — 테스트 또는 다중 테넌트 레이아웃 전용).
빠른 시작 (하나의 에이전트, 한 줄)
simple-room-send kitchen "stove is on" # 메시지 게시
simple-room-scan kitchen tail -n 5 # 마지막 5개 읽기
simple-room-scan kitchen active --window 60 # 현재 참여자 확인
빠른 시작 (두 에이전트 협업)
# 에이전트 A # 에이전트 B
simple-room-send tasks -m "나는 시작합니다" \
simple-room-monitor tasks # Monitor에서:
▲ # 새 줄 도착,
│ # 자신의 메시지 필터링
# --- 나중에, 다른 터미널/턴에서 --- simple-room-send tasks -m "확인"
올바른 패턴: Monitor(...) 도구 호출에서 모니터를 영구적인 백그라운드 명령으로 실행한 다음, 포그라운드에서 메시지를 보내고, 스캔하고, 대화합니다.
ASCII 흐름도
메시지 게시
에이전트 simple-room-send 디스크
───── ──────────────── ───────
$ simple-room-send kitchen \ │
-a alice -m "hi" │ format_record
│ → JSON line + '\n'
│ → os.open(O_APPEND|O_CREAT, 0o644)
│ → os.write(fd, line)
▼
~/.cache/simple-agent-room/kitchen.log
─────────────────────────────────────────
{"id":"…","ts":"…","agent":"alice", … }
{"id":"…","ts":"…","agent":"bob", … }
…
동시 게시자는 서로의 레코드를 손상시키지 않습니다: O_APPEND 쓰기는 PIPE_BUF(4096 B) 이하의 버퍼에 대해 POSIX에서 원자적이며, JSON 레코드는 실제로 항상 1KiB 미만입니다.
모니터링 (Monitor(...) 형태)
simple-room-monitor Monitor 도구
─────────────────── ───────────
백필: 마지막 N개 레코드 추출 표준 출력
(또는 "실시간 전용"의 경우 0) │
JSON 파싱, 자신 제외 ──────►│ 각 줄은 백그라운드
│ 이벤트이며,
실시간: pyinotify.watch 파일 감시 │ 사용자 응답이 아님
IN_MODIFY ─► 새 바이트 읽기
IN_DELETE ─► 재생성 대기
IN_MOVE ─► 재생성 대기
▼
에이전트가 줄을 읽고,
수행할 작업 결정
이 스크립트는 폴링하지 않습니다. pyinotify.Notifier에서 차단되고 커널 이벤트에 의해 깨어납니다. 로컬 파일 시스템에서 전송에서 이벤트 전달까지의 지연 시간은 1밀리초 미만입니다.
스캔 (읽기 전용)
simple-room-scan <room> <subcmd> [args]
────────────────────────────────────────
│
├─ count → 1줄: 총 레코드 수
├─ ids → 줄당 1개 ID (정렬됨)
├─ path → 1줄: 절대 파일 경로
├─ active [--window S] → 활성 에이전트당 "agent<TAB>ts"
├─ tail [-n N] [-a A] → 마지막 N개 (또는 에이전트의) 레코드
└─ grep <pattern> → 메시지가 일치하는 레코드
[--since-seq N]
[-a A] [--json]
│
▼
iter_records(path) → dict 스트림
(빈 줄 / '#' / 잘못된 형식의 줄 건너뜀)
참조
simple-room-send <room> [-m MSG] [-k {msg,system,meta}] [-a AGENT] [--stdin]
| 플래그 | 의미 |
|---|---|
-m MESSAGE | 메시지 텍스트 (그 외에는 stdin에서 읽음) |
--stdin | stdin에서 강제 읽기 (-m보다 우선) |
-k KIND | msg (기본값), system, 또는 meta |
-a AGENT | 로컬 에이전트 ID; 기본값 $SIMPLE_AGENT_ID 또는 $USER-<host>-<pid> |
--seq N | 명시적 단조 시퀀스 (선택 사항) |
--id ID | 명시적 레코드 ID (uuid4 hex, 선택 사항) |
--ts ISO | 명시적 타임스탬프 (선택 사항) |
-q | stderr에 "sent id=…" 확인 메시지 표시 안 함 |
메시지는 그대로 저장됩니다(개행, 탭, 백슬래시는 레코드 내에서 JSON 이스케이프 처리됨; 읽기 측에서는 일반 문자로 표시됨).
simple-room-monitor <room> [-a AGENT] [--exclude-self] [--backfill N] [--grep PATTERN] [--json]
| 플래그 | 의미 |
|---|---|
-a AGENT | 로컬 에이전트 ID (기본값은 위와 동일) |
--exclude-self | 로컬 에이전트의 레코드 제외 (기본값: 켜짐) |
--no-exclude-self | 포함 (자신의 메시지를 보려는 경우 사용) |
-b N | 실시간 전환 전에 마지막 N개 기존 레코드 출력 |
(-1 = 전체; 0 = 이벤트만, 기본값) | |
--grep PATTERN | 렌더링된 줄이 정규식과 일치하는 레코드만 출력 |
--json | 줄당 원시 JSON 레코드 출력 (그 외에는 HH:MM:SS agent: msg) |
이 스크립트는 종료될 때까지 실행됩니다. 영구적인 Monitor(...) 도구 호출의 command로 사용하십시오 — 올바른 패턴은 세션당 룸당 하나의 Monitor입니다. Monitor 이벤트는 백그라운드 이벤트이지 사용자 응답이 아닙니다. 턴을 종료하는 사용자 메시지로 취급하지 마십시오.
simple-room-scan <room> <subcommand> [args]
| 서브커맨드 | 인수 | 출력 |
|---|---|---|
count | — | 총 레코드 수 |
ids | — | 줄당 하나의 에이전트 ID |
path | — | 절대 파일 경로 |
active | --window SECONDS (120) | 활성 에이전트당 agent<TAB>ts |
tail | -n N (20), -a AGENT, --json | 마지막 N개 레코드 |
grep | PATTERN, --since-seq N, -a A, --json, -c (count→stderr) | 일치하는 레코드 |
grep은 대소문자를 구분하며 Python 정규식 문법을 사용합니다(일반적인 경우 ., *, +, ?, \b, 문자 클래스 등 PCRE에 가깝습니다).
자기 필터 패턴 ("자기 자신과 대화하지 않기" 레시피)
Monitor는 기본적으로 --exclude-self를 사용합니다. 단일 에이전트 턴 루프에서 에이전트가 방금 자신의 메시지를 보냈기 때문에, 이를 이벤트로 다시 재생하는 것은 잡음이 됩니다. 단일 에이전트 디버그 세션의 양쪽을 모두 확인해야 하는 경우 --no-exclude-self를 전달하십시오.
같은 룸에 있는 두 에이전트는 다른 에이전트 ID를 선택해야 합니다. 기본값($USER-<host>-<pid>)은 프로세스당 고유합니다. 동일한 셸에서 여러 에이전트를 실행하는 경우 각각에 대해 SIMPLE_AGENT_ID를 설정하여 구별하십시오.
알 필요가 없는 것
- 디스크 경로.
~/.cache/simple-agent-room/<room>.log입니다. 직접 작성할 필요가 없습니다.simple-room-scan <room> path로 확인할 수 있습니다. - 스키마. 라이브러리가 파일을 읽고, JSON을 파싱하고, 잘못된 형식의 줄을 버리고, 메시지 문자열을 이스케이프 해제합니다.
id,ts,agent,msg,kind, 선택적seq가 있는 딕셔너리를 볼 수 있습니다. - 폴링. Monitor는 완전히 이벤트 기반(inotify)입니다.
- 잠금. 레코드는 4KiB 미만이며 O_APPEND는 POSIX에서 원자적이므로 flock/fcntl이 필요하지 않습니다. 두 작성자가 동시에 게시해도 서로의 레코드가 손상되지 않습니다.
알아야 할 오류 모드
- 삭제/이름 변경 후 inotify가 오래된 경우: 라이브러리가 동일한 경로의
IN_CREATE에서 감시를 다시 연결하므로, 파일을 교체하는 로그 순환 도구가 처리됩니다. 수동으로rm하면 모니터가 다음 전송 시 새 빈 파일을 생성합니다. - 에이전트 ID 충돌: 동일한 ID를 가진 두 에이전트는 서로의 메시지를 자신의 메시지로 보고(기본적으로 필터링)합니다. 항상
SIMPLE_AGENT_ID또는$USER-<host>-<pid>기본값을 사용하십시오. - 시계 오차:
ts는 발신자의 벽시계 UTC입니다. 에이전트 간에ts로 정렬하려면 NTP를 설정하십시오. 단일 에이전트 내에서 순서를 지정하려면seq를 사용하십시오. - 매우 긴 메시지: 하드 제한은 없지만, 정기적으로 4KiB를 초과하여 게시하면 PIPE_BUF에 도달하여 레코드가 분할될 수 있습니다. 메시지를 4KiB 미만으로 유지하십시오.
- 잘못된 형식의 줄: 리더는 JSON 객체로 파싱되지 않는 줄을 자동으로 건너뜁니다. 잘못된 입력은 자동으로 무시되며, 주변의 유효한 레코드에는 영향을 미치지 않습니다.
파일
skills/simple-agent-room/
SKILL.md ← 이 파일
bin/
simple-room-send ← 얇은 래퍼, lib.simple_room_send.main 호출
simple-room-monitor ← 얇은 래퍼, lib.simple_room_monitor.main 호출
simple-room-scan ← 얇은 래퍼, lib.simple_room_scan.main 호출
lib/
simple_agent_room_lib.py ← 공유 라이브러리 (format/parse, inotify, scan)
simple_room_send.py ← send 진입점
simple_room_monitor.py ← monitor 진입점
simple_room_scan.py ← scan 진입점
각 bin/simple-room-* 래퍼는 12줄의 Python 파일로, sys.path를 조정하고 lib/simple_room_*.main에 위임합니다. 래퍼는 자신의 실제 경로를 확인하므로 ~/.local/bin/의 심볼릭 링크가 투명하게 작동합니다.
설치
리포지토리 루트에서:
./install.sh
이렇게 하면 simple-agent-room이 ~/.claude/skills/ 및 ~/.agents/skills/에 배치되고, 세 CLI가 각각 simple-room-send, simple-room-monitor, simple-room-scan으로 $PATH에 추가됩니다.
수동으로 수행하려면:
ln -s "$PWD/skills/simple-agent-room" ~/.claude/skills/simple-agent-room
ln -s "$PWD/skills/simple-agent-room" ~/.agents/skills/simple-agent-room
ln -s "$PWD/skills/simple-agent-room/bin/"* ~/.local/bin/
종속성
- Python ≥ 3.10
pyinotify(pip install pyinotify). monitor에서만 필요함;simple-room-send와simple-room-scan은 이것 없이도 작동합니다.