agmsg를 플러그인 방식으로 만들기: 에이전트 유형별 단일 디렉토리 구성 및 외부 드라이버를 위한 신뢰 게이트 (1.1.0)

agmsg는 CLI AI 에이전트들이 서로 메시지를 주고받을 수 있게 해주는 작은 도구입니다. Claude Code, Codex, Gemini CLI 등이 하나의 팀으로 합류하여 공유된 로컬 SQLite 파일을 통해 직접 대화합니다. 데몬(daemon)도, 네트워크도 없으며, 중간에서 누군가가 복사-붙여넣기를 전달할 필요도 없습니다.

최근 더 많은 사람들이 이를 사용하고 있습니다. Product Hunt에서 '오늘의 제품(Product of the Day)' 5위를 차지했으며 그 기세가 계속 이어지고 있습니다. 그리고 사람들이 구축하는 설정은 점점 더 야심 차게 변하고 있습니다. 제가 계속 목격하는 한 가지 패턴은 다음과 같습니다: 에이전트가 자신의 진행 상황을 모니터링하다가, 막히는 부분이 생기면 더 큰 그림을 볼 수 있는 두 번째 모델에게 자문을 구하여 터널 시야(tunnel vision)에서 벗어나는 방식입니다. 이 전체 루프는 중간에 인간의 결정 없이 실행됩니다. 에이전트 팀이 하나의 팀으로서 사용되는 것입니다.

이러한 사례가 늘어날수록, 저는 "이 에이전트도 섞어서 쓰고 싶다"라거나 "저 조합으로 실행하고 싶다"라는 말을 더 많이 듣게 됩니다. 이는 즐거운 고민입니다. 하지만 이 과정에서 코드베이스 내부에서 조용히 커지고 있던 문제 하나가 드러났습니다.

1.1.0 버전은 그 문제를 인지한 후, agmsg가 확장성(extensibility)을 처리하는 방식, 즉 새로운 에이전트를 얼마나 쉽고 안전하게 연결할 수 있는지를 재구축한 결과물입니다.

왜 1.1.0인가 (1.0.7이 아닌)

이전에는 새로운 에이전트 유형을 추가하는 것이 번거로운 일이었습니다. 코어(core) 곳곳에 분기문(if claude-code, do this; if codex, do that)이 흩어져 있었고, 새로운 유형 하나를 추가하려면 수십 군데에 있는 해당 분기문들을 수정해야 했습니다. 이는 누수되는 추상화(leaky abstraction)였습니다. 엔진이 자신이 지원하는 모든 유형의 이름을 알고 있었기 때문입니다.

단일 기능 추가였다면 패치 릴리스(patch release)였겠지만, 이번에는 기반을 재구축했기 때문에 마이너 업데이트(minor bump)인 1.1.0로 배포되었습니다. 대부분의 이점은 이 기반 위에 구축될 향후 릴리스에서 나타날 것입니다.

하나의 유형, 하나의 디렉토리

설명하기에는 아주 작은 변화입니다. 이제 에이전트 유형 (agent type)은 데이터와 동작 플러그 (behavior plug)의 결합이며, 각각은 자신만의 디렉토리에 위치합니다. scripts/drivers/types/ 아래에 디렉토리를 넣고, 매니페스트 (manifest)와 몇 가지 재정의 가능한 동작 (overridable behaviors)을 부여하면 코어 (core)가 이를 인식합니다. 코어는 더 이상 단 하나의 하드코딩된 유형 이름을 포함하지 않습니다. (저는 이 부분을 엔진 정화 (engine purification)라고 불렀는데, 실제보다 거창하게 표현한 것 같습니다.)

소켓과 플러그를 생각하면 쉽습니다. agmsg 코어는 소켓이고, 각 에이전트 유형은 플러그입니다. 소켓의 배선을 다시 할 필요 없이 플러그를 추가할 수 있습니다. 이전에는 소켓의 내부 구조를 열어보지 않고는 플러그를 추가할 수 없었습니다.

실제적으로 두 가지가 개선되었습니다.

이제 유형을 추가하는 것은 대부분 선언적 (declarative)입니다. 예를 들어, Delivery는 템플릿 메서드 (Template Method) 패턴이 되었습니다. 코어가 흐름 (apply / on_enable / on_disable / status)을 소유하고, 각 유형은 자신의 _delivery.sh에서 자신에게 특화된 부분만 재정의합니다. 매니페스트의 데이터 기반 키 (delivery_modes, stop_output, hook_windows_wrap)는 공유 코드를 건드리지 않고도 유형별 변동 사항의 대부분을 처리합니다. 여기저기 흩어져 있던 Codex 런타임 (runtime)은 이제 자체적인 types/codex/ 아래에 존재합니다.

