ConardLi/easy-agent

Easy Agent – a secure, terminal‑based coding assistant

What it does

• Runs as a command‑line REPL (eagent) beside your code repository.
• You describe a task in natural language; the agent plans, reads, edits files, runs builds/tests, and reports results.
• Every potentially‑dangerous action (file writes, shell commands, network calls) is filtered through a permission system you configure, with optional OS‑level sandboxing.

Key features

Area	Highlights
Core tools	File read/write, multi‑file edits, glob/grep, Bash/PowerShell execution, web fetch/search, MCP‑based extensions.
Safety	Allow/ask/deny rule engine, workspace‑trust model, path‑boundary checks, read‑only Plan mode, classifier‑assisted Auto mode, sandbox (Seatbelt on macOS, bubblewrap on Linux).
Persistence	Session transcripts, file checkpoints (/rewind), project‑wide memory (AGENT.md/AGENTS.md), durable task graphs, resumable sessions.
Extensibility	Skills, custom agents, slash commands, plugins, MCP servers, static marketplace, SDK for embedding.
Interfaces	Interactive terminal UI, headless JSON/NDJSON output (-p), JSON‑RPC over stdio, Agent Client Protocol for IDEs, SDK (eagent/sdk).
Supported models	Anthropic, OpenAI‑compatible, Gemini, local Ollama‑style models; configurable via JSON profiles or env vars.
Platforms	macOS, Linux/WSL2 (sandboxed), Windows (PowerShell, no sandbox).

How you use it

1. Install globally with npm (npm i -g eagent) or run via npx.
2. Export a model token (e.g., ANTHROPIC_AUTH_TOKEN).
3. cd into a project and start eagent.
4. On first run you decide whether to trust the folder. Then type natural‑language requests, e.g. explain how requests are authenticated.
5. Use slash commands (/help, /rewind, /model, /permissions, etc.) to control the session, inspect state, or undo changes.

Security model

• Permission rules: allow, ask, deny – deny always wins. Unapproved actions trigger a prompt.
• Permission modes: default (ask), plan (read‑only), auto (classifier decides, prompts on uncertainty).
• Workspace trust: Trust decisions are stored in ~/.easy-agent/state.json; a repo cannot mark itself trusted.
• Path boundaries: Symlinks outside the workspace are rejected.
• Sandbox: Optional OS sandbox isolates Bash commands; if it fails to start the command is blocked.
• Local data: All session data lives under ~/.easy-agent with restrictive permissions (0700/0600).

Configuration

• Settings are layered JSON files (user → project → local → CLI → managed).
• Model profiles are defined in settings.json; select with eagent --model <name> or /model.
• Permissions, feature flags, and sandbox options are toggled via the same hierarchy.

Typical workflows

• Code exploration: Ask where a feature is implemented; the agent greps, opens files, and explains.
• Batch refactor: Prompt a multi‑file change, review the diff, and /rewind if needed.
• CI integration: Pipe prompts to eagent -p and consume JSON output in scripts.
• Custom tooling: Register your own skill or plugin, or connect an IDE via the ACP protocol.

Development & contribution

• Built in TypeScript, bundled as a single ESM package.
• Development workflow: npm run dev; CI runs verification scripts and extensive tests.
• Currently not accepting external PRs, but issues with reproducible bugs are welcome.

License: MIT (with third‑party licenses listed separately).

---

Easy Agent is a genuine open‑source project that provides a programmable, security‑focused AI coding assistant for developers working in the terminal.