AlphaAgent

A self-hosted, OpenClaw-style personal AI agent that runs in your terminal and in your browser. It talks to 8 AI providers, keeps persistent sessions you can switch on the fly, and comes with a built-in tool loop (shell, files, web) so the model can actually do things on your machine.

• Zero runtime dependencies (Node ≥ 18, built-in fetch)
• 8 providers: Claude, Gemini, OpenAI, OpenRouter, Qwen, Pollinations, OpenCode Zen, Blackbox
• Rich streaming REPL — spinner, markdown rendering, reasoning tokens, tool calls, multi-line input, tab completion, Ctrl-C to stop
• Embedded web UI (alphaa serve)
• Persistent, switchable sessions
• Tool loop with automatic fallback when a model rejects tools
• Python companion package (pip install alpha-agent-ai)

Install

npm

npm install -g alpha-agent-ai
alphaa --version

pip (Python companion)

pip install alpha-agent-ai

Quick start

alphaa configure        # interactive setup wizard
alphaa                  # start the REPL

The REPL renders markdown as the model streams, shows a spinner while "thinking…", prints reasoning tokens dimmed, and draws tool calls/result boxes. Press Ctrl-C once to stop a long response (the prompt comes right back), Ctrl-C while idle to quit. Start messages with / for commands:

alphaa ❯ /help
alphaa [main] openai/gpt-4o-mini ❯ /use research           # switch to another session
alphaa [main] openai/gpt-4o-mini ❯ /provider gemini        # switch providers on the fly
alphaa [main] openai/gpt-4o-mini ❯ /model gemini-2.5-flash
alphaa [main] openai/gpt-4o-mini ❯ /new                    # start a fresh session
alphaa [main] openai/gpt-4o-mini ❯ what's in this folder?  # the agent will use list_dir / shell tools

Multi-line input — end a line with \ (or leave an open ``` code fence) to keep typing on the next line; enter a blank line to send. Press Tab to complete /commands, provider ids, model names and session names.

One-shot

alphaa ask "Summarize the README" -p openai -m gpt-4o-mini
echo "summarize this repo" | alphaa -p openai      # pipe stdin = one-shot ask

Providers

| id | name | kind | default model | key | |-------------|--------------------|-------------|-------------------------------|---------| | claude | Claude (Anthropic) | anthropic | claude-sonnet-4-5 | required | | gemini | Google Gemini | gemini | gemini-2.5-flash | required | | openai | OpenAI | openai | gpt-4o-mini | required | | openrouter | OpenRouter | openai | meta-llama/llama-3.3-70b-instruct | required | | qwen | Qwen (DashScope) | openai | qwen-plus | required | | pollinations| Pollinations | openai | openai | optional | | opencode | OpenCode Zen | openai | deepseek-v4-flash | optional | | blackbox | Blackbox AI | openai | blackboxai/openai/gpt-4o | optional |

pollinations, opencode and blackbox work without a key; if you set one, it is used.

API keys

Keys are read from (in order): your shell environment, ~/.alpha-agent/.env, or .env in the current directory. The configure wizard writes them for you.

# shell
export OPENAI_API_KEY=sk-...

# or ~/.alpha-agent/.env
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
OPENROUTER_API_KEY=sk-or-...
DASHSCOPE_API_KEY=sk-...     # qwen (also QWEN_API_KEY / ALIBABA_API_KEY)
POLLINATIONS_API_KEY=...     # optional
OPENCODE_API_KEY=...         # optional
BLACKBOX_API_KEY=...         # optional

CLI commands

alphaa                       Start the interactive chat REPL
alphaa ask "<question>"      One-shot prompt (-p provider, -m model, -s session, --no-tools, --new)
alphaa configure             Interactive setup wizard
alphaa sessions              List all sessions
alphaa use <session>         Switch the active session
alphaa new [name]            Create and switch to a new session
alphaa rm <session>          Delete a session
alphaa rename <s> <new>      Rename a session
alphaa providers             Show available providers and default models
alphaa system "<prompt>"     Set the default system prompt
alphaa status                Show config path, provider, sessions and key status
alphaa serve                 Start the web UI (default port 3838)
alphaa env                   Show which API keys are set (values hidden)
alphaa help                  Show this help

REPL commands

/help /new [name] /use <session> /list /rm <session> /rename <s> <new> /clear /provider <p> /model <m> /system <text> /tools on|off /temperature <n> /usage /config /session /exit

Web UI

alphaa serve --port 8080
# open http://127.0.0.1:8080

Streaming responses, a session sidebar, provider/model pickers and a tools on/off toggle. The server binds to 127.0.0.1 by default.

Sessions

Sessions persist in ~/.alpha-agent/sessions/<id>.json; the active session is stored in ~/.alpha-agent/state.json so it survives restarts. You can keep one session per project, per language, per mood — and hop between them any time.

alphaa new coding
alphaa ask "add error handling" -s coding
alphaa use research

Programmatic API (JavaScript)

import { Agent, SessionStore, loadConfig } from 'alpha-agent-ai';

const store = new SessionStore().init();
const agent = new Agent({
  store,
  config: loadConfig(),
  providerId: 'openai',
  model: 'gpt-4o-mini',
});

for await (const ev of agent.stream('What is 2 + 2?')) {
  if (ev.type === 'text') process.stdout.write(ev.text);
}

Events

Providers and the agent emit normalized events:

| type | payload | |---------------|------------------------------------------------------| | text | { text } — a chunk of assistant text | | reasoning | { text } — reasoning tokens (when the model sends them) | | tool | { toolCalls } — the model requested tool calls | | tool_result | { name, args, result } — a tool ran | | usage | { promptTokens, completionTokens, totalTokens } | | result | final { text, sessionId, sessionName, provider, model, usage } | | error | { message } |

Built-in tools

shell, read_file, write_file, list_dir, web_fetch. Models that reject tool calls are detected and automatically retried without tools. Override with new Agent({ toolExecutor }) or swap the tool list with new Agent({ tools }).

Python companion

from alpha_agent import Agent, default_store, load_env

load_env()                       # loads ~/.alpha-agent/.env
store = default_store()
agent = Agent(store, config={"provider": "openai", "model": "gpt-4o-mini"})

for event in agent.stream("List the files in this directory"):
    if event["type"] == "text":
        print(event["text"], end="", flush=True)

The Python package ships the same providers, sessions, tool loop and CLI (alphaa becomes available after pip install). Python ≥ 3.9, stdlib only.

Configuration

~/.alpha-agent/config.json is generated by alphaa configure:

{
  "provider": "openai",
  "model": "gpt-4o-mini",
  "system": "You are AlphaAgent...",
  "temperature": 0.7,
  "maxTokens": 4096,
  "tools": true,
  "maxToolRounds": 8,
  "port": 3838
}

Development

npm test               # Node test suite (18 tests)
npm run test:python    # Python test suite (14 tests)
node bin/alpha-agent.js --version

License

MIT