Skip to content

quickstart.md

Latest commit

 

History

History
79 lines (53 loc) · 2.37 KB

quickstart.md

File metadata and controls

79 lines (53 loc) · 2.37 KB
Raw

Quickstart

AgentX is a terminal chat agent built on the OpenAI Responses API over WebSocket transport. For most users, the simplest path is: install it globally, run agentx-setup once, then start agentx.

Start the CLI

If you installed the package globally, use:

agentx

If you are working from the repository root, use:

node agentx.mjs

Optional: run the setup helper

agentx-setup

Use that to save your OpenAI API key and runtime settings in ~/.agentx.

Quick flags

  • agentx --help or agentx -h shows quick help
  • agentx --version or agentx -v prints the package version
  • agentx --debug prints raw websocket logs and suppresses live status lines
  • MCP calls and streamed arguments are shown in cyan when configured

Before you begin

Set your API key in the shell environment, or let agentx-setup write it into ~/.agentx for you:

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

AgentX prefers agentx_api_key and falls back to AGENTX_API_KEY. The launchers load ~/.agentx when present. Startup also displays the active model and runtime settings.

Optional MCP tools

To enable MCP tools, place an .agentx.mcp.json file in your home directory. Copy .agentx.mcp.json.example as a starting point and update its server URL and authorization. AgentX loads ~/.agentx.mcp.json automatically; a missing file is allowed, while invalid JSON prevents the prompt template from loading.

First run

  1. Start AgentX.
  2. Type a normal message and press Enter.
  3. AgentX sends that message to OpenAI.
  4. The response streams into the terminal as it is generated.

What to expect

  • The prompt shows your user, short hostname, current working directory, and a # marker.
  • AgentX waits for your first message before contacting OpenAI.
  • Tool calls may stream command arguments and shell summaries live.
  • If .agentx_responseid exists, the session resumes automatically. If it contains pending tool calls, AgentX asks how you want to continue.

Install or update

Install or update the latest release at any time with:

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

See AGENTS.md behavior for how project instructions are discovered and loaded.

Remove AgentX

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