ConardLi/easy-agent: 터미널 코딩 에이전트

사용자가 작성한 코드를 읽고, 파일을 수정하며, 사용자가 제어하는 권한 규칙 하에 명령을 실행하는 터미널 코딩 에이전트입니다.

Easy Agent (eagent)는 리포지토리 옆의 터미널에서 작동합니다. 작업을 설명하면 이를 계획하고, 파일을 읽고 변경하며, 테스트 또는 셸 명령을 실행하고, 결과를 보고합니다. 사용자의 장치를 변경할 수 있는 모든 동작은 권한 규칙(permission rules), 작업 공간 신뢰(workspace trust), 그리고 선택적인 OS 레벨의 샌드박스를 거칩니다. Anthropic, OpenAI 호환 모델, Gemini, 그리고 로컬 모델과 함께 작동합니다.

이 코드는 실행될 뿐만 아니라 읽힐 수 있도록 작성되었습니다. 모델 통신, 에이전트 루프(agentic loop), 도구(tools), 권한(permissions), 컨텍스트 관리(context management), 그리고 각 확장 시스템은 별도의 레이어에 존재합니다. 아래 링크된 문서를 통해 보안 관련 부분이 어떻게 작동하고 왜 그렇게 하는지 설명하며, 학습 경로는 코드 스냅샷과 함께 순서대로 레이어를 안내하여 사용자가 직접 에이전트를 구축하거나 커스터마이징하는 데 도움을 줍니다.

중국어 문서: README.zh-CN.md

• 익숙하지 않은 코드베이스를 탐색하세요: 어떤 부분이 처리되는지, 흐름(flow)이 어떻게 작동하는지, 또는 변경 사항이 무엇에 영향을 미칠지 질문할 수 있습니다.
• 여러 파일을 수정하고, diff를 검토하며, 잘못된 경우 /rewind로 되돌릴 수 있습니다. - 빌드와 테스트를 실행하고, 실패 내용을 읽고, 수정 작업을 반복합니다.
• 먼저 읽기 전용 계획 모드(read-only Plan Mode)에서 변경 사항을 계획한 다음, 이를 수행할 수 있습니다.
• 스크립트로 작성하세요: 입력을 eagent -p로 파이프하여 CI 또는 셸 스크립트에서 텍스트, JSON, 또는 NDJSON 출력을 읽을 수 있습니다. - MCP 서버, 스킬(skills), 사용자 지정 에이전트(custom agents), 후크(hooks), 및 플러그인을 통해 자체 도구를 연결할 수 있습니다.

요구 사항: Node.js 22 이상, npm, 그리고 최소 하나의 지원되는 모델 제공업체에 대한 자격 증명(credentials)입니다.

npm install -g --ignore-scripts eagent
eagent --version

또는 설치 없이 시도해 보세요:

npx --yes eagent@latest

macOS 및 Linux에서는 설치 프로그램도 제공됩니다. 이는 Node.js를 확인하고, --ignore-scripts 옵션으로 동일한 npm 패키지를 설치하며, eagent가 PATH에 있는지 확인합니다. 이 과정에서 Node.js를 설치하거나 패키지 라이프사이클 스크립트를 실행하지는 않습니다.

패키지는 두 개의 명령어인 eagent와 긴 별칭(alias)인 easy-agent를 설치합니다.

export ANTHROPIC_AUTH_TOKEN="your-token"
cd your-project
eagent

폴더에서 처음 사용할 때, Easy Agent는 사용자에게 신뢰하는지 묻습니다. 그런 다음 요청을 입력하세요. 예를 들어 이 저장소에서 요청은 어떻게 인증되는지 설명해줘와 같이요. 명령어는 /help를 입력하고; 종료하려면 Ctrl+D를 누르세요.

• 파일 및 코드 도구: 읽기(Read), 쓰기(Write), 편집(Edit), 다중 편집(MultiEdit), Glob, Grep, Bash, 그리고 Windows용 PowerShell
• 웹 및 외부 도구: WebFetch, WebSearch, MCP 도구 및 리소스
• 안전한 실행: allow/ask/deny 규칙, Plan Mode, Auto Mode, workspace trust, hooks, 제어된 서브 프로세스(controlled subprocesses), 개인 로컬 데이터, 그리고 macOS 및 Linux용 fail-closed 셸 샌드박싱(shell sandboxing)
• 장기 작업: TodoWrite, 영구적인 태스크 그래프(persistent task graphs), 서브 에이전트(sub-agents), 백그라운드 실행(background runs), Git worktree 격리(isolation), 그리고 Agent Teams
• 컨텍스트 및 연속성: 내구성 있는 지속성(durable persistence), 재개(resume), 압축(compaction), 토큰 예산(token budgets), 프로젝트 메모리 (AGENTS.md / AGENT.md), 파일 체크포인트(file checkpoints), 그리고 되감기(rewind) - 확장성: 스킬(skills), 사용자 지정 에이전트(custom agents), 슬래시 명령어(slash commands), 출력 스타일, hooks, MCP 서버, 플러그인, 및 정적 마켓플레이스
• 인터페이스: 대화형 터미널 UI, 헤드리스 텍스트/JSON/NDJSON 출력, 임베디 가능한 세션 SDK (eagent/sdk), 데스크톱 앱 및 기타 프로그램을 위한 stdio 기반 JSON-RPC (eagent --rpc), Zed, JetBrains IDEs 및 기타 ACP 에디터를 위한 Agent Client Protocol (eagent --acp), 이미지 및 스크린샷, 그리고 여러 모델 프로토콜

