MercuryCLI: 터미널에서 AI 코딩 에이전트 실행

Website: mercury-cli.ai

Mercury는 사용자의 로컬 저장소(repository) 내 터미널에서 AI 코딩 에이전트를 실행합니다. 이 에이전트는 파일을 읽고 수정하며, 명령을 실행하고 그 결과를 확인합니다. 사용자는 제공자(provider), 모델(model), 그리고 에이전트가 수행할 수 있는 권한을 직접 선택할 수 있습니다.

각 세션은 고유의 대화 기록, 모델, 권한 및 작업 공간을 유지합니다. 한 작업을 진행하는 동안 다른 작업을 실행 상태로 남겨두고, 필요할 때 다시 돌아와서 이어서 작업할 수 있습니다. 같은 채팅 내에서 제공자나 모델을 전환하거나, 에디터(editor)에서 Mercury를 사용하거나, 스크립트에서 헤드리스(headless) 방식으로 실행하거나, 나중에 작업을 예약할 수도 있습니다.

저는 여러 에이전트와 모델을 사용하여 장시간 세션에 걸쳐 Mercury를 개발하는 데 활용합니다. 이러한 작업 과정을 추적하는 것이 중요하기 때문에, 현재 어떤 작업이 진행 중인지, 무엇이 변경되었는지, 그리고 사용자의 결정이 필요한 부분이 무엇인지를 파악할 수 있습니다.

Mercury는 소스 코드를 공개(source-available)하고 있습니다. 생산 환경에서 사용할 조건은 라이선스(Licence)를 참조하십시오.

Apple silicon 및 Intel Mac, Linux x64, Windows x64용 릴리스 아카이브가 제공됩니다. git을 별도로 설치해야 합니다. 각 아카이브에는 Node와 ripgrep이 포함되어 있으므로, 별도의 Node 설치는 필요하지 않습니다.

다음 중 하나의 설치 방법을 선택하십시오:

curl -fsSL https://mercury-cli.ai/install | sh # macOS 및 Linux x64
irm https://mercury-cli.ai/install.ps1 | iex # Windows x64, PowerShell 7에서
brew install Whq02/mercury/mercury # Homebrew: macOS 및 Linux x64
...

설치 후에는 새 터미널을 열고 mercury --version을 실행하여 확인하십시오. 그런 다음 저장소(repository)에서 mercury를 실행하여 첫 번째 작업을 시작합니다.
터미널에 Mercury를 사용하려면, 설치 프로그램이 출력하는 PATH 지침을 따르십시오.

설치 경로, 업데이트 및 릴리스 검증

셸(shell) 및 PowerShell 설치 프로그램은 플랫폼에 맞는 최신 릴리스를 가져와서, SHA256SUMS.txt 파일과 SHA-256 값을 비교하고, 압축을 풀고, 아카이브 자체의 mercury install 명령어를 실행합니다.

Homebrew와 npm 패키지는 각각 특정 릴리스에 고정(pinned)되어 있으며 태그가 지정된 후에 재게시되므로, 최신 릴리스보다 뒤처질 수 있습니다. npm 패키지인 mercury-tech-cli는

,은 핀된 릴리스를 다운로드하는 런처입니다; mise는 동일한 패키지를 설치합니다.

Mercury의 설치는 사용자 로컬(user-local)이며 관리자 접근 권한이 필요하지 않습니다. 따라서 설치 명령을 다시 실행해도 안전합니다.

릴리스 버전은 설정 홈 디렉터리인 ~/.mercury/versions/<version> (Windows에서는 %USERPROFILE%\.mercuryuilds가 아닌, 원문 그대로 유지: %USERPROFILE%\.mercuryuilds)에 존재합니다. mercury 명령어는 macOS 및 Linux에서는 ~/.local/bin에, Windows에서는 %LOCALAPPDATA%\Mercury\bin에 설치됩니다.

mercury install은 해당 명령어의 디렉터리를 PATH에 한 번 추가합니다: 쉘 시작 파일에 보호된 라인으로 추가되거나, Windows 사용자 PATH에 항목으로 추가됩니다. 새 터미널을 열면 변경 사항이 자동으로 적용됩니다.

어떤 설치 방법을 사용하든 mercury update를 사용하세요.

쉘(shell) 또는 PowerShell 설치 프로그램, 또는 mercury install로 설치된 경우, Mercury는 제자리에서 업데이트됩니다. --check는 업데이트 여부를 확인하고, --status는 업데이트 상태를 보고하며, --rollback은 디스크에 남아있는 이전 버전으로 되돌립니다.

