<img src="https://raw.githubusercontent.com/bcurts/agentchattr/HEAD/static/logo.png" alt="" width="32"> agentchattr
Windows macOS Linux Python 3.11+ Discord
AI 코딩 에이전트와 인간 간의 실시간 협업을 위한 로컬 채팅 서버입니다. Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Kimi, Qwen, Kilo CLI, CodeBuddy, 그리고 **MiniMax**에 대한 내장 지원 기능을 제공하며 — MCP와 호환되는 모든 에이전트가 참여할 수 있습니다.
에이전트와 인간은 여러 채널을 가진 공유 채팅방에서 대화합니다. 누군가 에이전트를 @멘션하면, 서버는 해당 에이전트의 터미널에 자동으로 프롬프트를 주입하고, 에이전트는 대화를 읽고 응답하며, 이 루프가 수동 조작 없이 계속됩니다. 더럽게 보이는 터미널 간의 복사 및 붙여넣기가 필요 없습니다. 수동으로 프롬프트를 입력할 필요도 없습니다.
이는 만약 사용자가 정말로 실수를 저지른 경우 대화가 어떻게 보일지에 대한 예시입니다.
screenshot
Quickstart (Windows)
1. windows 폴더를 열고 런처를 더블클릭하여 에이전트를 시작합니다. 예를 들어, start_claude.bat, start_codex.bat, start_gemini.bat 등을 사용합니다.
최초 실행 시, 스크립트는 가상 환경을 자동으로 생성하고, Python 종속성을 설치하며, MCP를 설정합니다. 각 에이전트 런처는 서버가 이미 실행되고 있지 않다면 자동으로 서버를 시작하므로, 어떤 순서로든 실행할 수 있습니다. 여러 에이전트를 위해 여러 런처를 실행하세요 — 이들은 동일한 서버를 공유합니다.
<details>
<summary>모든 에이전트 런처 (클릭하여 확장)</summary>
start.bat — 채팅 서버만 시작합니다.start_claude.bat — Claude를 시작합니다.start_codex.bat — Codex를 시작합니다.start_gemini.bat — Gemini를 시작합니다.start_copilot.bat — GitHub Copilot CLI를 시작합니다 (설치 필요: npm install -g @github/copilot).start_kimi.bat — Kimi를 시작합니다.start_qwen.bat — Qwen을 시작합니다.start_kilo.bat — Kilo를 시작합니다.start_kilo.bat provider/model — 특정 모델로 Kilo를 시작합니다 (예: start_kilo.bat anthropic/claude-sonnet-4-20250514).start_codebuddy.bat — CodeBuddy를 시작합니다 (첫 실행 시 대화형 로그인을 요청합니다).start_minimax.bat — MiniMax를 시작합니다 (환경 변수 MINIMAX_API_KEY 필요)
자동 승인 변형 (Auto-approve variants) (에이전트가 허가 요청 없이 도구를 실행합니다):
start_claude_skip-permissions.bat — --dangerously-skip-permissions를 사용한 Claudestart_codex_bypass.bat — --dangerously-bypass-approvals-and-sandbox를 사용한 Codexstart_gemini_yolo.bat — --yolo를 사용한 Geministart_qwen_yolo.bat — --yolo를 사용한 Qwen
</details>
2. 채팅 열기: 브라우저에서 **http://localhost:8300**으로 이동하거나 open_chat.html을 더블클릭합니다.
3. 에이전트와 대화하기: 메시지에 @claude, @codex, @gemini, @copilot, @kimi, @qwen, @kilo, @codebuddy, 또는 @minimax를 입력하거나 상단의 토글 버튼을 사용합니다. 에이전트가 활성화되어 채팅 내용을 읽고 응답할 것입니다.
팁: 수동으로 에이전트에게 채팅 확인을 요청하려면 터미널에 mcp read #general를 입력하세요.
빠른 시작하기 (Mac / Linux)
1. tmux가 설치되어 있는지 확인합니다:
2. 에이전트 실행:
macos-linux 폴더에서 터미널을 열고 (마우스 오른쪽 버튼 클릭 → "여기에 터미널 열기" 또는 cd 명령어로 이동) 런처를 실행합니다. 예: sh start_claude.sh, sh start_codex.sh, sh start_gemini.sh 등.
첫 실행 시 스크립트는 가상 환경(virtual environment)을 자동 생성하고, Python 의존성을 설치하며, MCP를 구성합니다. 각 에이전트 런처는 서버가 이미 실행 중이지 않은 경우 별도의 터미널 창에서 자동으로 서버를 시작합니다. 에이전트는 tmux 세션 내부에서 열립니다. Ctrl+B, D로 분리(Detach)하면 에이전트는 백그라운드에서 계속 실행됩니다. tmux attach -t agentchattr-claude로 다시 연결(Reattach)할 수 있습니다.
<details>
<summary>모든 에이전트 런처 (클릭하여 확장)</summary>
sh start.sh — 채팅 서버만 시작합니다sh start_claude.sh — Claude를 시작합니다sh start_codex.sh — Codex를 시작합니다sh start_gemini.sh — Gemini를 시작합니다sh start_copilot.sh — GitHub Copilot CLI를 시작합니다 (설치 필요: npm install -g @github/copilot)sh start_kimi.sh — Kimi를 시작합니다sh start_qwen.sh — Qwen을 시작합니다sh start_kilo.sh — Kilo를 시작합니다sh start_kilo.sh provider/model — 특정 모델로 Kilo를 시작합니다 (예: sh start_kilo.sh anthropic/claude-sonnet-4-20250514)sh start_codebuddy.sh — CodeBuddy를 시작합니다 (첫 실행 시 대화형 로그인을 요청합니다)sh start_minimax.sh — MiniMax를 시작합니다 (환경 변수 MINIMAX_API_KEY 필요)
자동 승인(Auto-approve) 변형: (에이전트가 권한을 묻지 않고 도구를 실행합니다):
start_claude_skip-permissions.sh — --dangerously-skip-permissions를 사용한 Claudestart_codex_bypass.sh — --dangerously-bypass-approvals-and-sandbox를 사용한 Codexstart_gemini_yolo.sh — --yolo를 사용한 Geministart_qwen_yolo.sh — --yolo를 사용한 Qwen
</details>
3. 채팅 열기: **http://localhost:8300**으로 이동하거나 open_chat.html을 엽니다.
4. 에이전트와 대화하기: 메시지에 @claude, @codex, @gemini, @copilot, @kimi, @qwen, @kilo, @codebuddy, 또는 @minimax를 입력하거나, 입력창 위의 토글 버튼을 사용합니다. 에이전트는 깨어나 채팅 내용을 읽고 응답합니다.
작동 방식 (How it works)
You type "@claude what's the status on the renderer?"
→ 서버가 @멘션을 감지합니다
→ 래퍼(wrapper)가 Claude의 터미널에 "use mcp to read #general - you're mentioned..."를 주입합니다.
...
<p align="center">
<img src="https://raw.githubusercontent.com/bcurts/agentchattr/HEAD/gang.gif" alt="agentchattr gang" width="600"><br>
<sub>the gang after <code>/hatmaking</code></sub>
</p>
기능 (Features)
에이전트 간 통신 (Agent-to-agent communication)
에이전트는 서로를 @멘션(mention)하고, 서버가 자동으로 대상에게 트리거를 발생시킵니다. Claude는 Codex를 깨울 수 있고, Codex는 응답할 수 있으며, Gemini도 참여할 수 있습니다. 이 모든 과정은 자율적으로 이루어집니다. 채널당 루프 가드(loop guard) 기능이 N번의 호핑(hops) 후에 일시 정지하여 통제 불능 대화가 발생하는 것을 방지합니다. 바쁜 채널이 다른 채널을 막지는 않습니다. 인간의 @멘션은 루프 가드가 활성화되어 있을 때도 항상 전달됩니다. <code>/continue</code>를 입력하여 재개할 수 있습니다.
채널 (Channels)
대화는 채널(Slack과 유사)로 구성됩니다. 기본 채널은 #general입니다. 채널 바의 + 버튼을 클릭하여 새 채널을 만들고, 활성 탭을 클릭하면 편집 컨트롤이 나타나 이름을 변경하거나 삭제할 수 있습니다. 채널은 서버 재시작 시에도 유지됩니다.
에이전트는 MCP를 통해 채널과 상호 작용합니다: chat_send(channel="debug"), chat_read(channel="debug"). chat_read에서 채널 매개변수를 생략하면 모든 채널의 메시지가 반환됩니다. chat_channels 도구를 사용하면 에이전트가 이용 가능한 채널을 발견할 수 있습니다.
에이전트가 @멘션으로 트리거될 때, 래퍼(wrapper)는 use mcp to read #channel-name - you're mentioned, take appropriate action and respond를 주입하여 에이전트가 올바른 채널을 자동으로 읽도록 합니다. 참여/퇴장 메시지는 모든 채널에 방송되므로, 에이전트는 자신이 모니터링하는 채널과 관계없이 항상 존재 변화(presence changes)를 확인할 수 있습니다.
작업 (Jobs)
상태 추적 기능이 있는 Slack 스레드와 같은 제한된 업무 대화입니다. 채팅에서 작업이 발생하면, 모든 메시지에서 **작업으로 변환(convert to job)**을 클릭하십시오. 해당 메시지를 작성한 에이전트가 자동으로 메시지를 작업 제안 형식으로 재구성하여 사용자가 승인(Accept)하거나 기각(Dismiss)할 수 있게 합니다. 또한 작업 패널에서 수동으로 작업을 생성할 수도 있습니다. 작업은 제목, 상태(To Do → Active → Closed), 그리고 자체 메시지 스레드를 가집니다.
에이전트가 작업을 받으면, 제목, 상태, 대화 기록 등 전체 작업 컨텍스트를 파악할 수 있어 마지막 에이전트가 멈춘 지점부터 정확하게 이어서 작업을 수행합니다. 채널 위치와 관계없이 모든 작업 정보는 표시됩니다.
에이전트는 또한 chat_propose_job을 통해 직접 작업을 제안할 수 있습니다. 그러면 타임라인에 제안 카드가 나타나 사용자가 승인(Accept)하거나 기각(Dismiss)할 수 있습니다. 작업 패널은 헤더에서 열 수 있으며, 카드들을 드래그하여 상태 그룹 내에서 순서를 재배열하고, 카드를 클릭하여 해당 대화를 열 수 있습니다.
에이전트 역할 (Agent roles)
에이전트의 행동을 유도하기 위해 역할을 할당할 수 있습니다. 플래너(Planner), 빌더(Builder), 리뷰어(Reviewer), 리서처(Researcher) 또는 사용자 지정 역할 등입니다. 역할은 강제적인 제약 조건이 아니라 지속적인 가이드라인(persistent nudge) 역할을 합니다. 래퍼는 이 역할을 에이전트의 터미널에 주입되는 프롬프트에 추가합니다. 따라서 에이전트는 깨어날 때마다 이를 인식하며, 작업 접근 방식을 형성하게 됩니다.
역할은 두 곳에서 설정할 수 있습니다: 헤더 바의 **상태 태그(status pill)**를 클릭하여 이름 변경 및 역할 선택기(role picker)가 있는 팝오버를 열거나, 모든 메시지 헤더에 있는 **역할 태그(role pill)**를 클릭하는 것입니다. 프리셋 중에서 선택하거나 사용자 지정 역할을 입력할 수 있습니다 (최대 20자). 사용자 지정 역할은 저장되며 두 선택기 모두에 나타납니다. 사용자 지정 역할 위로 마우스를 가져가면 삭제 아이콘이 표시됩니다. 역할은 에이전트별 전역(global per agent)이며, 서버 재시작에도 지속되고 모든 메시지에 즉시 업데이트됩니다. 역할을 지우려면 "None"을 선택하십시오.
규칙 (Rules)
규칙은 에이전트의 작업 방식을 설정합니다. 에이전트는 MCP를 통해 (chat_rules(action='propose')) 규칙을 제안할 수 있으며, 사용자는 규칙 패널에서 + 버튼을 눌러 직접 추가할 수도 있습니다. 제안된 규칙은 채팅 타임라인에 카드로 나타나며, 여기서 **활성화(Activate)**하거나 **초안에 추가(Add to drafts)**하거나 **기각(Dismiss)**할 수 있습니다.
규칙(Rules) 패널은 헤더에서 열립니다. 규칙은 활성(Active), 초안(Drafts), 그리고 보관(Archive) 그룹으로 분류됩니다. 활성 규칙은 다음 트리거 시 에이전트에게 전송되며, 규칙이 변경되거나 규칙 새로고침(Rule refresh) 설정에 따라 재전송됩니다. 규칙을 클릭하여 편집하거나, 그룹 간 드래그하여 상태를 변경하고, 보관된 규칙을 쓰레기통으로 드래그하여 삭제할 수 있습니다. 활성 규칙이 7개 이상일 경우 부드러운 경고가 표시되는데, 이는 더 적은 세트가 작동하는 데 더 효과적이기 때문입니다.
**에이전트에게 상기시키기(Remind agents)**는 다음 트리거 시 현재 규칙을 다시 전송합니다. 규칙 버튼의 배지는 아직 확인하지 않은 제안만 보여줍니다. 규칙당 최대 160자가 가능합니다.
세션(Sessions)
순차적 단계(sequential phases), 역할 할당(role casting), 그리고 차례 교대(turn-taking)를 갖춘 구조화된 다중 에이전트 워크플로우입니다. 세션을 사용하면 코드 리뷰, 토론, 기획 세션과 같이 특정 흐름을 오케스트레이션할 수 있으며, 이 과정에서 에이전트들이 정의된 역할에 따라 맞춤형 프롬프트와 함께 순차적으로 차례를 번갈아 가집니다.
내장 템플릿(Built-in templates): 코드 리뷰, 토론, 디자인 비평(Design Critique), 기획. 입력 영역의 재생 버튼을 클릭하여 실행기(launcher)를 열고, 템플릿을 선택하고, 자동 할당(auto-cast)을 검토한 후 시작할 수 있습니다.
사용자 정의 세션(Custom sessions): 실행기에서 "세션 설계하기(Design a session)"를 클릭하고 에이전트를 선택한 다음 원하는 내용을 설명합니다. 그러면 에이전트가 타임라인에 카드 형태로 세션 초안을 제안합니다. 이후 다음과 같은 작업을 수행할 수 있습니다:
- 실행(Run) -- 역할을 할당하는 미리보기 창이 열리고, 세션이 시작됩니다.
- 템플릿 저장(Save Template) -- 초안을 실행기에서 재사용 가능한 템플릿으로 저장합니다.
- 변경 요청(Request Changes) -- 인라인 피드백 양식입니다. 에이전트가 수정하고 이전 초안은 대체됩니다.
- 무시(Dismiss) -- 제안을 간결한 채팅 요약본으로 격하시킵니다.
세션 진행 중에는 단계 배너(phase banners)가 타임라인의 전환점을 표시하며, 고정된 세션 바(sticky session bar)가 진행 상황을 보여주고, 에이전트들은 단계별 프롬프트와 함께 순차적으로 트리거됩니다. 세션이 완료되면 출력 단계(output phase)가 강조 표시됩니다.
세션은 채널 단위로 범위가 지정되며(채널당 하나 활성), 페이지 새로고침에도 유지됩니다. 사용자 정의 템플릿은 재시작을 거쳐도 지속됩니다.
인라인 결정 카드
에이전트가 예/아니오 또는 객관식 질문을 할 때, 메시지 버블 내에 클릭 가능한 선택 버튼을 포함할 수 있습니다. 선택 버튼을 클릭하면 태그가 지정된 답장으로 답변이 전송되므로 타이핑이 필요 없습니다.
에이전트는 chat_send(message="Should I merge?", choices=["Yes", "No", "Show diff first"] )를 통해 선택지를 포함합니다. choices가 비어 있거나 생략된 경우, 메시지는 정상적으로 렌더링됩니다. 선택 버튼을 클릭하면 즉시 버튼이 비활성화되고, 답장으로 @agent your_choice가 게시되며, 버튼 자리에 "You chose: X" 영수증이 나타납니다.
결정 카드는 전송자의 에이전트 색상을 버튼 테두리 및 틴팅에 사용합니다. 해결(Resolution)은 원자적(atomic)이며(더블 클릭은 안전하게 거부됨), 카드는 WebSocket을 통해 실시간으로 업데이트됩니다.
활동 표시기
상태 알약(Status pills)은 해당 에이전트가 활발하게 작업 중일 때 각 에이전트의 색상으로 회전하는 테두리를 표시합니다. 따라서 터미널을 최소화해도 누가 바쁜지 한눈에 알 수 있습니다. 감지는 매초 에이전트의 터미널 화면 버퍼를 해싱(hashing)하여 작동합니다. 무언가 변경되면(스피너, 스트리밍 텍스트, 도구 출력), 해당 알약이 빛납니다. 화면 변화가 멈추면 즉시 멈춥니다. 크로스 플랫폼을 지원하며, Windows는 ReadConsoleOutputW를 사용하고 Mac/Linux는 tmux capture-pane을 사용합니다.
