CleverAgents Core

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

Highlights

• Unified CLI entry points: cleveragents and agents
• Fast Typer/Click-based interface with parity for help/version behavior
• Interactive TUI (agents tui) built on Textual with persona management, slash commands, and fuzzy reference resolution
• Behavior-driven coverage via Behave and Robot Framework
• Nox automation for linting, typing, testing, docs, builds, and benchmarks
• MkDocs-powered documentation with CleverAgents branding

Feature Overview

Feature	Description
Plan lifecycle	Full strategize → execute → apply pipeline with LLM actors
Actor system	YAML-defined actors compiled to LangGraph graphs
Skill registry	Composable skill bundles with MCP, file, git, and inline tools
Resource system	DAG-based resource registry with 30+ built-in types (git, fs, container, LSP)
Automation profiles	Named profiles (manual, cautious, supervised, auto, ci, full-auto) controlling autonomy
Sandbox & checkpoint	Copy-on-write, overlay-fs, git-worktree, and transaction sandbox strategies
ACMS	Advanced Context Management System with UKO ontology and 10-stage assembly pipeline
TUI	Textual terminal UI with personas, slash commands, and @-reference picker
A2A / Server	Agent-to-Agent protocol facade; Kubernetes Helm chart for server deployment
Observability	LangSmith tracing, structured logging via structlog, audit event bus

Quick Start

# clone the CleverAgents core repository
git clone https://git.cleverthis.com/cleveragents/cleveragents-core.git
cd cleveragents-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

First plan

# initialise the local database
agents init

# register a project
agents project create local/my-project --description "My first project"

# add a git resource
agents resource add git-checkout local/my-repo --url https://github.com/example/repo.git

# link resource to project
agents project link-resource local/my-project local/my-repo

# create an action
agents action create --config examples/actions/simple.yaml

# start a plan
agents plan use local/my-action --project local/my-project

# execute the plan (requires an LLM API key)
agents plan execute

Interactive TUI

# install the optional Textual dependency
pip install 'cleveragents[tui]'

# launch the TUI
agents tui

# headless startup check (no Textual required)
agents tui --headless

Inside the TUI:

Key / Prefix	Action
F1	Toggle context-sensitive help panel
/	Open slash command overlay (67 commands)
@	Open reference picker (projects, plans, resources, …)
!	Shell passthrough mode
Tab	Cycle to next persona
Ctrl+Q	Quit

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.