xenodium/agent-shell

👉 @xenodium의 GitHub Sponsors를 통해 이 작업을 후원해 주세요 (제 블로그를 확인해 보세요)

유용한 LLM 토큰(tokens) 비용을 지불하고 계신 만큼, 이 프로젝트의 개발과 유지보수를 후원하는 것을 고려해 보세요. 여러분의 도움으로 저는 이 노력을 더욱 지속 가능하게 만들 수 있습니다.

감사합니다!

ACP (Agent Client Protocol)를 기반으로 LLM 에이전트(agents)와 상호작용하는 네이티브 Emacs 셸(shell)입니다.

agent-shell을 사용하면 Gemini CLI, Claude Agent, Auggie, Mistral Vibe 또는 기타 ACP 기반 에이전트와 채팅할 수 있습니다.

agent-shell 0.47 업데이트.
agent-shell 0.25 업데이트.
agent-shell 0.17 개선 사항 + MELPA.
agent-shell 0.5 개선 사항.
Emacs agent-shell 소개 (ACP 기반).
acp.el 소개.

agent-shell은 ACP (Agent Client Protocol)를 통해 에이전트와 통신하기 위해 acp.el에 의존합니다.

이제 agent-shell 경험을 확장하기 위한 몇 가지 추가 패키지를 제공합니다:

emacs-skills: Emacs를 위한 Claude Agent 기술(skills).
agent-shell-to-go: Slack을 통해 모바일 또는 다른 기기에서 agent-shell 세션과 상호작용.
agent-circus: 샌드박스화된 Docker 컨테이너에서 AI 코딩 에이전트 실행.
agent-shell-sidebar: agent-shell을 위한 사이드바(sidebar) 애드온.
agent-shell-bookmark: agent-shell 세션에 대한 북마크(bookmark) 지원.
agent-shell-workspace: 여러 agent-shell 세션을 관리하기 위한 전용 탭 바(tab-bar) 워크스페이스.
agent-shell-manager: agent-shell 버퍼(buffers)의 표 형식 보기 및 관리.
agent-review: agent-shell을 위한 코드 리뷰(code review) 인터페이스.
agent-shell-attention.el: agent-shell을 위한 모드라인(mode-line) 주의 추적기.
agent-shell-knockknock: knockknock.el을 통한 agent-shell 알림.
agent-shell-notifications: agent-shell 이벤트를 위한 데스크톱 알림.
meta-agent-shell: 에이전트 간 통신, 작업 추적 및 프로젝트 수준의 디스패칭(dispatching)을 포함한 agent-shell용 멀티 에이전트 조정 시스템.
agent-shell-macext: agent-shell을 위한 macOS 전용 개선 사항.
agent-shell-org-transcript: agent-shell을 위한 Org-mode 트랜스크립트(transcripts).

org-roam 통합 기능이 포함된 세션(sessions). - ob-agent-shell: agent-shell 소스 블록(source blocks)을 실행하기 위한 Org Babel 백엔드(backend). - agent-recall: agent-shell 대화 트랜스크립트(transcripts)를 검색, 브라우징 및 재개. - agent-shell-pet: agent-shell 세션 상태를 방송하는 Codex 스타일의 펫(pets).

20Y: Emacs에서의 에이전틱(Agentic) 개발 워크플로(workflow).
Skye: Emacs를 통해 LLM을 사용하는 방법.
sincebyte: Agent Shell Cursor Agent CLI.
Naputo: Emacs에서 실행되는 agent-shell ACP 클라이언트를 시작할 때 세션을 선택하는 방법.
vandee: Emacs에서 OpenCode를 활용한 나의 에이전트 연습.
Fedora Project Wiki: AI/ML 특별 관심 그룹(Special Interest Group).

멋진 아이콘을 제공해 준 Lobe Icons에 감사드립니다.

Anthropic의 Claude Agent(이전 명칭 Claude Code)의 경우, claude-agent-acp 지침을 따르십시오. 일반적으로 다음과 같습니다:

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

