Easy Agent
An open-source, terminal-native project to fully recreate the Claude Code experience from the ground up.
Easy Agent is a long-horizon engineering project focused on rebuilding a complete local agentic coding system in TypeScript and Node.js. The goal is not to publish isolated demos, but to incrementally construct a production-style coding agent with a clean architecture, strong safety boundaries, multi-turn orchestration, local tool execution, and the extensibility required for a full Claude Code-class developer experience.
This repository is the open-source implementation track of that effort. Full documentation will be added over time. For now, this README focuses on the project itself: what it aims to become, how it is structured, and where implementation currently stands.
Chinese version: see README.zh-CN.md
Vision
Easy Agent aims to become a serious open-source recreation of a modern local coding agent system.
Core goals:
- Fully recreate the Claude Code-style workflow in an open-source codebase
- Keep the architecture layered, explicit, and extensible
- Prioritize real engineering systems over toy examples
- Evolve incrementally toward a complete local Agent CLI
- Preserve a stable path toward persistence, compaction, MCP, skills, sandboxing, sub-agents, multi-agent collaboration, and multi-provider support
Project Status
Current stage: foundational implementation in active development
The project already has meaningful groundwork across the CLI, streaming communication, tool execution, terminal UI, and session orchestration layers. At the same time, many advanced systems in the full recreation plan are still under active development.
Easy Agent should currently be understood as a serious open-source rebuild in progress rather than a finished end-user product.
Architecture
Easy Agent is being built around a five-layer architecture:
+---------------------------------------------------+ | 1. Interaction Layer | | Terminal UI, input handling, rendering | +---------------------------------------------------+ | 2. Orchestration Layer | | Multi-turn session flow, usage, commands | +---------------------------------------------------+ | 3. Core Agentic Loop | | Reason -> tool call -> observe -> continue | +---------------------------------------------------+ | 4. Tooling Layer | | File, shell, search, and local actions | +---------------------------------------------------+ | 5. Model Communication Layer | | Streaming API communication with LLMs | +---------------------------------------------------+
This separation makes the system easier to evolve:
- the communication layer handles model I/O
- the tool layer exposes actionable capabilities
- the agentic loop drives single-turn autonomous execution
- the orchestration layer manages multi-turn state and control flow
- the interaction layer turns the runtime into a usable terminal product
Repository Layout
easy-agent/ ├── src/ │ ├── entrypoint/ # CLI bootstrap │ ├── ui/ # React/Ink terminal interface │ ├── core/ # agentic loop and query orchestration │ ├── tools/ # local tools and tool registry │ ├── services/api/ # model client and streaming wrapper │ ├── permissions/ # permission and safety controls │ ├── context/ # system prompt and context management │ ├── session/ # session persistence and history │ ├── types/ # shared domain types │ └── utils/ # env, config, logging, helpers ├── package.json ├── tsconfig.json ├── README.md └── README.zh-CN.md
Roadmap and Progress
The project follows a 30-phase roadmap designed to recreate the full Claude Code-style system progressively.
| Phase | Area | Core Code | Status |
|---|---|---|---|
| 0 | Project scaffold | planned in step series | ✅ Done |
| 1 | LLM communication layer | step/step1.js | ✅ Done |
| 2 | React/Ink terminal UI | step/step2.js | ✅ Done |
| 3 | Tool interface and first tool | step/step3.js | ✅ Done |
| 4 | Core agentic loop | step/step4.js | ✅ Done |
| 5 | Complete core toolset | step/step5.js | ✅ Done |
| 6 | System prompt and context engineering | step/step6.js | ✅ Done |
| 7 | Permission control system | step/step7.js | ✅ Done |
| 8 | QueryEngine multi-turn orchestration | step/step8.js | ✅ Done |
| 9 | Session persistence and restore | step/step9.js | ✅ Done |
| 10 | Project memory system | step/step10.js | ✅ Done |
| 11 | Context compaction | step/step11.js | ✅ Done |
| 12 | Fine-grained token budget management | step/step12.js | ✅ Done |
| 13 | Plan mode | step/step13.js | ✅ Done |
| 14 | TodoWrite session task tracking | step/step14.js | ✅ Done |
| 15 | Task management system (V2) | step/step15.js | ✅ Done |
| 16 | MCP protocol support | step/step16.js | ✅ Done |
| 17 | Skills system | step/step17.js | ✅ Done |
| 18 | Sandbox | step/step18.js | ✅ Done |
| 19 | Sub-agents | planned | ⏳ Not started |
| 20 | Custom agent system | planned | ⏳ Not started |
| 21 | Multi-agent collaboration | planned | ⏳ Not started |
| 22 | Hooks lifecycle system | planned | ⏳ Not started |
| 23 | Terminal UI upgrades | planned in step series | 🚧 Partial |
| 24 | Configuration system improvements | planned in step series | 🚧 Partial |
| 25 | File history and rollback | planned | ⏳ Not started |
| 26 | Error handling and resilience | planned in step series | 🚧 Partial |
| 27 | Pipe mode / non-interactive execution | planned | ⏳ Not started |
| 28 | Auto mode | planned in step series | 🚧 Partial |
| 29 | Multi-provider support | planned in step series | ⏳ Not started |
| 30 | Packaging, publishing, and documentation | planned in step series | 🚧 Partial |
The easy-agent/step/ directory contains tutorial-friendly milestone code, so each completed chapter is directly learnable and reproducible from a focused single file.
What Easy Agent Is — and Is Not
Easy Agent is:
- an open-source recreation project
- a systems-engineering effort
- a long-term implementation of a local coding agent
- a public codebase evolving toward a full Claude Code-class CLI
Easy Agent is not:
- a one-file demo
- a prompt-only wrapper around an API
- a finished product today
- a public mirror of any private course material
Getting Started
Requirements
- Node.js
- npm
- Anthropic-compatible model access
Environment Variables
Easy Agent currently supports the following environment variables:
ANTHROPIC_MODEL— default model nameANTHROPIC_BASE_URL— custom API base URLANTHROPIC_AUTH_TOKEN— API authentication token
Install
npm install
Development
npm run dev
Build
npm run build npm start
Example CLI Options
agent --help agent --model claude-sonnet-4-20250514 agent --plan agent --auto agent --dump-system-prompt
Near-Term Priorities
The next major milestones are:
- a fuller plan-mode workflow
- task management system
- extensibility primitives beyond MCP and skills
- configuration improvements beyond the current sandbox and permission model
- sub-agent and multi-agent collaboration
- multi-provider architecture
Contribution Policy
Easy Agent is not accepting external contributions at this stage.
The project is still in active reconstruction, and the implementation, structure, and development conventions are expected to change frequently. External contributions will be opened after the project reaches a more stable and maintainable state.
Until then, you are welcome to follow the project and reference the public roadmap, but pull requests and outside code contributions are intentionally postponed for now.
License
MIT