Homebrew의 경우, brew upgrade Whq02/mercury/mercury를 실행하기 전에 사용자에게 묻습니다. 기본 응답은 '아니요'이므로, 승인하려면 y를 입력하세요. Mercury는 명령어 출력을 스트리밍하고 나중에 설치된 버전을 확인합니다. 스크립트에서 프롬프트를 건너뛰려면 --yes를 사용하세요.

npm 런처는 설치 프로그램과 동일한 릴리스 레이아웃을 사용하며, 각 실행은 설치된 릴리스에 위임됩니다. 따라서 mercury update는 Mercury 자체 업데이트 채널을 통해 npm 설치를 제자리에서 업데이트합니다. npm update -g mercury-tech-cli는 패키지가 처음 실행될 때만 설치하는 릴리스만 변경합니다. 이는 mise를 사용할 때도 마찬가지입니다.

--check는 모든 설치 방법의 동일한 릴리스 목록을 읽어 사용자의 업데이트 방법을 알려줍니다. 업데이트가 가능한 경우, 홈 화면 오른쪽 하단에 vX.Y.Z available · mercury update가 표시되며, 채팅에는 임시 알림이 표시됩니다. 둘 다 숨기려면 MERCURY_UPDATE_NOTICE=0을 설정하세요.

설치 및 업데이트 요청은 공개 릴리스 목록과 아카이브를 익명으로 가져옵니다. 계정이나 토큰 없이 실행할 수 있습니다. 만약 익명 요청이 거부되면, Mercury는 로그인된 GitHub CLI (gh)를 사용합니다.

업데이트 후, Mercury는 PATH에 있는 명령어가 업데이트된 설치본을 가리키는지 확인합니다. 다른 설치본이 우선권을 갖거나, 업데이트된 명령어가 PATH에서 누락된 경우, 문제점과 해결 방법을 설명합니다. mercury health가 동일한 문제를 보고합니다.

릴리스를 활성화하기 전에, Mercury는 아카이브를 SHA256SUMS.txt와 비교하여 확인합니다. 또한 업데이트 단계를 거치기 전에 컴파일된 신뢰 목록(trust roster)에 있는 Mercury 릴리스 키로 서명된 페이로드도 필요로 합니다. 서명이 거부되면 활성 설치본은 변경되지 않습니다.

--allow-unsigned를 사용하여 서명되지 않은 페이로드를 수락할 수 있습니다. 하지만 Mercury는 여전히 알 수 없는 서명 키, 잘못 구성된 서명 블록, 변조된 내용을 거부합니다. 명령어 결과와 로컬 기록 모두에서 사용자가 서명되지 않은 페이로드를 허용했음을 보여줍니다.

1.0.0-beta.3 버전부터는 아카이브가 패키징 과정에서 서명되며, 그 서명은 게시 전에 검증됩니다. 검증된 설치본은 시작 시 서명 알림을 추가하지 않습니다. mercury health는 signed — key 627b54b734ca0e72를 보여줍니다.

1.0.0-beta.2 아카이브는 서명이 없습니다. 이러한 설치본은 Mercury를 명령어나 플래그 없이 대화형으로 시작할 때, 한 번에 provenance — unsigned를 표시합니다. 건강 검사는 계속해서 해당 상태를 보여줍니다. 이는 아카이브 매니페스트에 서명이 없다는 의미이며, 다운로드는 여전히 SHA256SUMS.txt와 비교됩니다.

docs/TRUST.md는 검증 결과와 아카이브를 수동으로 확인하는 방법을 설명합니다. docs/TERMINAL-RUNTIME.md는 시작 시 검증에 대해 다룹니다.

Linux arm64의 경우, 설치 프로그램 지침을 따라 소스에서 빌드하십시오. Windows arm64의 경우, 에뮬레이션 하에서 x64 아카이브를 사용하십시오. Mercury는 두 플랫폼 모두에 네이티브 아카이브가 없습니다.

Intel Mac용 아카이브는 1.0.0-beta.3부터 이용 가능합니다. 이들은 Apple silicon 러너에서 크로스 패키징되며, 배포 전에 Rosetta를 통해 시작 시 테스트됩니다. 1.0.0-beta.2를 사용하는 Intel Mac은 소스 빌드가 필요합니다.

릴리스 아카이브에는 Node 24 LTS가 포함되어 있습니다. 런처인 mercury install와 mercury update는 이 번들된 런타임을 사용하며, git만이 릴리스 자체에 필요한 유일한 별도 요구 사항입니다.

