agent-shell: Claude Code, Codex, Gemini CLI를 Emacs 버퍼에서 쓰는 ACP 클라이언트

9bow · 9월 27, 2026, 9:30오전

agent-shell 소개

Claude Code, Codex, Gemini CLI 같은 코딩 에이전트는 각자 자기만의 터미널 화면(TUI)을 가진 CLI로 배포됩니다. 이런 에이전트를 에디터 안에서 쓰려면 에디터와 에이전트의 조합마다 연동을 따로 만들어야 했고, 그런 연동이 없으면 Emacs 안의 터미널 에뮬레이터 버퍼에 에이전트 TUI를 그대로 띄워 쓸 수밖에 없었습니다. 이번에 소개하는 agent-shell은 여러 코딩 에이전트를 Agent Client Protocol(ACP) ( Agent Client Protocol(ACP): AI 코드 에이전트와 코드 에디터(IDE)를 연결하는 새로운 표준)라는 공통 프로토콜로 연결해, 일반 Emacs 버퍼 하나에서 같은 방식으로 다룰 수 있게 해주는 Emacs 패키지입니다.

agent-shell은 Emacs 내장 comint-mode 위에 만든 셸 버퍼라서, 터미널 에뮬레이터처럼 문자 모드와 줄 모드를 오가지 않고 평소 쓰던 버퍼 편집과 이동 명령을 그대로 쓸 수 있습니다. 에이전트와의 통신은 같은 저자가 만든 ACP 클라이언트 라이브러리 acp.el이 맡습니다. ACP 를 지원하는 에이전트라면 대부분 붙일 수 있다는 점이 핵심이며, 공식 지원 목록에는 Claude Code(agent-shell 안에서는 Claude Agent 로 표시), Codex, Gemini CLI, Goose, Grok Build, Cursor, Kimi Code CLI, Qwen Code, Mistral Vibe, OpenCode, Antigravity, Junie 등 19개 에이전트가 올라 있습니다.

아래 화면은 agent-shell에서 Claude Code 세션을 시작한 모습입니다. 상단 헤더에 에이전트, 모델, 세션 모드, 컨텍스트 사용량이 표시되고, 에이전트가 알려준 기능, 모델, 모드 목록이 접을 수 있는 항목으로 나열됩니다.

agent-shell은 Álvaro Ramírez(xenodium)가 개인 프로젝트로 개발하고 있습니다. 저자가 앞서 만든 여러 LLM 용 Emacs 셸 chatgpt-shell은 현재 지원 중단(deprecated) 상태이며, 저자는 agent-shell을 그 후속으로 안내하고 있습니다(chatgpt-shell 처럼 임시 셸이 필요하면 M-x agent-shell-new-temp-shell). agent-shell의 셸 버퍼는 저자의 또 다른 패키지 shell-maker를 거쳐 comint 위에 구현되어 있습니다. 패키지는 Emacs 패키지 저장소인 MELPA로 배포되며, 본체 저장소 바깥에 사이드바, 알림, 세션 북마크, Org 연동 같은 서드파티 확장 패키지 28개가 저장소의 Related projects 목록에 정리되어 있습니다.

agent-shell과 기존 방식 비교

Emacs 안에서 코딩 에이전트를 쓰는 가장 단순한 방법은 터미널 에뮬레이터 버퍼(vterm, term 등)에 에이전트 CLI를 그대로 실행하는 것입니다. agent-shell과의 차이는 다음과 같습니다:

항목	터미널 버퍼에서 CLI 직접 실행	agent-shell
화면	에이전트마다 다른 자체 TUI	모든 에이전트가 같은 `comint` 기반 Emacs 버퍼
에이전트 교체	에이전트별로 화면과 조작법이 다름	`M-x agent-shell`에서 골라 시작, 조작법 동일
편집과 이동	터미널 입력 모드의 제약을 받음	일반 Emacs 편집, 검색, 이동 명령 사용
슬래시 명령과 스킬	CLI가 제공하는 것 전부	에이전트가 ACP 로 노출한 것만 사용 가능
MCP 서버 설정	에이전트마다 따로 설정	`agent-shell-mcp-servers` 한 곳에서 공유 가능
사전 준비	에이전트 CLI 설치	에이전트 CLI + 필요 시 ACP 어댑터 설치

가장 큰 차이는 에이전트를 바꿔도 사용하는 화면과 키 조작이 그대로라는 점입니다. 반대로 슬래시 명령과 스킬은 에이전트가 ACP 를 통해 알려준 것만 쓸 수 있어서, CLI 에서만 되는 명령이 있을 수 있습니다. 저자는 이 경우 해당 에이전트나 그 ACP 어댑터 쪽에 기능 요청을 하라고 안내하고 있습니다.