참고: 바이너리(binary)를 전역(globally)으로 설치하여 PATH에서 사용할 수 있도록 하려면 -g 플래그가 필요합니다. 설치 후, 터미널에서 which claude-agent-acp를 실행하여 사용 가능한지 확인하십시오.

선택 사항: Claude 구독을 사용하려는 경우 Claude Agent 자체가 필요할 수도 있습니다(최소 한 번은 Emacs 외부에서 CLI를 실행하여 구독에 로그인한 다음 Emacs에서 agent-shell을 사용하십시오). 설치를 위해 Claude Agent의 시작하기(get started) 가이드를 따르십시오.

OpenAI의 Codex의 경우, zed/codex-acp를 설치하고 codex-acp 실행 파일이 PATH에 있는지 확인하십시오.

Google의 Gemini CLI의 경우, --experimental-acp 플래그를 지원하는 최신 릴리스(release)를 반드시 확보하십시오.

Goose CLI의 경우, goose를 설치하고 goose 실행 파일이 PATH에 있는지 확인하십시오.

Cursor agent의 경우, 다음 명령어로 설치하십시오:

npm install -g @blowmage/cursor-agent-acp

자세한 내용은 https://github.com/blowmage/cursor-agent-acp-npm 을 참조하십시오.

Kimi Code CLI의 경우, 다음 명령어로 설치하십시오:

curl -L code.kimi.com/install.sh | bash

자세한 내용은 https://www.kimi.com/code 를 참조하십시오.

Kiro CLI의 경우, 다음 명령어로 설치하십시오:

curl -fsSL https://cli.kiro.dev/install | bash

자세한 내용은 https://kiro.dev/docs/cli/acp/ 를 참조하십시오.

Qwen Code의 경우, 다음 명령어로 설치하십시오:

npm install -g @qwen-code/qwen-code@latest

자세한 내용은 https://github.com/QwenLM/qwen-code 를 참조하십시오.

Auggie CLI의 경우, 다음 명령어로 설치하십시오:

npm install -g @augmentcode/auggie

자세한 내용은 https://docs.augmentcode.com/cli/overview 를 참조하십시오.

Mistral Vibe의 경우, 다음 명령어로 설치하십시오:

uv tool install mistral-vibe

자세한 내용은 https://github.com/mistralai/mistral-vibe 를 참조하십시오.

Factory Droid의 경우, Droid를 설치하십시오:

curl -fsSL https://app.factory.ai/cli | sh

자세한 내용은 https://factory.ai 를 참조하십시오.

Pi coding agent의 경우, pi-acp 어댑터를 설치하십시오:

npm install -g pi-acp

자세한 내용은 https://github.com/svkozak/pi-acp 를 참조하십시오.

agent-shell은 MELPA에서 사용 가능한 shell-maker를 통해 내장된 comint-shell로 구동됩니다.

agent-shell과 그 의존성인 acp.el은 현재 모두 MELPA에서 사용할 수 있습니다.

다음과 같이 설치할 수 있습니다:

