Introduction

Arcen Agent is a next-generation, self-improving AI agent framework designed to execute, deploy, and scale autonomous workflows. Unlike traditional one-shot LLM runners, Arcen uses a Dialectic Learning Loop that evaluates run-time outputs, adapts procedural behavior, and remembers interactions across execution boundaries.

Core Philosophy: The Dialectic Learning Loop

At the heart of Arcen is the concept of a self-improving agent. The agent loop does not just perform actions; it critiques them:

Thesis (Execution): The agent accepts a user goal and plans a series of tool calls.
Antithesis (Evaluation): Verification scripts, terminal outcomes, or human-in-the-loop approvals critique the tool execution.
Synthesis (Learning): The agent saves learnings into its procedural memory (skills/), ensuring future sessions benefit from the correction.

What Arcen Provides

Arcen integrates multiple architectural layers to create a cohesive developer and runtime experience:

1. Unified Interface Surfaces

Interactive CLI: Rich terminal sessions built with prompt_toolkit and Rich displaying real-time tool runs and model streams.
Ink-Based TUI: React-like terminal component layout via ui-tui and a stdio-based Python JSON-RPC gateway (tui_gateway).
Messaging Gateway: Multi-platform support (gateway/) enabling remote control of your agent using Telegram, Slack, WhatsApp, Signal, Discord, and more.

2. Extensible Capabilities & Plugins

Pluggable Architecture: Extend core functionality without touching core packages. Write custom model providers, memory store adapters, context engines, or custom tools under ~/.arcen/plugins/.
Built-in Toolsets: System access, Git management, Web search, and directory analysis tools registered with automatic parameter validation.
Docker & SSH Isolation: Run code safely inside terminal backend sandbox environments (Docker, SSH, Singularity, Daytona, Modal, or local).

3. State & Memory Management

Persistent Sessions: Powered by a robust SQLite Session Database with Full-Text Search (FTS5) for querying past trajectories.
Procedural Skills: Load runtime instructions interactively, compile new skills with /learn, and keep them synchronized across execution profiles.

Repository Structure

To help you find your way around the codebase, here are the main files and folders:

arcen-agent/
├── run_agent.py          # AIAgent class — handles core LLM conversation loop
├── model_tools.py        # Orchestrates tool selection, requirements, and execution
├── toolsets.py           # Defines groupings of active tools (e.g. _ARCEN_CORE_TOOLS)
├── cli.py                # Terminal user interface using prompt_toolkit & Rich
├── arcen_state.py        # SQLite SessionDB storage engine
├── arcen_constants.py    # Directory resolutions & profile path overrides
├── gateway/              # Multi-platform gateway runtime (Telegram, Slack, etc.)
├── plugins/              # Built-in and user-level extension modules
├── ui-tui/               # TypeScript & Ink UI components for the TUI
└── tui_gateway/          # Python backend for TUI communications

To learn more about how these parts interact, read our Architecture Guide.