ACP 자체는 Zed ( Zed, 에이전틱 편집(Agentic Editing) 기능 베타 버전을 포함한 업데이트 공개) 개발팀과 Google 이 함께 만든 프로토콜입니다. agent-shell은 같은 프로토콜을 Emacs 쪽에서 구현한 클라이언트라서, 새 에이전트가 ACP 를 지원하면 에이전트별 연동을 새로 짜지 않고 설정을 추가하는 수준으로 지원 목록을 늘릴 수 있습니다.

agent-shell을 사용하면 좋을 사용자

Emacs 를 주 에디터로 쓰면서 Claude Code, Codex, Gemini CLI 등 여러 코딩 에이전트를 번갈아 쓰는 개발자에게 agent-shell이 잘 맞습니다. 에이전트마다 다른 TUI를 익히지 않고 같은 버퍼와 키 조작으로 쓸 수 있고, MCP 서버 설정도 한 곳에서 공유할 수 있습니다. Devcontainer 나 Docker 컨테이너 안에서 에이전트를 실행하고 싶은 경우에도 실험적 설정이 제공됩니다.

반대로 Emacs 를 쓰지 않거나, 특정 CLI 전용 슬래시 명령과 스킬에 크게 의존하는 사용자에게는 agent-shell이 적절한 선택지가 아닙니다. ACP 를 지원하지 않는 에이전트는 연동 대상이 아니라고 프로젝트가 명시하고 있으므로, 쓰려는 에이전트가 ACP 를 지원하는지 먼저 확인해야 합니다.

agent-shell의 동작 구조

agent-shell은 에이전트를 직접 호출하지 않고, 사용자의 입력을 acp.el 을 거쳐 ACP 메시지로 주고받습니다. ACP 공식 문서에 따르면 로컬 에이전트는 에디터의 하위 프로세스로 실행되고 표준 입출력(stdio) 위의 JSON-RPC 로 통신합니다. 아래 그림은 이 구조를 3개의 계층으로 정리한 것입니다.

에이전트가 ACP 를 지원하는 방식은 크게 두 가지입니다:

내장 ACP 모드: Gemini CLI(gemini --experimental-acp), Goose(goose acp), Kiro CLI(kiro-cli acp), Qoder CLI(qoder --acp), Junie(junie --acp true)처럼 CLI 자체가 ACP 서버 모드를 제공하는 경우입니다. Cursor 도 공식 CLI 의 agent acp 하위 명령을 사용합니다.
별도 ACP 어댑터: Claude Code 는 Claude Agent SDK 를 감싼 @agentclientprotocol/claude-agent-acp, Codex 는 @agentclientprotocol/codex-acp(호환되는 Codex 바이너리를 함께 설치), Pi 는 pi-acp 같은 어댑터를 설치해 PATH 에 두어야 합니다.

ACP 명세에 없는 기능 일부는 확장으로 다룹니다. 에이전트가 작업 중일 때 보낸 프롬프트를 기본적으로는 대기열에 넣었다가 현재 턴이 끝나면 전송하는데, 에이전트가 ACP 확장인 _session/steering을 지원하면 진행 중인 턴에 바로 끼워 넣어 방향을 바로잡을 수 있습니다(M-x agent-shell-prompt-steer). 현재는 Claude 와 Codex 어댑터가 이를 구현하고 있으며, 끼워 넣은 프롬프트가 기존 지시를 대체할 수 있으므로 기존 작업을 끝내게 하려면 대기열을 쓰라고 저자는 안내합니다.

agent-shell의 주요 기능

agent-shell은 셸 버퍼 외에 한 번에 한 턴씩 작성하고 읽는 뷰포트(Viewport) 화면을 제공합니다. 셸 버퍼에서 C-c C-o로 뷰포트를 열고, 뷰포트에서는 r로 답장, b/f로 이전과 다음 턴 이동, n/p로 항목 이동을 할 수 있습니다. 도구 호출과 추론(thinking) 과정은 기본적으로 접힌 Activity 그룹으로 묶여서 긴 작업에서도 출력이 덜 번잡합니다(0.63 버전부터). 아래는 뷰포트에서 파일 편집 결과가 접힌 항목으로 표시된 화면입니다.

그 밖의 주요 기능은 다음과 같습니다:

세션 제어: 에이전트가 해당 옵션을 제공하면 C-c C-v로 모델, C-c C-m으로 세션 모드, C-c C-t로 추론 강도(thought level)를 바꿀 수 있습니다. 현재 선택값은 헤더에 표시되고 클릭해서 바꿀 수도 있습니다.
권한 요청과 diff 확인: 에이전트가 파일 수정 권한을 요청하면 변경 내용을 diff 버퍼로 보여주고, diff 에서 RET을 누르면 변경이 적용될 파일 위치로 이동합니다.
이미지와 파일 첨부: 클립보드 이미지 붙여넣기(agent-shell-send-clipboard-image), 스크린샷 전송(agent-shell-send-screenshot), 파일 관리자나 dired에서 파일을 끌어다 놓아 프롬프트에 첨부하는 기능을 지원합니다. 에이전트가 돌려준 이미지도 버퍼 안에 바로 렌더링합니다.
MCP 서버 공유 설정: agent-shell-mcp-servers에 MCP 서버를 한 번 등록하면 사용하는 모든 에이전트에 같은 설정을 넘길 수 있고, 에이전트별로 :mcp-servers를 따로 지정할 수도 있습니다.
컨테이너 실행(실험적): agent-shell-command-prefix로 에이전트 시작 명령 앞에 devcontainer exec이나 docker exec을 붙여 컨테이너 안에서 실행할 수 있습니다. 다만 경로 변환 함수를 쓰면 에이전트가 로컬 파일에 접근할 수 있고, 악의적인 에이전트가 작업 디렉터리 제한을 우회할 가능성이 있다고 저자가 직접 경고하고 있습니다. 로컬 파일 접근을 완전히 막으려면 agent-shell-text-file-capabilities를 nil로 설정합니다.