(use-package agent-shell
:ensure t
:ensure-system-package
...

이렇게 하면 필요한 의존성(acp.el 및 shell-maker)이 자동으로 설치됩니다.

Doom Emacs를 사용 중이며 package! 매크로를 사용하고 싶다면:

(package! shell-maker)
(package! acp)
(package! agent-shell)

doom sync를 실행한 후 재시작하십시오.

설정 전에 require를 포함하십시오:

(require 'acp)
(require 'agent-shell)
;; 나머지 설정...

사용하고자 하는 에이전트 제공자(agent providers)에 대한 인증을 설정하십시오.

agent-shell-make-environment-variables를 사용하여 agent-shell-*-environment 변수를 커스텀함으로써 생성된 에이전트 프로세스에 환경 변수(environment variables)를 전달할 수 있습니다. 이 헬퍼 함수는 키/값 쌍을 받아 에이전트가 시작될 때 이를 내보냅니다(export).

(setq agent-shell-anthropic-claude-environment
(agent-shell-make-environment-variables
"ANTHROPIC_API_KEY" (auth-source-pass-get 'secret "anthropic-api-key")
...

기본적으로 에이전트 프로세스는 최소한의 환경으로 시작됩니다. 부모 Emacs 프로세스로부터 환경 변수를 상속받으려면 agent-shell-make-environment-variables에서 :inherit-env t 파라미터를 사용하십시오:

(setenv "ANTHROPIC_API_KEY" (auth-source-pass-get 'secret "anthropic-api-key"))
(setq agent-shell-anthropic-claude-environment
(agent-shell-make-environment-variables :inherit-env t))

이를 통해 PATH, HOME 등과 같은 환경 변수 (environment variables)가 Emacs 세션으로부터 에이전트 프로세스 (agent process)에서 사용 가능하도록 보장하면서도, 동시에 특정 변수를 재정의(override)하거나 추가할 수 있습니다.

:load-env 파라미터를 사용하여 .env 파일로부터 환경 변수를 로드할 수 있습니다. 이는 단일 파일과 다중 파일을 모두 지원합니다:

;; 단일 .env 파일로부터 로드
(setq agent-shell-anthropic-claude-environment
(agent-shell-make-environment-variables
...

.env 파일은 한 줄에 하나의 변수가 있는 KEY=value 형식을 포함해야 합니다. 주석 (#으로 시작하는 줄)과 빈 줄은 무시됩니다.

로그인 기반 인증 (login-based authentication, 기본값):

(setq agent-shell-anthropic-authentication
(agent-shell-anthropic-make-authentication :login t))

API 키 인증 (API key authentication):

;; 문자열 사용
(setq agent-shell-anthropic-authentication
(agent-shell-anthropic-make-authentication :api-key "your-anthropic-api-key-here"))
...

OAuth 토큰 인증 (OAuth token authentication) (claude setup-token에서 얻는 CLAUDE_CODE_OAUTH_TOKEN):

;; 문자열 사용
(setq agent-shell-anthropic-authentication
(agent-shell-anthropic-make-authentication :oauth "your-oauth-token-here"))
...

Anthropic 호환 대체 API 엔드포인트 (API endpoints)의 경우, 환경 변수를 통해 설정하십시오:

(setq agent-shell-anthropic-claude-environment
(agent-shell-make-environment-variables
"ANTHROPIC_BASE_URL" "https://api.moonshot.cn/anthropic"
...

로그인 기반 인증 (login-based authentication, 기본값):

(setq agent-shell-google-authentication
(agent-shell-google-make-authentication :login t))

API 키 인증 (API key authentication):

;; 문자열 사용
(setq agent-shell-google-authentication
(agent-shell-google-make-authentication :api-key "your-google-api-key-here"))
...

Vertex AI 인증:

(setq agent-shell-google-authentication
(agent-shell-google-make-authentication :vertex-ai t))

로그인 기반 인증 (기본값):

(setq agent-shell-openai-authentication
(agent-shell-openai-make-authentication :login t))

API 키 인증:

;; 문자열 사용 시
(setq agent-shell-openai-authentication
(agent-shell-openai-make-authentication :api-key "your-openai-api-key-here"))
...

OpenAI API 키 인증:

;; 문자열 사용 시
(setq agent-shell-goose-authentication
(agent-shell-make-goose-authentication :openai-api-key "your-openai-api-key-here")
...

OAuth 로그인 기반 인증:

(setq agent-shell-qwen-authentication
(agent-shell-qwen-make-authentication :login t))

로그인 기반 인증 (기본값):

(setq agent-shell-auggie-authentication
(agent-shell-make-auggie-authentication :login t))

인증 없음 (대체 인증 방법을 사용할 때):

(setq agent-shell-auggie-authentication
(agent-shell-make-auggie-authentication :none t))

API 키 인증:

;; 문자열 사용 시
(setq agent-shell-mistral-authentication
(agent-shell-mistral-make-authentication :api-key "your-mistral-api-key-here")
...

기본적으로, agent-shell은 지원되는 모든 에이전트(Claude Agent, Gemini CLI, Codex, Goose, Qwen Code, 그리고 Auggie)에 대한 설정을 포함합니다. 사용 가능한 에이전트는 agent-shell-agent-configs 변수를 통해 사용자 지정할 수 있습니다.

M-x agent-shell

알려진 모든 에이전트 중 하나를 시작하거나 재사용합니다.

agent-shell 대화형 명령을 통해 알려진 모든 에이전트 셸( agent-shell-agent-configs 참조)을 선택하고 시작할 수 있으며, 사용 가능한 경우 기존 셸을 재사용하도록 활성화합니다. 접두사 인자(C-u M-x agent-shell)를 사용하면 새 셸 세션을 강제로 시작하여 여러 에이전트 셸을 인스턴스화합니다.

특정 에이전트 셸 세션 직접 시작:

M-x agent-shell-anthropic-start-claude-code

Claude 에이전트 세션 시작: M-x agent-shell-auggie-start-agent
Auggie 에이전트 세션 시작: M-x agent-shell-openai-start-codex
Codex 에이전트 세션 시작: M-x agent-shell-google-start-gemini
Gemini 에이전트 세션 시작: M-x agent-shell-goose-start-agent
Goose 에이전트 세션 시작: M-x agent-shell-cursor-start-agent
Cursor 에이전트 세션 시작: M-x agent-shell-kiro-start-agent
Kiro CLI 에이전트 세션 시작: M-x agent-shell-mistral-start-vibe
Mistral Vibe 에이전트 세션 시작: M-x agent-shell-qwen-start
Qwen Code 에이전트 세션 시작: M-x agent-shell-droid-start-agent
Factory Droid 에이전트 세션 시작: M-x agent-shell-pi-start-agent
Pi 코딩 에이전트 세션 시작

모든 새로운 셸을 시작할 때 사용할 기본 에이전트를 설정할 수 있습니다. agent-shell을 통해 다음과 같이 설정합니다:

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

또한, agent-shell을 통해 MCP 서버를 직접 구성할 수 있습니다. 이를 사용하면 사용하는 모든 에이전트에 걸쳐 설정을 반복할 필요가 없습니다.

(setq agent-shell-mcp-servers
'(((name . "notion")
(type . "http")
...

agent-shell은 컨테이너 내에서 에이전트 및 셸 명령을 실행하는 기본적인 지원 기능을 제공합니다.

에이전트를 시작하거나 실행해야 할 셸 명령 앞에 접두사를 붙이려면 agent-shell-command-prefix를 사용하십시오. 이렇게 하면 해당 명령이 컨테이너 내부에서 실행됩니다.

(setq agent-shell-command-prefix '("devcontainer" "exec" "--workspace-folder" "."))

에이전트별로 동적인 컨테이너가 필요한 경우, 현재 agent-shell 버퍼를 받아 명령 목록을 반환하는 함수를 제공하십시오:

(setq agent-shell-command-prefix
(lambda (buffer)
(let ((config (agent-shell-get-config buffer))) 
...

동일한 에이전트 유형이라도 다른 셸 세션에 대해 서로 다른 컨테이너를 사용할 수 있습니다:

(setq agent-shell-command-prefix
(lambda (buffer)
;; 프로젝트별로 다른 컨테이너 사용
...

acp-make-client에 전달했을 수 있는 모든 :environment-variables는 다음을 참고하십시오.

컨테이너 내부에서 실행되는 에이전트 프로세스에는 적용되지 않습니다. 환경 변수는 devcontainer 설정 또는 Dockerfile을 통해 주입하는 것을 권장합니다.

다음으로, 컨테이너 경로를 로컬 작업 디렉토리로, 또는 그 반대로 변환하는 agent-shell-path-resolver-function을 설정하십시오.

Agent shell은 특히 devcontainer와 함께 사용할 수 있는 agent-shell-devcontainer-resolve-path 함수를 제공합니다. 이 함수는 .devcontainer/devcontainer.json에 지정된 workspaceFolder를 읽거나, 그렇지 않은 경우 /workspaces/<repository-name>이라는 기본값을 사용합니다.

(setq agent-shell-path-resolver-function #'agent-shell-devcontainer-resolve-path)

xenodium/agent-shell

요약

핵심 포인트

댓글