@vietor/easy-agent 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vietor Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# Easy Agent
+
+![](https://img.shields.io/badge/Node.js-22%2B-brightgreen?style=flat-square) [![npm]](https://www.npmjs.com/package/@vietor/easy-agent)
+
+[npm]: https://img.shields.io/npm/v/@vietor/easy-agent.svg?style=flat-square
+
+An autonomous coding agent in the terminal.
+
+## Requirements
+
+- Node.js ≥ 22
+
+## Install
+
+Install globally with npm:
+
+```bash
+npm install -g @vietor/easy-agent
+```
+
+Or run it once without installing:
+
+```bash
+npx @vietor/easy-agent
+```
+
+## Configuration
+
+Create `~/.easy-agent.json` in your home directory:
+
+```json
+{
+  "llm": {
+    "baseUrl": "https://api.example.com/v1",
+    "apiKey": "your-api-key",
+    "model": "your-model"
+  }
+}
+```
+
+`llm.baseUrl`, `llm.apiKey`, and `llm.model` are all required. Point `baseUrl` at any OpenAI-compatible endpoint (OpenAI, Azure OpenAI, local servers, etc.) and set `model` to a model that endpoint serves.
+
+### Optional: MCP servers
+
+Add an `mcpServers` map to expose external tools through the Model Context Protocol. Each entry spawns a local process (stdio transport):
+
+```json
+{
+  "llm": { ... },
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--auto-connect",
+        "--accept-insecure-certs"
+      ]
+    }
+  }
+}
+```
+
+Only `command` is required; `args` and `env` are optional. MCP tools become available to the agent as `MCP__<server>__<tool>`. If a server fails to connect within 30s, it is disabled and the error is shown in the TUI — the rest keep running.
+
+### Optional: Agent instructions
+
+Easy Agent reads instructions files and appends them to the system prompt, so you can set persistent rules, conventions, or preferences. It looks in two places:
+
+1. **Global** — your home directory, applied to every session. Checks `~/.agents/AGENTS.md` first, then `~/.claude/CLAUDE.md`; uses the first one found.
+2. **Project** — your current working directory, applied per-project. Checks `./AGENTS.md` first, then `./CLAUDE.md`; uses the first one found.
+
+Both global and project files are loaded and concatenated into the system prompt if they exist.
+
+### Optional: Skills
+
+Skills are reusable prompts that register themselves as slash commands. Create a subdirectory for each skill under `~/.agents/skills/` (or `~/.claude/skills/`) with a `SKILL.md` file:
+
+```
+~/.claude/skills/
+  deploy/
+    SKILL.md
+  review/
+    SKILL.md
+```
+
+A `SKILL.md` with YAML frontmatter:
+
+```markdown
+---
+name: deploy
+description: Deploy the app to production
+---
+
+Run the deployment: build the project, then run `deploy.sh` with the `--prod` flag.
+```
+
+Only `name` is required; if omitted the directory name is used. The body is the full prompt injected when the skill is invoked. Skills appear as `/`-prefixed commands in the TUI alongside built-in slash commands.
+
+## Usage
+
+Launch the TUI:
+
+```bash
+easy-agent
+```
+
+Type a prompt and press Enter. The agent streams its reply and calls tools as needed, showing each tool call and a one-line preview of its result. It iterates until the task is done (capped at 25 tool rounds per turn).
+
+Built-in tools:
+
+- **Shell** — run shell commands using this platform's native syntax.
+- **FileRead** — read a file's full contents.
+- **FileWrite** — create or fully overwrite a file.
+- **FileEdit** — replace one exact, unique match within a file.
+- **Glob** — list files, optionally filtered by a glob pattern.
+- **Grep** — search file contents by regex.
+- **WebFetch** — fetch a URL as markdown or text.
+
+Slash commands:
+
+- `/mcp` — list linked MCP servers, their status, and exposed tools.
+- `/clear` — reset the conversation.
+- `/compact` — compress the conversation into a summary to free context.
+- `/export` — save the current session to `session-{timestamp}.jsonl`.
+- `/quit` or `/exit` — leave the app.

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "./main.js";
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/cmds/builtin.js

@@ -0,0 +1,68 @@
+import { writeFileSync } from "node:fs";
+export const exitCommand = {
+    name: "exit",
+    description: "Exit the session",
+    async execute(_ctx, host) {
+        host.exit();
+    },
+};
+export const clearCommand = {
+    name: "clear",
+    description: "Clear the conversation and log",
+    async execute(ctx, host) {
+        ctx.agent.clear();
+        host.clearLog();
+    },
+};
+export const mcpCommand = {
+    name: "mcp",
+    description: "List linked MCP servers",
+    async execute(ctx, host) {
+        const servers = ctx.mcp.list();
+        const text = servers.length
+            ? [
+                "MCP servers:",
+                ...servers.map((s) => `❯ ${s.name} ⋅ ${s.status} ∶ ${s.tools.join(", ") || "(no tools)"}`),
+            ].join("\n")
+            : "No MCP servers linked.";
+        host.info(text);
+    },
+};
+export const compactCommand = {
+    name: "compact",
+    description: "Compact the agent context",
+    async execute(ctx, host) {
+        host.thinking(true);
+        try {
+            await ctx.agent.compact();
+            host.info("context compacted");
+        }
+        catch (e) {
+            host.error(e.message);
+        }
+        finally {
+            host.thinking(false);
+        }
+    },
+};
+export const exportCommand = {
+    name: "export",
+    description: "Export the session to a JSONL file",
+    async execute(ctx, host) {
+        try {
+            const d = new Date();
+            const pad = (n) => String(n).padStart(2, "0");
+            const ts = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+            const file = `session-${ts}.jsonl`;
+            const lines = ctx.agent
+                .export()
+                .map((m) => JSON.stringify(m))
+                .join("\n");
+            writeFileSync(file, lines + "\n", "utf-8");
+            host.info(`exported to ${file}`);
+        }
+        catch (e) {
+            host.error(e.message);
+        }
+    },
+};

package/dist/cmds/registry.js

@@ -0,0 +1,27 @@
+import { exitCommand, clearCommand, mcpCommand, compactCommand, exportCommand } from "./builtin.js";
+export class CommandRegistry {
+    commands = new Map();
+    register(command) {
+        this.commands.set(command.name, command);
+    }
+    schemas() {
+        return [...this.commands.values()].map((t) => ({
+            name: t.name,
+            description: t.description,
+        }));
+    }
+    async execute(command, ctx, host) {
+        const cmd = this.commands.get(command);
+        if (!cmd) {
+            host.error(`unknown command: /${command}`);
+            return;
+        }
+        await cmd.execute(ctx, host);
+    }
+}
+export function registerBuiltinCommands(commands) {
+    commands.register(exitCommand);
+    commands.register({ ...exitCommand, name: "quit" });
+    for (const t of [clearCommand, mcpCommand, compactCommand, exportCommand])
+        commands.register(t);
+}

package/dist/cmds/types.js

@@ -0,0 +1 @@
+export {};

package/dist/config.js

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+const CONFIG_FILE = ".easy-agent.json";
+const LLMConfig = z.object({
+    baseUrl: z.string(),
+    apiKey: z.string(),
+    model: z.string(),
+});
+const MCPServerConfig = z.object({
+    command: z.string(),
+    args: z.array(z.string()).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+});
+const Config = z.object({
+    llm: LLMConfig,
+    mcpServers: z.record(z.string(), MCPServerConfig).optional(),
+});
+export function loadConfig() {
+    const path = join(homedir(), CONFIG_FILE);
+    const raw = JSON.parse(readFileSync(path, "utf-8"));
+    const result = Config.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("\n  ");
+        throw new Error(`Invalid config ~/${CONFIG_FILE}:\n  ${issues}`);
+    }
+    return result.data;
+}