agent-shell의 ACP 트래픽 확인과 문제 진단

agent-shell이 예상대로 동작하지 않을 때 원인은 에이전트 쪽 ACP 구현일 수도, agent-shell 쪽일 수도 있습니다. 이를 가리기 위해 agent-shell은 ACP 트래픽 뷰어를 내장하고 있습니다. M-x agent-shell-toggle-logging으로 기록을 켜고 문제를 재현한 뒤 M-x agent-shell-view-traffic을 실행하면 요청, 응답, 알림이 시간순으로 표시됩니다. 아래 화면은 에이전트가 보낸 session/request_permission 요청을 트래픽 뷰어에서 연 모습입니다.

트래픽은 M-x acp-traffic-save-to로 .traffic 파일로 저장할 수 있어 이슈 보고에 첨부하기 좋습니다. 저자는 개발 과정에서도 저장한 트래픽을 다시 재생하는 가짜 에이전트를 만들어, 유료 에이전트를 매번 호출하지 않고 문제 세션을 반복 재현했다고 소개 글에서 밝혔습니다.

agent-shell 설치와 사용

agent-shell과 의존 패키지 acp.el, shell-maker는 모두 MELPA 에 올라 있습니다. 먼저 쓰려는 에이전트의 CLI 와 ACP 어댑터를 설치합니다. Claude Code 의 경우 다음과 같습니다:

npm install -g @agentclientprotocol/claude-agent-acp

-g 플래그로 전역 설치해야 PATH 에서 claude-agent-acp를 찾을 수 있습니다. Claude 구독을 쓰려면 Claude Code CLI 를 Emacs 바깥에서 한 번 실행해 로그인해 두면 됩니다. 이어서 Emacs 설정에 다음을 추가합니다:

(use-package agent-shell
    :ensure t
    :ensure-system-package
    ;; Add agent installation configs here
    ((claude . "brew install claude-code")
     (claude-agent-acp . "npm install -g @agentclientprotocol/claude-agent-acp")))

Doom Emacs 사용자는 package! 매크로로 shell-maker, acp, agent-shell을 추가하고 doom sync를 실행하면 됩니다. 설치 후 M-x agent-shell을 실행하면 알려진 에이전트 목록에서 골라 시작할 수 있고, C-u M-x agent-shell로는 새 세션을 추가로 엽니다. 특정 에이전트를 바로 시작하는 명령(M-x agent-shell-anthropic-start-claude-code, M-x agent-shell-openai-start-codex, M-x agent-shell-google-start-gemini 등)도 있습니다.

API 키나 OAuth 토큰으로 인증하려면 에이전트별 인증 변수를 설정합니다. 다음은 auth-source에서 Anthropic API 키를 읽어오는 예시입니다:

(setq agent-shell-anthropic-authentication
      (agent-shell-anthropic-make-authentication
       :api-key (lambda () (auth-source-pass-get 'secret "anthropic-api-key"))))

항상 같은 에이전트로 시작하고 싶다면 기본 에이전트를 지정할 수 있습니다:

(setq agent-shell-preferred-agent-config (agent-shell-anthropic-make-claude-code-config))

로컬 모델을 쓰고 싶다면 OpenCode 를 거쳐 Ollama 로 띄운 모델(예시는 Qwen2.5 7B)을 연결하거나, ANTHROPIC_BASE_URL 환경 변수로 Anthropic 호환 API 엔드포인트를 지정할 수 있습니다. 에이전트별 설치 방법과 인증 옵션, 로컬 모델 설정, 키 바인딩, Evil 사용자용 설정은 저장소 README 의 Setup 섹션에 정리되어 있습니다.

agent-shell의 라이선스

agent-shell은 GPL-3.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 단, 수정한 코드를 배포할 때는 같은 GPL-3.0 조건으로 소스 코드를 함께 공개해야 합니다.

agent-shell 소개 글 (저자 블로그)

agent-shell 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 글은 파이토치 한국 사용자 모임이 직접 정리한 글입니다. 새 글을 놓치지 않으시려면 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로 알림을 받으시고, 회원으로 가입하시면 주요 글들을 이메일로도 보내드립니다!

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~