Architecture

Phoenix Agent is built as a modular Python application with a clear separation of concerns.

Design Principles

• Modular — Every subsystem is independent and communicates via the event bus
• Secure by default — No destructive action without explicit permission
• Provider-agnostic — All AI providers implement the same interface
• Windows-native — Mouse/keyboard via Win32 API (ctypes), zero external deps
• Extensible — Plugins can add commands, providers, and behaviors

Directory Structure

src/phoenix_agent/
├── core/           # Engine, event bus, command registry, intelligence
├── cli/            # CLI entry point (Click + Rich)
├── ui/             # TUI (Textual) - optional
├── commands/       # All slash command implementations
├── providers/      # AI provider abstraction layer
├── security/       # Encryption, trust, permissions, audit
├── memory/         # Persistent conversation & knowledge
├── agents/         # Specialized sub-agents
├── plugins/        # Dynamic plugin system
├── mouse/          # Win32 mouse/keyboard control
├── automation/     # Workflow engine
├── scheduler/      # Task scheduling
├── filesystem/     # File operations & watching
├── terminal/       # Shell execution
├── telemetry/      # Metrics & analytics
├── config/         # Settings & profiles
└── utils/          # Windows system detection

Core Components

PhoenixEngine

The central orchestrator (core/engine.py). It initializes all subsystems, routes user input (commands vs chat), manages action history (undo/redo/timeline), and coordinates shutdown.

Event Bus

Decoupled pub/sub system (core/events.py). Modules communicate without direct dependencies:

COMMAND_EXECUTED / COMMAND_FAILED
MESSAGE_RECEIVED / MESSAGE_SENT
TRUST_ENABLED / TRUST_DISABLED
PLUGIN_LOADED / PLUGIN_UNLOADED
PROVIDER_CONNECTED / SHUTDOWN

Command Registry

Commands self-register with metadata (category, aliases, trust requirement). Execution is timed and error-handled (core/registry.py).

Provider Layer

All providers implement the AIProvider abstract class:

class AIProvider(ABC):
    async def validate_key(api_key) -> bool
    async def list_models(api_key) -> list[ModelInfo]
    async def chat(messages, model, **kwargs) -> ChatResponse

Execution Pipeline

When the AI responds, Phoenix parses the response for action blocks:

1. AI receives message + system prompt (with system context)
2. AI responds with [EXEC]/[MOUSE]/[KEYS] blocks
3. Phoenix extracts blocks via regex
4. If trust ON: execute each action sequentially
   If trust OFF: block and show warning
5. Results appended to response
6. Action logged to timeline + decision journal

Win32 Mouse/Keyboard

Native Windows control via ctypes — no pyautogui needed:

WinMouse: move_to, click, double_click, scroll, drag_to, position
WinKeyboard: type_text, hotkey, press (full VK code map)

Data Flow

User Input
    │
    ├── starts with "/" ──► CommandRegistry.execute()
    │                           └── Command.handler() ──► UI
    │
    └── plain text ──► ProviderManager.chat()
                           └── AIProvider.chat()
                                 └── Response
                                       └── _process_exec_blocks()
                                             ├── [EXEC] ──► _run_shell()
                                             ├── [MOUSE] ──► WinMouse
                                             └── [KEYS] ──► WinKeyboard

Configuration

Settings stored in %LOCALAPPDATA%\phoenix-agent\:

phoenix-agent/
├── settings.json    # User preferences, profiles
├── keys/            # Encrypted API keys (Fernet/AES-128)
├── memory/          # Conversations + knowledge base
├── journal/         # Decision journal
├── plugins/         # User plugins
└── audit_log.json   # Security audit trail