Easy Agent

A terminal coding agent that reads your code, edits files, and runs commands under permission rules you control.

Easy Agent (eagent) runs in your terminal next to your repository. Describe a task and it plans the work, reads and changes files, runs tests or shell commands, and reports back. Every action that can change your machine goes through permission rules, workspace trust, and an optional OS-level sandbox. It works with Anthropic, OpenAI-compatible, Gemini, and local models.

The code is written to be read as well as run. Model communication, the agentic loop, tools, permissions, context management, and each extension system live in separate layers. The documents linked below explain how the security-relevant parts behave and why, and the learning path walks through the layers in order with code snapshots, which helps if you want to build or customize an agent of your own.

中文文档：README.zh-CN.md

What you can use it for

• Find your way around an unfamiliar codebase: ask where something is handled, how a flow works, or what a change would touch.
• Make multi-file changes, review the diff, and undo them with /rewind if they are wrong.
• Run builds and tests, read the failures, and iterate on a fix.
• Plan a change first in read-only Plan Mode, then carry it out.
• Script it: pipe input into eagent -p and read text, JSON, or NDJSON output in CI or shell scripts.
• Connect your own tools through MCP servers, skills, custom agents, hooks, and plugins.

Install

Requirements: Node.js 22 or newer, npm, and credentials for at least one supported model provider.

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

Or try it without installing:

npx --yes eagent@latest

On macOS and Linux an installer is also available. It checks Node.js, installs the same npm package with --ignore-scripts, and verifies that eagent is on PATH. It does not install Node.js or run package lifecycle scripts.

curl -fsSL https://raw.githubusercontent.com/ConardLi/easy-agent/main/install.sh | sh

The package installs two commands, eagent and the long alias easy-agent.

Quick start

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

On first use in a folder, Easy Agent asks whether you trust it. Then type a request, for example explain how requests are authenticated in this repo. Type /help for commands; press Ctrl+D to exit.

Core capabilities

• File and code tools: Read, Write, Edit, MultiEdit, Glob, Grep, Bash, and PowerShell on Windows
• Web and external tools: WebFetch, WebSearch, MCP tools and resources
• Safe execution: allow/ask/deny rules, Plan Mode, Auto Mode, workspace trust, hooks, controlled subprocesses, private local data, and fail-closed shell sandboxing on macOS and Linux
• Long-running work: TodoWrite, persistent task graphs, sub-agents, background runs, Git worktree isolation, and Agent Teams
• Context and continuity: durable persistence, resume, compaction, token budgets, project memory (AGENTS.md / AGENT.md), file checkpoints, and rewind
• Extensibility: skills, custom agents, slash commands, output styles, hooks, MCP servers, plugins, and static marketplaces
• Interfaces: interactive terminal UI, headless text/JSON/NDJSON output, an embeddable session SDK (eagent/sdk), images and screenshots, and multiple model protocols

Supported platforms

• Node.js 22 or newer is required on every platform. Older versions exit with an explanatory message.
• The install.sh installer supports macOS and Linux. On Windows, install with npm.
• On Windows, local data relies on the user profile's ACLs instead of POSIX 0600/0700 modes. /doctor reports this.
• Clipboard image paste needs pngpaste or osascript on macOS and xclip or xsel on Linux.

See Sandbox security for per-platform setup, including the Ubuntu AppArmor restriction on user namespaces.

Security model

Easy Agent assumes the model can make mistakes and that a repository you open may be hostile. Several independent layers limit what a session can do:

• Permission rules. Tool calls that change files, run commands, or reach the network are checked against allow, ask, and deny rules. Deny rules always win. In the default mode anything not allowed is asked; Bash commands that are proven read-only can run without a prompt (analysis rules).
• Permission modes. default asks before risky actions. plan (--plan) allows only read-only tools. auto (--auto) lets a classifier approve safe calls, block risky ones, and fall back to a prompt when unsure. Headless runs (-p) deny calls that would prompt unless you pass --dangerously-skip-permissions; deny rules still apply.
• Workspace trust. Project settings, .env, project MCP servers, hooks, plugins, and model profiles are ignored until you trust the folder. Trust is stored in your home directory, so a repository cannot mark itself trusted, and project files cannot replace credentials inherited from your shell (details).
• Path boundaries. File tools resolve real paths and refuse to follow symbolic links out of the workspace and its allowed directories (details).
• Shell sandbox. When sandbox.enabled is set, Bash runs inside an OS sandbox with an allow-only write policy and proxy-filtered network. If the sandbox cannot start, the command is blocked rather than run unsandboxed (details).
• Local data. Sessions, settings, trust state, and logs are private to your account. Stream debug logging is off unless you enable it and redacts credentials when on (details).

Easy Agent sends no analytics or telemetry. Network requests go to the model provider you configure, to MCP servers and plugin sources you add, and to WebFetch/WebSearch targets when those tools are allowed. /doctor probes the configured provider endpoint for reachability.

Configuration

Settings are JSON files merged in this order, from lowest to highest priority:

1. User: ~/.easy-agent/settings.json
2. Project: <project>/.easy-agent/settings.json (shared, applied once the folder is trusted)
3. Local: <project>/.easy-agent/settings.local.json (personal, applied once the folder is trusted)
4. Command line: --settings <file>, --model, --permission-mode, and similar flags
5. Managed policy: /Library/Application Support/EasyAgent/managed-settings.json on macOS, /etc/easy-agent/managed-settings.json on Linux, %PROGRAMDATA%\EasyAgent\managed-settings.json on Windows

A project .env is applied after project and local settings, only for a trusted folder. Feature switches are described in Configuration and feature controls.

For a raw Anthropic model name, environment variables are enough:

export ANTHROPIC_AUTH_TOKEN="your-token"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514" # optional
eagent

Named Anthropic, OpenAI-compatible, Gemini, and local profiles go in settings.json:

{
  "defaultModel": "gpt",
  "models": {
    "gpt": {
      "protocol": "openai-chat",
      "model": "gpt-5.1",
      "baseURL": "https://api.openai.com/v1",
      "apiKey": "${OPENAI_API_KEY}"
    },
    "gemini": {
      "protocol": "gemini",
      "model": "gemini-2.5-pro",
      "apiKey": "${GEMINI_API_KEY}"
    },
    "ollama": {
      "protocol": "openai-chat",
      "model": "qwen2.5-coder",
      "baseURL": "http://localhost:11434/v1"
    }
  }
}

Select a profile with eagent --model gpt or /model gpt inside the REPL.

Run /config list, /model list, or /doctor to inspect the effective setup. Credential values are always redacted.

Where data is stored