AlphaAgent

AlphaAgent is a secure, CLI-first AI coding assistant built on LiteLLM (multi-provider). The interactive CLI (alpha-agent chat) runs an Agent / AgentSession loop with tool calling, filesystem sandboxing, and a tiered shell command policy.

Optional modules (e.g. EventBus in alpha_agent/core/) are not wired into the default chat or run paths.

Security-first design

Layer	Behavior
Workspace (tools)	FilesystemGuard under ~/.alpha-agent/workspace/
Agent data	Sessions, memory, logs, plugins, exports, and CLI history under ~/.alpha-agent/workspace/AgentOrchestra/
Shell	SAFE / CONFIRM / BLOCK; BLOCK is absolute
Modes	safe, dev, unrestricted - Security_Guide.md
Audit	AgentOrchestra/logs/audit.log (JSONL)

Features

Routing persisted in config.yaml, /dispatch, footer + token meter, tool panels, doctor, /mode, /debug, /undo, /export + silent auto-save; persisted history and memory under AgentOrchestra.

Recently added features:

• alpha-agent --reset / -r for a full local reset (--reset-yes for non-interactive scripts)
• /routes + /route separation (listing vs add binding)
• Better Windows logging compatibility (UTF-8 stderr + ASCII-safe route logs)
• Better background process kill behavior (Windows process tree + GUI detection)
• Slash command autocomplete and expanded command set

Install

Requires prompt_toolkit>=3.0.0 (installed automatically from pyproject.toml).

pip install -e .
alpha-agent init
alpha-agent doctor
alpha-agent chat

Quick start

alpha-agent chat

Global options (including --reset): alpha-agent --help.

Plugins

You can add custom tools as plugins. Start here:

• Plugin Guide

Quick path:

1. Create a .py file in ~/.alpha-agent/workspace/AgentOrchestra/plugins/
2. Define tools using @tool(...) from alpha_agent.tools.base
3. Validate with /plugins in chat or alpha-agent tools list

Documentation

Index (recommended): docs/README.md

Quick links: docs/slash-commands.md · docs/agents.md · docs/personas.md · Plugins_Guide.md · Configuration_Guide.md · CLI_Reference.md