package/dist/core/agent.js

@@ -0,0 +1,116 @@
+import { withAbort } from "../util/async.js";
+const STALL_THRESHOLD = 3;
+const COMPACT_PROMPT = "Summarize this conversation into a concise context summary. Preserve the user's goal, decisions made, files touched, and current progress. Write the summary in the same language the user used in the conversation. Begin your reply with \"Summary of conversation so far:\".";
+export class Agent {
+    llm;
+    session;
+    tools;
+    constructor(llm, session, tools) {
+        this.llm = llm;
+        this.session = session;
+        this.tools = tools;
+    }
+    get contextTokens() {
+        return this.session.getEstimatedTokens();
+    }
+    clear() {
+        this.session.clear();
+    }
+    export() {
+        return this.session.export();
+    }
+    async compact() {
+        const history = this.session.toLLM().slice(1);
+        if (history.length === 0)
+            return;
+        const request = [
+            ...history,
+            { role: "user", content: COMPACT_PROMPT },
+        ];
+        const msg = await this.llm.chat(request, []);
+        this.session.compact(msg.content || "");
+    }
+    async run(userInput, onEvent, signal) {
+        this.session.createCheckpoint();
+        try {
+            this.session.add({ role: "user", content: userInput });
+            await this.loop(onEvent, signal);
+        }
+        finally {
+            this.session.removeCheckpoint();
+        }
+    }
+    async runSkill(skill, onEvent, signal) {
+        this.session.createCheckpoint();
+        try {
+            this.session.add({ role: "skill", name: skill.name, content: skill.prompt });
+            await this.loop(onEvent, signal);
+        }
+        finally {
+            this.session.removeCheckpoint();
+        }
+    }
+    async loop(onEvent, signal) {
+        await withAbort(async (aborted) => {
+            let lastSig = "";
+            let stall = 0;
+            while (true) {
+                let msg;
+                try {
+                    msg = await this.llm.chat(this.session.toLLM(), this.tools.schemas(), (text) => onEvent?.({ type: "delta", text }), (attempt, max) => onEvent?.({ type: "retry", attempt, max }), (promptTokens, completionTokens) => onEvent?.({ type: "usage", promptTokens, completionTokens }), signal);
+                }
+                catch (e) {
+                    if (aborted())
+                        return;
+                    onEvent?.({ type: "error", text: e.message });
+                    return;
+                }
+                this.session.add(msg);
+                if (!msg.tool_calls?.length)
+                    return;
+                if (aborted())
+                    return;
+                const sig = msg.tool_calls
+                    .map((c) => `${c.function.name}:${c.function.arguments}`)
+                    .join("|");
+                stall = sig === lastSig ? stall + 1 : 1;
+                lastSig = sig;
+                if (stall >= STALL_THRESHOLD) {
+                    onEvent?.({ type: "error", text: "agent stalled: repeated identical tool calls" });
+                    return;
+                }
+                await Promise.all(msg.tool_calls.map(async (call) => {
+                    let args = {};
+                    let argsError = "";
+                    if (call.function.arguments) {
+                        try {
+                            args = JSON.parse(call.function.arguments);
+                        }
+                        catch (e) {
+                            argsError = `Error: invalid arguments: ${e.message}`;
+                        }
+                    }
+                    const summary = this.tools.summarize(call.function.name, args);
+                    onEvent?.({ type: "tool_start", id: call.id, name: call.function.name, summary });
+                    if (aborted())
+                        return;
+                    const result = argsError
+                        ? { content: argsError, isError: true }
+                        : await this.tools.execute(call.function.name, args);
+                    if (aborted())
+                        return;
+                    onEvent?.({ type: "tool_end", id: call.id, name: call.function.name, result: result.content, isError: result.isError });
+                    this.session.add({ role: "tool", tool_call_id: call.id, content: result.content });
+                }));
+                if (aborted())
+                    return;
+            }
+        }, {
+            signal,
+            onAbort: () => {
+                this.session.restoreCheckpoint();
+                onEvent?.({ type: "interrupted" });
+            },
+        });
+    }
+}

