@eliware/agentx-cli

agentx is a lightweight terminal chat agent built on the OpenAI Responses API over WebSocket transport. Install the published package globally, run agentx-setup once, and then start agentx.

It is designed to feel shell-like:

• waits for your first message before calling OpenAI
• supports internal cd, clear, /clear, /usage, /rollback, /setup, quit, and exit
• supports direct shell commands with a leading !
• supports tab completion for local files and folders, including after changing directories
• remembers interactive session state in .agentx_responseid and successful checkpoints in .agentx_checkpoint
• can prompt to resume interrupted tool execution on startup
• includes quick CLI flags for help, version, and debug logging
• handles temporary WebSocket connectivity failures and shuts down connections gracefully
• prints active model and runtime settings at startup
• prints friendly startup errors for missing config or API keys
• supports optional MCP tools configured in ~/.agentx.mcp.json

Usage

npm -g install @eliware/agentx-cli@latest
agentx-setup
agentx

For a single request, run:

agentx "summarize this project"

One-shot mode prints the response and usage summary, then exits. Tool execution is approved by default; use --confirm to enable confirmation prompts.

If you are working from the repository itself, run node agentx.mjs.

Quick flags:

• agentx --help, agentx -h, or agentx -? prints quick help
• agentx --version or agentx -v prints the package version
• agentx --debug prints raw websocket logs and suppresses live status lines
• agentx --confirm enables confirmation prompts; approval is the default
• agentx "message" sends one request, performs tool calls, prints the response and usage summary, then exits

Behavior

• Type a normal message to send it to OpenAI.
• Type cd /path/to/dir to change the local working directory without calling OpenAI.
• Type !ls to run a local shell command directly; its output is buffered for the next AI request.
  • clear: resets the session state and starts a fresh conversation.
  • /clear: also resets the session state and restarts the conversation.
  • !clear: runs the local shell clear command, clearing only the terminal display.
• Type /usage to view token and cost totals.
• Type /rollback to restore a successful response checkpoint.
• Recoverable API failures keep the REPL alive and offer retry, new-chain, rollback, or clear options.
• Successful turns update .agentx_checkpoint; one-shot invocations branch from that checkpoint and use isolated pending state, so multiple one-shots can run in the same folder without sharing interrupted tool calls.
• Type /setup to edit the API key, model, reasoning, output, and compaction settings, then reload them without ending the session; setup errors return to the REPL.
• Type quit, exit, /quit, or /exit to leave the app.

Docs

User-facing docs live in docs/:

• Quickstart
• Command reference
• Session state
• Examples
• Troubleshooting
• AGENTS.md behavior

Development

• Main entrypoint: agentx.mjs
• Setup entrypoint: agentx-setup.mjs
• Official behavior specifications: specs/
• Implementation modules: src/

This project uses Spec Driven Development. Update the relevant spec first, then tests, then implementation. Tests are secondary to the specs, and implementation is third. Maintain 100% test coverage across all files and always fix lint warnings.

Run lint and tests with:

npm run lint
npm test

Environment

Set your OpenAI key in the shell environment, or let agentx-setup write it to ~/.agentx:

export agentx_api_key="your-key-here"
# or: export AGENTX_API_KEY="your-key-here"

The launchers load ~/.agentx when present.

MCP tools

AgentX automatically loads an optional .agentx.mcp.json from your home directory and merges its MCP tool definitions into the request. Start with .agentx.mcp.json.example, then copy it to ~/.agentx.mcp.json and add your server configuration. The example file is ignored by Git when copied or customized locally. MCP calls and streamed arguments are displayed in cyan.

License

MIT © 2025 Eli Sterling, eliware.org

Install, update, and uninstall

Install or update the latest release with:

npm -g install @eliware/agentx-cli@latest

Remove AgentX and its local configuration with:

npm -g uninstall @eliware/agentx-cli
rm -f $HOME/.agentx*

See AGENTS.md behavior for discovery, inheritance, prompt-cost implications, and maintenance guidance.

Parallel workers

AgentX exposes asynchronous worker tools:

• spawn_agent: starts 1-10 independent AgentX workers and returns IDs immediately.
• agent_status: reports status, elapsed time, line count, partial output, and usage. Use wait and optional timeout_ms to block until completion or return partial progress.

Workers use --yolo, have independent conversations, and share the parent working directory. Use workspace files for intentional coordination; avoid simultaneous edits to the same file.