@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, /setup, quit, and exit
• supports direct shell commands with a leading >
• supports tab completion for local files and folders
• remembers session state in .agentx_responseid
• can prompt to resume interrupted tool execution on startup
• includes quick CLI flags for help, version, and debug logging
• 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

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

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.
• Type clear to reset the saved session.
• Type >clear to clear the terminal display through the local shell.
• Type /clear to clear the saved session id.
• Type /usage to view token and cost totals.
• Type /setup to edit the API key, model, reasoning, output, and compaction settings, then reload them without ending the session.
• 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
• Implementation modules: src/

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.