package/dist/core/session.js

@@ -0,0 +1,75 @@
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    const cjk = (text.match(/[一-龥぀-ヿ가-힯]/g) || []).length;
+    const words = (text.match(/[a-zA-Z0-9']+/g) || []).length;
+    return Math.ceil(cjk * 1.6 + words * 1.3 + (text.length - cjk) * 0.3);
+}
+function messageText(msg) {
+    const parts = [];
+    if (typeof msg.content === "string")
+        parts.push(msg.content);
+    else if (Array.isArray(msg.content)) {
+        for (const p of msg.content) {
+            if (p.type === "text")
+                parts.push(p.text);
+        }
+    }
+    if ("tool_calls" in msg && msg.tool_calls) {
+        for (const tc of msg.tool_calls) {
+            if (tc.function?.name)
+                parts.push(tc.function.name);
+            if (tc.function?.arguments)
+                parts.push(tc.function.arguments);
+        }
+    }
+    return parts.join(" ");
+}
+export class Session {
+    system;
+    messages = [];
+    estimatedTokens = 0;
+    checkpoint;
+    checkpointTokens = 0;
+    constructor(system) {
+        this.system = system;
+        this.messages.push({ role: "system", content: system });
+        this.estimatedTokens = estimateTokens(system);
+    }
+    getEstimatedTokens() {
+        return this.estimatedTokens;
+    }
+    add(msg) {
+        this.messages.push(msg);
+        this.estimatedTokens += estimateTokens(messageText(msg));
+    }
+    toLLM() {
+        return this.messages.map((m) => (m.role === "skill" ? { role: "user", name: m.name, content: m.content } : m));
+    }
+    export() {
+        return this.messages.slice(1);
+    }
+    clear() {
+        this.messages = [{ role: "system", content: this.system }];
+        this.estimatedTokens = estimateTokens(this.system);
+    }
+    compact(summary) {
+        this.messages = [
+            { role: "system", content: this.system },
+            { role: "assistant", content: summary },
+        ];
+        this.estimatedTokens = estimateTokens(this.system) + estimateTokens(summary);
+    }
+    createCheckpoint() {
+        this.checkpoint = this.messages.slice();
+        this.checkpointTokens = this.estimatedTokens;
+    }
+    restoreCheckpoint() {
+        this.messages = this.checkpoint.slice();
+        this.estimatedTokens = this.checkpointTokens;
+    }
+    removeCheckpoint() {
+        this.checkpoint = undefined;
+        this.checkpointTokens = 0;
+    }
+}

package/dist/llm/client.js

@@ -0,0 +1,74 @@
+import OpenAI, { APIConnectionError } from "openai";
+import { withRetry } from "../util/async.js";
+const MAX_RETRIES = 3;
+export class LLMClient {
+    client;
+    model;
+    constructor(config) {
+        this.client = new OpenAI({
+            apiKey: config.apiKey,
+            baseURL: config.baseUrl || undefined,
+            maxRetries: 0,
+        });
+        this.model = config.model;
+    }
+    async chat(messages, tools, onDelta, onRetry, onUsage, signal) {
+        return withRetry(() => this.streamOnce(messages, tools, onDelta, onUsage, signal), {
+            retries: MAX_RETRIES,
+            retryable: (e) => e instanceof APIConnectionError,
+            backoff: (attempt) => 1000 * 2 ** attempt,
+            onRetry,
+            signal,
+        });
+    }
+    async streamOnce(messages, tools, onDelta, onUsage, signal) {
+        let content = "";
+        const calls = new Map();
+        const stream = await this.client.chat.completions.create({
+            model: this.model,
+            messages,
+            tools,
+            stream: true,
+            stream_options: { include_usage: true },
+        }, { signal });
+        for await (const chunk of stream) {
+            if (chunk.usage) {
+                onUsage?.(chunk.usage.prompt_tokens ?? 0, chunk.usage.completion_tokens ?? 0);
+            }
+            const delta = chunk.choices[0]?.delta;
+            if (!delta)
+                continue;
+            if (delta.content) {
+                content += delta.content;
+                onDelta?.(delta.content);
+            }
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    let acc = calls.get(tc.index);
+                    if (!acc) {
+                        acc = { id: tc.id ?? "", name: "", arguments: "" };
+                        calls.set(tc.index, acc);
+                    }
+                    if (tc.function?.name)
+                        acc.name += tc.function.name;
+                    if (tc.function?.arguments)
+                        acc.arguments += tc.function.arguments;
+                }
+            }
+        }
+        const message = {
+            role: "assistant",
+            content: content || null,
+        };
+        if (calls.size) {
+            message.tool_calls = [...calls.entries()]
+                .sort((a, b) => a[0] - b[0])
+                .map(([, acc]) => ({
+                id: acc.id,
+                type: "function",
+                function: { name: acc.name, arguments: acc.arguments },
+            }));
+        }
+        return message;
+    }
+}