• 모든 플랫폼에서 Node.js 22 이상이 필수입니다. 이전 버전은 설명 메시지와 함께 종료됩니다.
• install.sh 설치 프로그램은 macOS와 Linux를 지원합니다. Windows에서는 npm으로 설치하세요. - Windows의 경우, 로컬 데이터는 POSIX 0600 /0700 모드 대신 사용자 프로필의 ACL(Access Control Lists)에 의존합니다./doctor

이것을 보고합니다. - 클립보드 이미지 붙여넣기는 다음 중 하나가 필요합니다:
pngpaste

또는 osascript

macOS의 경우, 그리고 Linux에서는 xclip 또는 xsel을 사용해야 합니다.

플랫폼별 설정을 포함하여 샌드박스 보안(Sandbox security)을 참조하십시오. 여기에는 사용자 네임스페이스에 대한 Ubuntu AppArmor 제한 사항이 포함됩니다.

Easy Agent는 모델이 실수를 할 수 있으며, 열게 되는 저장소가 적대적일 수 있다고 가정합니다. 여러 독립적인 계층이 세션이 수행할 수 있는 작업을 제한합니다:

권한 규칙(Permission rules). 파일을 변경하거나 명령을 실행하거나 네트워크에 접근하는 도구 호출은 허용(allow), 요청(ask), 거부(deny) 규칙과 비교됩니다. 거부 규칙이 항상 우선합니다. 기본 모드에서는 허용되지 않은 모든 것에 대해 요청하며, 읽기 전용으로 입증된 Bash 명령어는 프롬프트 없이 실행될 수 있습니다 (분석 규칙).권한 모드(Permission modes). default는 위험한 작업 전에 요청합니다. plan (--plan)은 읽기 전용 도구만 허용합니다. auto (--auto)는 분류기가 안전한 호출을 승인하고, 위험한 호출을 차단하며, 확신이 서지 않을 때 프롬프트로 폴백(fall back)하도록 합니다. 헤드리스 실행(-p)은 --dangerously-skip-permissions를 전달하지 않는 한 프롬프트를 유발하는 호출을 거부합니다. ; 거부 규칙은 여전히 적용됩니다.작업 공간 신뢰(Workspace trust). 프로젝트 설정, .env, 프로젝트 MCP 서버, 훅(hooks), 플러그인, 모델 프로필은 폴더를 신뢰할 때까지 무시됩니다. 신뢰는 홈 디렉터리에 저장되므로, 저장소가 스스로를 신뢰한다고 표시할 수 없으며, 프로젝트 파일이 셸에서 상속된 자격 증명을 대체할 수 없습니다 (자세히).경로 경계(Path boundaries). 파일 도구는 실제 경로를 해석하고 작업 공간 및 허용된 디렉터리 외부의 심볼릭 링크를 따르는 것을 거부합니다 (자세히).셸 샌드박스(Shell sandbox). sandbox.enabled가 설정되면, Bash는 쓰기만 허용하는 정책과 프록시 필터링된 네트워크가 적용된 OS 샌드박스 내에서 실행됩니다. 샌드박스를 시작할 수 없는 경우, 명령은 샌드박스 외부에서 실행되는 대신 차단됩니다 (자세히).로컬 데이터(Local data). 세션, 설정, 신뢰 상태 및 로그는 사용자 계정에만 사적입니다. 스트림 디버그 로깅은 활성화하지 않는 한 꺼져 있으며, 활성화된 경우 자격 증명을 마스킹합니다 (자세히).

Easy Agent는 어떠한 분석(analytics)이나 원격 측정(telemetry)도 전송하지 않습니다. 네트워크 요청은 설정한 모델 제공업체로, 추가한 MCP 서버 및 플러그인 소스로, 그리고 해당 도구들이 허용될 때 WebFetch/WebSearch 대상으로 전송됩니다. /doctor

설정은 다음 순서(가장 낮은 우선순위부터 가장 높은 우선순위)로 병합되는 JSON 파일들입니다:

• 사용자 (User):
  ~/.easy-agent/settings.json

• 프로젝트 (Project):
  <project>/.easy-agent/settings.json

(공유되며, 폴더가 신뢰될 때 한 번 적용됨) - 로컬 (Local):
<project>/.easy-agent/settings.local.json

