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: Stage 22 — Hooks lifecycle system, next

The project has completed the tutorial-friendly implementation track through Stage 21, including the CLI, streaming communication, tool execution, terminal UI, session orchestration, context management, MCP, skills, sandboxing, sub-agents, background agent execution, git worktree isolation, and Agent Teams / multi-agent collaboration. Stage 22 is the next major planned area: lifecycle hooks.

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
│   ├── agents/          # sub-agent definitions, registry, and runners
│   ├── tools/           # local tools and tool registry
│   ├── services/        # model API, MCP, and skills services
│   ├── permissions/     # permission and safety controls
│   ├── context/         # system prompt and context management
│   ├── sandbox/         # Bash sandbox profiles and wrapping
│   ├── session/         # session persistence and history
│   ├── state/           # UI/runtime stores for tasks, todos, agents
│   ├── 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 31-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-Agent and agent definitions	step/step19.js	✅ Done
20	Background agents and worktree isolation	step/step20.js	✅ Done
21	Agent Teams / multi-agent collaboration	step/step21.js	✅ Done
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.

Current implementation notes:

• Stage 21 is complete in source and the step snapshot.
• Stage 22 Hooks remains planned and intentionally separate from Agent Teams.

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 name
• ANTHROPIC_BASE_URL — custom API base URL
• ANTHROPIC_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:

1. implement Stage 22 Hooks lifecycle system
2. write the Stage 22 tutorial article and step/step22.js
3. continue terminal UI and configuration improvements
4. move toward pipe mode, Auto Mode, and 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