그리고 코어의 유지보수성이 향상되었습니다. 공유 스크립트에서 하드코딩된 유형 이름을 제거하는 것은 지루하게 들릴 수 있지만, 실제로 가장 중요한 부분이었습니다. 엔진은 더 이상 특정 유형을 편애하지 않으므로, 수정하기가 더 쉬워졌고 유형을 추가하더라도 다른 유형을 망가뜨릴 가능성이 훨씬 낮아졌습니다.

의도된 확장성

agmsg에서는 이 플러그 메커니즘을 드라이버 (driver)라고 부릅니다. 이는 에이전트를 코어에 연결하는 어댑터 (adapter) 역할을 합니다.

드라이버 덕분에 여러분만의 에이전트 유형을 추가할 수 있습니다. 1.1.0 버전은 이를 보여주는 첫 번째 실제 사례로 Cursor를 탑재했습니다. 새로운 레이아웃 덕분에 Cursor와 같은 신규 유형은 매니페스트와 플러그를 넣는 것만으로 구현이 가능합니다. 또한 Fewmanism의 기여를 바탕으로 베타 버전으로 추가된 커뮤니티 구축 유형인 Hermes도 있습니다.

이 부분이 제가 가장 신경 썼던 부분입니다. 외부에서 새로운 유형(type)을 추가할 수 있게 한다는 것은, 알 수 없는 코드가 사용자의 머신에서 실행되도록 허용하는 것과 종이 한 장 차이입니다. 드라이버(driver)는 쉘 스크립트(shell script)입니다. 무엇이든 할 수 있죠. 따라서 외부 드라이버는 선택적 참여(opt-in) 방식입니다. 사용자가 명시적으로 신뢰(trust)하기 전까지는 아무것도 로드되지 않습니다.

agmsg plugin list      # 발견된 외부 드라이버 확인 (기본적으로 신뢰되지 않음)
agmsg plugin trust     # 특정 경로에 고정된(path-pinned) 드라이버의 로드 허용
agmsg plugin untrust   # 신뢰 취소

누군가 디렉토리에 넣어둔 드라이버는 스스로 실행되지 않습니다. 사용자가 해당 경로에 고정하여 발행한 trust 명령 이후에만 로드됩니다. 이를 통해 의도치 않게 드라이버가 삽입되어 실행되는 명백한 보안 허점을 막으면서도, 확장을 위해 디렉토리를 넣는 것보다 더 어려운 과정을 거치지 않도록 했습니다.

향후 방향

agmsg 생태계에서 제가 원하는 것은 명확합니다. 사용 중인 어떤 에이전트(agent)든 큰 번거로움 없이, 그리고 안전하게 연결되는 것입니다.

새로운 AI 도구들이 거의 매주 출시되고 있습니다. 저의 목표는 "이 도구를 agmsg에 연결할 수 있으면 좋겠다"라는 생각이 들 때, 매번 적은 비용으로 안전하게 연결할 수 있게 하는 것입니다. 1.1.0 버전은 이를 위한 기반 작업입니다. 유형(types)이 플러그인 방식으로 전환되는 첫 번째 단계이며, 저장(storage)과 전달(delivery)이 동일한 드라이버 모델(설계 노트를 원하신다면 ADR 0001/0002 참조)을 따라 그 뒤를 이을 것입니다.

마지막으로 한 가지 더. 이 빌드의 기반이 된 PR(Pull Request)을 보내준 기여자들에게 큰 감사를 전합니다. Windows 측의 lucian (@lucianlamp) (1.1.0에는 PowerShell 런처를 단일 Git Bash 경로로 대체하는 #186과 #187도 포함되었습니다), 그리고 Hermes의 Fewmanism에게 감사드립니다. agmsg는 항상 사용자와 직접 손을 보태주는 사람들 덕분에 이렇게 성장해 왔습니다.

아직 끝난 것이 아닙니다. Hermes는 베타 버전이며, 다음으로는 커뮤니티와 함께 Grok 유형을 만들어보고 싶고, 아직 견고화(hardening) 작업도 남아 있습니다. 여러분만의 에이전트를 연결하거나, 유형을 구축하거나, Hermes를 테스트해보고 싶다면 모두 환영합니다.

이미 1.0.x 버전을 사용 중인 분들을 위한 실질적인 참고 사항이 하나 더 있습니다: install.sh --update 명령어가 이제 새로운 경로에 Codex 모니터 래퍼 (wrapper)를 다시 생성하므로, 1.0.x에서 1.1.0으로 업그레이드할 때 모니터 전달 기능이 조용히 중단되는 일은 발생하지 않을 것입니다. 업데이트 후에는 실행 중인 와처 (watcher)가 새로운 코드를 인식할 수 있도록 에이전트를 재시작하십시오.

npx agmsg                       # 설치 / 업데이트
npm i -g agmsg && agmsg install # 또는 이 방식

GitHub의 agmsg: https://github.com/fujibee/agmsg