소스에서 빌드하려면 다음이 필요합니다:

Node 24 LTS: 지원 범위인 >=24.20.0 <25 버전이어야 합니다. .node-version은 빌드에 사용되고 릴리스 아카이브에 포함되는 패치를 지정합니다. bun 1.3.x는 빌드를 위해 필요하며, 릴리스에는 번들되지 않습니다. git. Windows에서는 Windows Terminal 내부의 PowerShell 7 또는 VS Code 터미널에서 실행하십시오. 자세한 내용은 docs/INSTALL-WINDOWS-FROM-SOURCE.md를 참조하십시오.

Node 최소 버전에는 nodejs/node#56645에 대한 수정 사항이 포함되어 있습니다. 24.20.0 미만에서는 Windows에서 도구를 호출하는 비헤드리스 run 명령이 종료 시 중단됩니다.

런처는 다음 순서로 Node를 선택합니다: 명시적인 MERCURY_NODE 바이너리, 번들된 런타임, 그런 다음 PATH에 있는 호환 가능한 Node 설치본입니다. 런타임이 누락된 경우, 런처가 오류를 보고합니다.

Git for Windows는 bash.exe를 제공하며, Bash 도구는 사용 가능할 때 이를 사용합니다. 릴리스 아카이브에는 Mercury의 bash 호환 셸 엔진도 포함되어 있습니다. 이는 bash.exe가 누락된 경우 Windows에서 자동으로 사용됩니다.

활성화된 셸과 그 이유를 확인하려면 건강 검진(health check)의 shell 행을 읽으십시오. bash.exe가 사용 가능한 경우 Git Bash를, 누락된 경우 번들된 엔진을 표시합니다. 번들된 엔진은 .cmd와 같은 래퍼(shim)인 npm을 실행하기 위해 cmd /c npm …이 필요합니다. 래퍼를 직접 실행하면 실패합니다. cd 이후에는 엔진에 실행하려는 프로그램의 절대 경로를 제공해야 합니다.

MERCURY_SHELL_ENGINE=brush로 설정하거나, Shell engine 아래 /config에서 brush를 선택하여 bash.exe가 사용 가능할 때도 번들된 엔진을 사용할 수 있습니다.
MERCURY_SHELL_ENGINE=system은 시스템의 bash.exe만 사용합니다.

엔진 팩이나 Git for Windows 없이 소스 빌드를 해도 시작은 되지만, Bash 도구는 사용할 수 없습니다. PowerShell 도구는 계속 사용 가능하며, shell 진단 기능에서 Bash 지원 복원 방법을 설명합니다.

Mercury는 bun으로 빌드되며 Node 24 LTS에서 실행됩니다:

bun run setup # 한 번만; bun install + 패키지 판매(vendored packs)
bun run build.ts # dist/mercury.mjs + dist/manifest.json 작성
node dist/mercury.mjs --version
...

전체 화면 인터페이스는 실제 TTY가 필요하지만, 최소 터미널 크기는 없습니다. 전체 레이아웃은 가로 100열에 세로 26행에서 시작하며, 더 작은 창에서는 간소화된 레이아웃을 사용합니다.

Mercury는 터미널이 COLORTERM=truecolor를 통해 지원한다고 광고하거나 iTerm2, Ghostty, WezTerm, Kitty, Windows Terminal 또는 VS Code로 인식하는 경우 24비트 색상을 사용합니다. 다른 터미널은 macOS 15 이전의 Apple Terminal을 포함하여 256색을 사용합니다.

건강 검사(health check)의 터미널 색상 행은 감지된 깊이와 이유를 보고합니다. True color를 지원하지만 광고하지 않는 터미널의 경우 MERCURY_TRUECOLOR=1을 설정하거나, 256색을 강제하려면 MERCURY_TRUECOLOR=0을 설정하십시오.

setup은 번들된 기능 팩(capability packs): pyright, debugpy, js-debug, 추가 구문(extra grammars), 플랫폼의 Node 런타임, 그리고 brush를 가져옵니다. 다운로드에 실패하면 해당 팩은 건너뛰어지며, 빌드와 영향을 받는 기능에서 누락된 구성 요소가 보고됩니다. bun install만 실행하면 해당 팩이 없는 빌드가 생성됩니다.

