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
• 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; Markdown transcript export (--format md) for human-readable sharing
• First-run experience — ActorSelectionOverlay guides new users to pick an actor on first TUI launch; creates a "default" persona automatically
• 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)
• 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
• Estimation lifecycle — actor.default.estimation config key wires an estimation actor into the Strategize-to-Estimate lifecycle hook
• Shell danger detection — TUI shell mode (! prefix) classifies commands by danger level (LOW → CRITICAL) and surfaces a warning overlay before executing destructive, privilege-escalating, or exfiltration-risk commands
• Inline permission questions — PermissionQuestionWidget renders single-file permission requests directly in the conversation stream with single-key shortcuts
• Invariant reconciliation — InvariantReconciliationActor runs automatically at every plan phase transition; failures block the transition and emit INVARIANT_VIOLATED
• UKO provenance tracking — every typed triple now carries sourceResource, validFrom, and isCurrent metadata; a revision chain enables temporal queries
• JSON-RPC 2.0 A2A wire format — A2aRequest/A2aResponse fields renamed to standard JSON-RPC 2.0 names (method, id, result, error)
• 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

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

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

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/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.