(개인적이며, 폴더가 신뢰될 때 한 번 적용됨) - 커맨드 라인 (Command line):
--settings <파일>

, --model

, --permission-mode

, 그리고 유사한 플래그들 - 관리 정책 (Managed policy):
macOS의 경우: /Library/Application Support/EasyAgent/managed-settings.json
Linux의 경우: /etc/easy-agent/managed-settings.json
Windows의 경우: %PROGRAMDATA%\EasyAgent\managed-settings.json

프로젝트 .env 파일은 프로젝트 및 로컬 설정 이후에, 신뢰된 폴더에 한해서만 적용됩니다. 기능 스위치(Feature switches)는 구성(Configuration) 및 기능 제어(feature controls)에서 설명합니다.

순수한 Anthropic 모델 이름의 경우, 환경 변수만으로 충분합니다:

export ANTHROPIC_AUTH_TOKEN="your-token"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514" # 선택 사항
eagent

이름이 지정된 Anthropic, OpenAI 호환, Gemini 및 로컬 프로필은 settings.json에 포함됩니다:

:

{
"defaultModel": "gpt",
"models": {
...

eagent --model gpt로 프로필을 선택하거나, REPL 내부에서 /model gpt를 사용합니다.

/config list, /model list, 또는 /doctor를 실행하여 실제 설정 상태를 검사합니다. 자격 증명(Credential) 값은 항상 마스킹 처리됩니다.

macOS 및 Linux에서, ~/.easy-agent는 모드 0700으로 생성되며 민감한 파일은 0600입니다. 이 npm 패키지를 제거해도 이 디렉토리는 유지되므로, 모든 데이터를 삭제하려면 직접 삭제해야 합니다.

eagent # interactive REPL
eagent --model gpt # 모델 프로필 선택
eagent --plan # 읽기 전용 계획 모드
...

구조화된 JSON 및 NDJSON 메시지는 버전이 지정된 헤드리스 출력 스키마를 따릅니다. 알 수 없는 비용은 측정된 0이 아닌 null로 보고됩니다.

모든 시작 옵션에 대해서는 eagent --help를 실행하세요. 유용한 REPL 명령어에는 다음이 포함됩니다:

전역 패키지를 업그레이드하거나 설치 프로그램을 다시 실행합니다:

npm install -g --ignore-scripts eagent@latest

제거하려면 다음을 사용합니다:

npm uninstall -g eagent

npm 패키지를 제거하더라도 ~/.easy-agent/ 아래의 사용자 설정 및 세션은 의도적으로 보존됩니다.

• 실행하여 버전을 확인합니다:
  eagent --version
• Node.js를 확인하려면 다음을 사용합니다:
  node --version
• Easy Agent 내부에서 /doctor를 실행하여 자격 증명, 설정, MCP, 플러그인, 샌드박스 지원 및 쓰기 가능한 경로를 검사합니다.
• 활성 모델과 구성 소스를 확인하려면 /status와 /config list를 실행합니다.
• 전역 설치가 성공했으나 eagent가 발견되지 않으면, npm prefix -g에 연결된 npm 전역 bin 디렉터리를 PATH에 추가한 후 새 셸을 엽니다.
• 재현 가능한 문제는 GitHub Issues를 통해 보고합니다.

이슈에는 API 키, .env 내용 또는 개인 프롬프트를 절대 포함하지 마십시오.

Easy Agent는 다섯 가지 런타임 레이어를 분리하여 유지합니다:

Terminal UI
↓
QueryEngine (multi-turn orchestration)
...

npm 패키지는 소스 맵(경로만, 임베디드 소스 없음)이 포함된 단일 읽기 가능한 ESM 번들을 배포하므로, 버그 보고서의 스택 트레이스는 실제 소스 라인을 가리킵니다. 번들링된 타사 코드의 라이선스는 dist/THIRD_PARTY_LICENSES.txt에 있습니다.

버전 고정된 @anthropic-ai/sandbox-runtime 의존성은 프로세스 격리를 위한 플랫폼 헬퍼를 제공합니다.

git clone https://github.com/ConardLi/easy-agent.git
cd easy-agent
npm install
...

npm run verify:production은 오프라인 풀 리퀘스트 게이트이며, npm run verify:release는 전체 릴리스 게이트입니다. 자세한 내용은 Testing and Releasing을 참고하세요.

에이전트가 단계별로 어떻게 구축되었는지 학습하고 싶다면, learning path에서 개발 마일스톤과 해당 코드 스냅샷 목록을 확인할 수 있습니다.

프로젝트는 여전히 빠르게 발전하고 있으며 외부 풀 리퀘스트를 받지 않고 있습니다. 명확한 재현 단계를 갖춘 이슈 제기는 환영합니다.

MIT. 번들된 서드파티 패키지는 자체 라이선스를 유지합니다. 설치된 패키지의 dist/THIRD_PARTY_LICENSES.txt를 참고하세요.