음성 지원을 빌드하려면 Rust를 설치한 후 setup을 실행하십시오. 그러면 native/voice가 빌드됩니다. 또한 cmake를 추가하여 native/whisper도 빌드할 수 있습니다. 둘 중 어느 것도 도구가 부족하면 setup이 이를 건너뛰고 건강 검사에서 누락된 애드온을 보고합니다. 두 애드온 모두 사용자의 컴퓨터에서 컴파일됩니다. 상위 버전(upstream)에 Windows 바이너리가 없기 때문에 윈도우 셸 엔진도 그곳에서 컴파일됩니다.

brush는 Rust로 작성된 bash 호환 셸입니다. macOS와 Linux에서는 선택 사항이며, 시스템 셸이 기본값으로 유지됩니다. /config (shell.engine) 또는 MERCURY_SHELL_ENGINE=brush를 통해 선택할 수 있습니다.

Bash용으로 사용하려면 지속적인 셸 상태를 가진 도구 호출(tool calls)이 필요합니다. Windows에서는 bash.exe가 누락된 경우 자동으로 선택됩니다. 자세한 내용은 docs/TERMINAL-RUNTIME.md를 참조하십시오.

빌드는 dist/에만 작성합니다. 설정 및 세션은 ~/.mercury 또는 MERCURY_CONFIG_DIR로 지정된 디렉터리에 저장되며, 첫 실행 시 생성됩니다. Windows에서는 node dist\mercury.mjs를 직접 실행하십시오.

scripts/ops/deploy-runtime.sh는 깨끗한 트리 빌드를 새로운 <config home>/runtime/builds/<build> 폴더에 게시하고 runtime/current를 그곳으로 지정합니다 (runtime/dist는 동일 링크의 이전 이름입니다). scripts/ops/deploy-launcher.sh는 런처를 <config home>/bin/mercury에 설치합니다. 해당 디렉터리를 PATH에 추가하십시오. zsh의 경우:
echo 'export PATH="$HOME/.mercury/bin:$PATH"' >> ~/.zshrc

런처가 런타임을 찾지 못하면 오류와 함께 중단됩니다. 다른 빌드로 전환하지 않습니다. Node 선택은 Requirements에 있는 순서를 따릅니다.

릴리스 설치를 하려면 mercury install 또는 mercury update를 실행하십시오. 이 명령어들은 소스 체크아웃을 변경하지 않으며 GitHub 로그인도 필요 없습니다. Mercury는 익명 릴리스 요청이 거부된 경우에만 gh를 참조합니다.

AGENTS.md는 간단한 빌드 및 실행 가이드입니다. BUILD-NOTES.md는 빌드를 더 자세히 다룹니다.

첫 번째 대화형 실행 시, 모양을 선택한 다음 제공업체(provider)에 로그인하십시오. 화면은 탐색하는 동안 테마 변경 사항을 미리 보여줍니다. True Black이 기본값이며, 다른 옵션은 오아시스 다크 테마입니다. 이는 나중에 /appearance로 변경할 수 있습니다.

또한

다음으로, Mercury는 사용자가 열어준 폴더를 신뢰하는지 묻습니다. 작업 공간 설정(workspace configuration)에 의해 요청된 것은 이 신뢰를 부여하기 전까지 실행되지 않습니다. 이 승인은 전체 리포지토리에 적용되며, 거부할 경우 Mercury가 종료됩니다. 자세한 내용은 docs/TRUST.md를 참조하세요.

일반적인 대화형 시작은 Boot face라고 불리는 홈 화면을 엽니다. 여기에는 10개의 메뉴 항목이 있으며, 'Continue Last Session'은 세션 기록이 있는 후에만 나타납니다:

<폴더>에서 새 세션(New Session in <folder>): 현재 폴더에서 새로운 세션을 시작합니다.
가장 최근 세션 계속하기(Continue Last Session): 가장 최근의 채팅으로 돌아갑니다.
부트 메뉴(Boot Menu): 모션, 크루메이트(crewmates, 서브 에이전트) 및 워크플로우를 포함하여 향후 세션을 구성합니다.
MCPs & Skills: 다음 세션에 무엇을 로드할지 선택합니다. 자세한 내용은 docs/KIT.md를 참조하세요.
Agents: 에이전트를 생성하고 편집합니다.
Health Check: 설치 상태를 확인합니다.
Saturn Scheduler: 세션을 예약합니다. 자세한 내용은 docs/SATURN.md를 참조하세요.
Logins: 제공업체 계정에 연결합니다.
Session Concourse: 현재 프로젝트의 세션 목록을 엽니다.
Sessions · Projects: 세션 또는 리포지토리를 선택할 수 있게 해줍니다.