package/dist/llm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/main.js

@@ -0,0 +1,61 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+import { LLMClient } from "./llm/client.js";
+import { Session } from "./core/session.js";
+import { Agent } from "./core/agent.js";
+import { ToolRegistry, registerBuiltinTools } from "./tools/registry.js";
+import { CommandRegistry, registerBuiltinCommands } from "./cmds/registry.js";
+import { tryLoadSkills } from "./skills/loader.js";
+import { tryReadFileText, readFirstFileContent } from "./util/fs.js";
+import { MCPServers } from "./mcp/server.js";
+import { startApp } from "./tui/App.js";
+const SYSTEM_PROMPT_BASE = `You are Easy Agent, an autonomous coding assistant running in the terminal. You complete tasks by calling tools, inspecting their results, and iterating until the work is done.
+
+Environment:
+- Platform: ${process.platform}
+- Working directory: ${process.cwd()}
+
+Tool use:
+- Prefer dedicated tools (FileRead, FileEdit, Glob, Grep) over the Shell tool when they fit the task.
+- Read a file before editing it; make minimal, surgical changes that match the surrounding code style.
+- Reference code as file_path:line_number.
+
+Output:
+- Be concise and use GitHub-flavored markdown.
+- State what you did and stop once the task is complete. Report outcomes faithfully, and do not narrate alternatives you will not pursue.`;
+export async function main() {
+    const config = loadConfig();
+    const llm = new LLMClient(config.llm);
+    const tools = new ToolRegistry();
+    registerBuiltinTools(tools);
+    const commands = new CommandRegistry();
+    registerBuiltinCommands(commands);
+    const mcp = new MCPServers();
+    mcp
+        .connect(config.mcpServers)
+        .then((list) => {
+        for (const t of list)
+            tools.register(t);
+    })
+        .catch((e) => mcp.report(`MCP connect failed: ${e.message}`));
+    const globalSkills = readFirstFileContent([join(homedir(), ".agents", "skills"), join(homedir(), ".claude", "skills")], tryLoadSkills);
+    if (globalSkills) {
+        globalSkills.forEach((skill) => commands.register({
+            name: skill.name,
+            description: skill.description ?? skill.name,
+            execute: async (_, host) => {
+                await host.runSkill(skill);
+            },
+        }));
+    }
+    const globalPrompt = readFirstFileContent([join(homedir(), ".agents", "AGENTS.md"), join(homedir(), ".claude", "CLAUDE.md")], tryReadFileText);
+    const projectPrompt = readFirstFileContent([join(process.cwd(), "AGENTS.md"), join(process.cwd(), "CLAUDE.md")], tryReadFileText);
+    const systemPrompt = [SYSTEM_PROMPT_BASE, globalPrompt, projectPrompt]
+        .filter(Boolean)
+        .join("\n\n=================\n\n");
+    const session = new Session(systemPrompt);
+    const agent = new Agent(llm, session, tools);
+    const app = startApp(agent, commands, mcp);
+    await app.waitUntilExit().finally(() => mcp.kill());
+}

package/dist/mcp/client.js

@@ -0,0 +1,45 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { getPackageInfo } from "../util/package.js";
+function getClientINfo() {
+    const pkginfo = getPackageInfo();
+    return { name: pkginfo.name, version: pkginfo.version };
+}
+export class MCPClient {
+    name;
+    client = new Client(getClientINfo(), { capabilities: {} });
+    transport;
+    connectReject;
+    constructor(name, config) {
+        this.name = name;
+        this.transport = new StdioClientTransport({ ...config, stderr: "ignore" });
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            this.connectReject = reject;
+            this.client
+                .connect(this.transport)
+                .then(resolve, reject)
+                .finally(() => {
+                this.connectReject = undefined;
+            });
+        });
+    }
+    async listTools() {
+        return this.client.listTools().then((r) => r.tools);
+    }
+    async callTool(name, args) {
+        return this.client.callTool({ name, arguments: args });
+    }
+    kill() {
+        this.connectReject?.(new Error("aborted"));
+        this.connectReject = undefined;
+        const pid = this.transport.pid;
+        if (pid) {
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch { }
+        }
+    }
+}