cleveragents-core/README.md

CleverAgents Core

CleverAgents is a Python-first automation platform. It provides a unified agents CLI, an interactive Textual TUI, embedded runtime, and service orchestration tools while embracing modern Python tooling.

Highlights

• Unified CLI entry points: cleveragents and agents
• Interactive TUI (agents tui) — full-screen Textual app with multi-session tabs, persona switching, slash commands, reference picker, and context-sensitive F1 help
• First-run experience — actor selection overlay on first launch; creates a default persona automatically so you can start chatting immediately
• Persona system — YAML-backed personas bind actors, argument presets, and scope references to named identities; persisted in ~/.config/cleveragents/personas/
• Session management — create, list, export, and import conversation sessions; full JSON export/import for portability; export/import also available inside the TUI
• Server mode — agents server connect configures a remote CleverAgents server; Kubernetes Helm chart in k8s/ for production deployment
• A2A integration — Agent-to-Agent protocol facade wires CLI and TUI to live application services (session, plan, registry, event); ValueError now maps to VALIDATION_ERROR for correct protocol semantics
• Permissions screen — TUI overlay for reviewing tool permission requests with unified, side-by-side, and context diff views; session-scoped allow/reject decisions
• Actor thought blocks — expandable reasoning trace widgets rendered inline in the conversation stream with muted styling
• UKO runtime — Universal Knowledge Ontology query interface, inference engine, and graph persistence for ACMS context strategies
• Database resource handler — full CRUD and checkpoint/rollback support for SQLite, PostgreSQL, MySQL, and DuckDB resources
• Devcontainer resource handler — delete(), list_children(), diff(), and create_sandbox() now fully implemented
• Estimation lifecycle — actor.default.estimation config key wires an estimation actor into the Strategize-to-Estimate lifecycle hook; emits PLAN_ESTIMATION_COMPLETE domain event; failures are informational and never block Execute
• Enriched domain events — PLAN_APPLIED carries changeset statistics (files changed, lines added/removed, resources modified, apply duration); PLAN_CANCELLED includes progress context; all events carry user_identity
• Correction attempts — correction_attempts table tracks every decision correction with full lifecycle state machine (pending → executing → complete/failed)
• Fast Typer/Click-based interface with parity for help/version behavior
• Behavior-driven coverage via Behave and Robot Framework
• Nox automation for linting, typing, testing, docs, builds, and benchmarks
• MkDocs-powered documentation with CleverAgents branding

Quick Start

# clone the CleverAgents core repository
git clone https://git.cleverthis.com/cleveragents/core.git
cd core

# install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,tests,docs]"

# set up pre-commit hooks and verify tooling
bash scripts/setup-dev.sh

# verify the CLI
agents --help
agents --version

Launch the TUI

# install TUI extra
pip install -e ".[tui]"

# launch the interactive terminal UI
agents tui

On first launch, the Actor Selection Overlay guides you through picking an actor. A default persona is created automatically. Inside the TUI:

• Type a message and press Enter to chat with the active actor
• Press / to open the slash command overlay (67 commands across 14 groups)
• Press @ to open the reference picker and insert file/resource references
• Press ! to enter shell mode and run a subprocess command
• Press F1 to toggle the context-sensitive help panel
• Press Ctrl+T to cycle through argument presets for the active persona
• Press Ctrl+Q to quit

Session management

agents session create --actor openai/gpt-4o
agents session list
agents session export --session-id <ID> --output session.json
agents session import --input session.json

Server mode

# connect to a remote CleverAgents server
agents server connect --url https://my-server.example.com --token <TOKEN>

# check connection status
agents server status

Estimation lifecycle

Configure an estimation actor to get cost/time/risk forecasts before plan execution:

agents config set actor.default.estimation anthropic/claude-4-sonnet
agents plan use <PLAN_ID>
agents plan execute  # estimation runs automatically before Execute phase
agents plan show <PLAN_ID>  # shows cost_estimate_usd and risk level

Developing

Pre-commit hooks run automatically on every git commit (formatting, linting, type checking, security scanning). To run checks manually:

# core validation
nox -s format            # ruff auto-formatting
nox -s lint              # ruff linting
nox -s typecheck         # pyright type checking
nox -s unit_tests        # behave unit tests
nox -s integration_tests # robot integration tests

# quality & security
nox -s security_scan     # bandit security scanning
nox -s dead_code         # vulture dead code detection
nox -s complexity        # radon complexity analysis
nox -s pre_commit        # run all pre-commit hooks
nox -s adr_compliance    # verify ADR compliance

