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.

Local Source-Code Workflow (v3.0.0 — v3.1.0)

CleverAgents v3.0.0 introduced the minimal local source-code workflow — a complete end-to-end pipeline for using an LLM to make changes to a local git repository, with full isolation, review, and apply steps. v3.1.0 extended this with the Actor Compiler and full LangGraph integration.

v3.0.0 — Minimal Local Source-Code Workflow

The core plan lifecycle commands let you describe a task, execute it with an LLM, review the proposed changes in a sandbox, and merge them into your repository:

# 1. Register the target repository as a resource
agents resource add git-checkout \
  --name local/my-repo \
  --path /path/to/my-repo

# 2. Create a project and link the resource
agents project create --name local/my-project
agents project link-resource \
  --project local/my-project \
  --resource local/my-repo

# 3. Define the task as an action
agents action create --config action.yaml

# 4. Create a plan from the action
agents plan use \
  --action local/my-action \
  --project local/my-project \
  --automation-profile trusted

# 5. Execute: LLM runs Strategize + Execute phases, writes to sandbox
agents plan execute <plan_id>

# 6. Review the proposed changes
agents plan diff <plan_id>

# 7. Merge changes into the repository
agents plan apply <plan_id>

Key v3.0.0 capabilities:

• Git worktree sandbox — changes are written to an isolated branch (cleveragents/plan-<id>); plan apply merges via git merge and cleans up
• SQLite persistence — all records (actions, plans, resources, projects, ChangeSets) are persisted locally; Alembic manages schema migrations
• Pydantic v2 domain models — all domain objects are immutable (frozen=True) Pydantic v2 models for type safety and validation
• State machine transitions — plans move through CREATED → READY → STRATEGIZING → EXECUTING → EXECUTED → APPLYING → APPLIED with explicit lifecycle guards

v3.1.0 — Actor Compiler + Full LLM Integration

v3.1.0 introduced the Actor YAML schema v3 and the actor compiler, enabling multi-node LangGraph workflows to be defined declaratively and compiled at registration time:

# Register an actor from a YAML file
agents actor add --config actor.yaml

# Register skills (tool collections) and individual tools
agents skill add --config skills/file-ops.yaml
agents tool add --config tools/validate.yaml

# Connect an external MCP tool server as a skill source
agents skill add --mcp http://localhost:3000 --name local/mcp-tools
agents skill refresh  # re-fetch tool list after server updates

# Attach validation rules to resources (gates plan apply)
agents validation attach \
  --resource local/my-repo \
  --validation local/run-tests \
  --tier required

Key v3.1.0 capabilities:

• Actor YAML v3 schema — version: "3" files declare type: llm | tool | graph; graph-type actors compile into LangGraph StateGraph structures
• GRAPH-type actor compilation — compile_actor() resolves node definitions, edges, conditional routing, and subgraph references at registration time
• Skill registry — skills are collections of tools; the flattened tool set is persisted for fast lookup during plan execution
• MCP adapter — any MCP-compatible tool server can be registered as a skill source; tools are discovered automatically and wrapped in the CleverAgents protocol
• Validation runner — required validations gate plan apply; informational validations report without blocking; ApplyValidationSummary aggregates results
• Multi-file ChangeSet — the execute phase produces a structured ChangeSet with one FileChange per file; plan diff and plan apply use it for accurate multi-file display and merge

For the full CLI reference for these commands, see docs/cli.md.