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; 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); 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
• Inline permission questions — PermissionQuestionWidget renders single-file permission requests directly in the conversation stream; single-key shortcuts (a/A/r/R) resolve without opening the full overlay
• Shell danger detection — TUI shell mode (! prefix) scans commands against a configurable pattern registry before execution; warning overlay surfaces dangerous patterns (CRITICAL/HIGH/MEDIUM/LOW) and lets the user abort or proceed
• 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
• 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)
• Git worktree sandbox — plan apply merges LLM-generated changes via git merge from an isolated worktree branch; non-git projects fall back to flat file copy
• ACMS context hydration — ContextTierService is now populated automatically before every plan execution via context_tier_hydrator.py; LLM receives real file context from linked project resources instead of an empty context window
• 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

On first launch, the Actor Selection Overlay guides you through picking an actor. A default persona is created automatically. 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

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

Documentation Index

Resource	Description	Link
Getting Started	Step-by-step setup and first plan	docs/guides/getting-started.md
CLI Reference	All agents commands and flags	docs/api/cli-reference.md
Python API	Application layer API reference	docs/api/python-api.md
Architecture Overview	Six-layer architecture and design	docs/architecture/overview.md
ADR Index	Architecture Decision Records	docs/adr/index.md
Release Notes	Version history and release notes	docs/release-notes/index.md
Observability	LangSmith, logging, metrics	docs/observability.md
Contributing	Contributor guide	docs/development/contributor-guide.md
Quality Automation	Nox, pre-commit, CI	docs/development/quality-automation.md

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