For the full quality automation guide, see docs/development/quality-automation.md.

Documentation

nox -s docs
nox -s serve_docs

Key reference documents:

• Architecture Overview
• TUI Reference
• Plan Lifecycle
• Estimation Lifecycle
• Decision Correction
• Correction Attempts
• Resource Handlers
• UKO Runtime

Tests

Behave feature scenarios live under features/ and Robot suites under robot/. Use the Nox sessions above to execute them in parity with the implementation plan.

Observability

LangSmith tracing is optional and off by default. Enable it by exporting CLEVERAGENTS_LANGSMITH_ENABLED=true along with a project name and API key (CLEVERAGENTS_LANGSMITH_PROJECT, CLEVERAGENTS_LANGSMITH_API_KEY). The settings module automatically mirrors these values to LANGCHAIN_TRACING_V2, LANGCHAIN_PROJECT, and LANGCHAIN_API_KEY, so LangChain/LangGraph agents emit traces without extra wiring. Additional knobs such as CLEVERAGENTS_LANGSMITH_ENDPOINT, CLEVERAGENTS_LANGSMITH_USER_ID, and CLEVERAGENTS_LANGSMITH_TAGS are documented in docs/reference/observability.md.

LLM provider configuration

CleverAgents ships with a LangChain/LangGraph powered provider registry that discovers whichever API keys you export and automatically selects the best available provider. The CLI now uses actors: select an actor with --actor <name> (or set a default via agents actor set-default). Actors embed provider/model choices; built-in actors are seeded from CLEVERAGENTS_DEFAULT_PROVIDER / CLEVERAGENTS_DEFAULT_MODEL, then fall back to the built-in order (openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini).

Required environment variables

Provider	Primary variables
OpenAI	OPENAI_API_KEY
Anthropic	ANTHROPIC_API_KEY
Google	GOOGLE_API_KEY or GOOGLE_GENAI_API_KEY
Azure OpenAI	AZURE_OPENAI_API_KEY plus AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_DEPLOYMENT
OpenRouter	OPENROUTER_API_KEY (+ optional CLEVERAGENTS_OPENROUTER_ORGANIZATION for sanitized headers)
Gemini	GEMINI_API_KEY or GOOGLE_GEMINI_API_KEY
Cohere	COHERE_API_KEY
Groq	GROQ_API_KEY
Together	TOGETHER_API_KEY

Set CLEVERAGENTS_DEFAULT_PROVIDER to pin the global provider (for example export CLEVERAGENTS_DEFAULT_PROVIDER=openai) and CLEVERAGENTS_DEFAULT_MODEL to lock in a model ID. When unset, the registry picks the first configured provider and uses its published default model such as gpt-4o for OpenAI or claude-sonnet-4-20250514 for Anthropic.

Diagnostics and testing shortcuts

• agents diagnostics prints whether the registry can see your credentials and which actor/provider is selected.
• agents tell and agents build require --actor <name> unless a default actor is set; use agents actor set-default <name> to configure one.
• Built-in actors (<provider>/<model>) are immutable, custom actors must be named local/<id>, and the default actor cannot be removed. Use --unsafe when adding/updating configs marked unsafe; runtime only warns when invoking unsafe actors.
• CLEVERAGENTS_TESTING_USE_MOCK_AI=true forces the in-repo mock provider so Behave/Robot suites never hit external APIs.
• The full capability matrix (streaming, tool calls, JSON mode, etc.) is documented in docs/reference/providers.md.

What's New in v3.7.0

See CHANGELOG.md for the full list. Highlights:

• TUI — full Textual-based interactive terminal UI with persona system, 67 slash commands, reference picker, permissions screen, thought blocks, and first-run experience
• Session management — agents session command group with export/import
• Server mode — agents server connect + Kubernetes Helm chart
• A2A integration — local facade wired to live application services
• Estimation lifecycle — optional pre-Execute cost/time/risk forecasting
• Enriched domain events — PLAN_APPLIED with changeset stats, user_identity on all events
• Correction attempts — full lifecycle tracking for decision corrections
• Resource handlers — DatabaseResourceHandler and DevcontainerHandler protocol completion
• UKO runtime — query interface, inference engine, and graph persistence
• ACMS — Phase 2 pipeline protocol aliases
• Bug fixes — session DI wiring, plan stale-cache, project context commit, action --format flag