YamX - YamX ~ A terminal-first AI agent that runs, fixes,

项目说明

YamX

YamX (yamx) is a terminal coding agent. It starts with no model, runs local commands immediately, and when a model is connected it writes code, edits files, debugs failures, and applies fixes from a local picture of the project.

1.0.30. Node.js 18+.

The prompt is >. A pixel YamX mark plays on startup, then a card shows the folder, local · offline (or the connected model), the session, and the .

Start

From this repository:

npm run dev starts without a separate build. npm link puts yamx on your PATH.

YamX opens even when no API key is set. The card reads local · offline. Shell lines such as git status run on this machine. On Windows, ip runs as ipconfig and ps runs as tasklist. Dangerous commands still ask before they run.

Connect a model with /connect or yamx --onboard. Enter the base URL, API key, and any model name for an OpenAI-compatible chat endpoint (usually a URL ending in /v1).

YamX stores those fields, plus optional extra headers, as pro.custom in ~/.yamx/config.json. Leave the API key blank later to keep the saved key.

Coding architecture

A write, fix, or debug turn reads the project from disk first. That brief is what the model and its sub-agents use. Greetings and bare shell lines do not take this path.

The brief always includes the absolute project path, working directory, OS, shell, package manager, the test / lint / build scripts that exist, git branch and dirty state, entry files, and any files named in the error you pasted.

If no model is connected, YamX saves the brief and asks you to /connect. The next coding turn sends that brief with the request. The model does not invent paths or commands that are not in the brief or a tool result.

Sub-agents:

| Role | What it does |
| --- | --- |
| explorer | Read, grep, and map the repo. Runs in parallel with other explorers and the re. |
| implementer | Reads, then edits with edit_file, multi_edit, patch_file, or write_file. |
| debugger | Reproduces the failure, edits, then reruns the same command. |
| re | Reads git status and git diff. Does not edit. |

Only one writer runs at a time, and it locks the paths it names. Each child returns a short report (files changed, commands, first error, whether passed). The parent does not redo those edits. /explore, /plan, /review, and /agent use the same runner.

After a real file edit, the same test or build command is allowed to run again. An unchanged rerun is skipped.

settings.subagents.maxParallel defaults to 3. settings.subagents.maxIterations defaults to 12.

Two binaries

| Binary | What it is |
| --- | --- |
| yamx | The coding REPL. Sessions, 33 tools, project brief, sub-agents, and any connected model. |
| ymax | The offline router. One local expert handles a command. No API key. |

In-session commands

| Command | |
| --- | --- |
| /help | List commands |
| /connect | Set base URL, API key, and model name |
| /model | Provider and model in use |
| /explore /plan /review | Read-only sub-agents |
| /agent <name> <task> | Run a built-in or custom sub-agent |
| /agents | List sub-agents |
| /scan [quick\|deep] | Offline project scan to .yamx/project-summary.md |
| /tools | List tools |
| /diff /status | Git diff and session snapshot |
| /undo | Revert the last file edits from this turn |
| /stop | Stop the current turn |
| /exit | Save and quit |

Custom sub-agents are markdown files in .yamx/agents/ or ~/.yamx/agents/.

Built-in tools (33)

Destructi and deletes still ask for approval.

Connect

/connect, yamx --onboard, and the web Settings → Model page use the same fields: base URL, API key, model name, and optional extra headers. They are stored as pro.custom.

En o: YAMX_CUSTOM_BASE_URL, YAMX_CUSTOM_API_KEY, YAMX_CUSTOM_MODEL.

A sa, OpenAI, or other named provider in an older config does not start. With no base URL, YamX stays offline.

Configuration

~/.yamx/config.json holds pro and settings. Sessions live in ~/.yamx/sessions/. Project memory lives in .yamx/.

Settings that matter for coding:

Remo data:

Web UI

The ser to loopback. --allow-dangerous permits risky commands from the browser. The page can chat, switch sessions, and set a model under Settings, Model.

Useful routes: GET /api/state, GET /api/sessions, POST /api/chat, POST /api/command, GET /api/tools.

CLI reference

Subcommands: yamx config, yamx web.

Develop

On Windows, npm.cmd is the script runner if PowerShell blocks npm.

Troubleshooting

yamx is not on PATH: the npm global bin directory must be on PATH. Open a new terminal after install.

No model yet: that is the normal start. Use /connect. Coding asks wait there until a model is connected. Shell lines still run.

Curl setup rejected: the URL must be http or https and end in /v1 or /chat/completions.

A command was rewritten badly: short names and shell keywords are not typo-fixed (ip stays a network command, not if). /fix previews a correction. /translate shows the nati for this OS.

Build fails with EPERM on dist: another yamx or node dist/index.js still has those files open. Stop it, then build again.

License

ISC — Yamin

项目信息

开发语言：TypeScript

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕YamX ~ A terminal-first AI agent that runs, fixes, and automates coding, DevOps, networking, and defensive security tasks from the command line.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。