maestro-care 0.0.1

Collaborative Agent Reasoning Ecosystem — Textual TUI demo

CARE — Collaborative Agent Reasoning Ecosystem

A Textual TUI + CLI for generating, running, and evolving CARL agent chains. CARE is the user-facing consumer on top of a four-module stack — MAGE for chain generation, CARL for execution, GigaEvo Memory for persistence, and GigaEvo Platform for evolution.

Run

uv sync
uv run care init       # one-shot: write a minimal .env with MAGE creds
uv run care            # launch the TUI
uv run care --help     # list CLI subcommands

care init walks the minimum MAGE credentials (base URL, API key, model) and writes a ./.env so a fresh checkout can boot. Use --non-interactive with explicit flags for CI / scripted setup: care init --non-interactive --api-key sk-... --base-url ... --model ....

The TUI opens directly into the chat surface — a Claude-Code-style transcript with a prompt at the bottom and a mode toggle above it. Type a task in natural language to generate + run an agent chain; type a slash command (/help, /mode, /library, /dataset, /evolution, /tour, …) for the non-chat affordances. First-time users see a one-line offer to type /tour for a 5-step walkthrough.

Chat modes

The toggle above the prompt picks one of two modes; /mode switches the same setting via the keyboard. Default is Ad-Hoc — configurable per-deployment with CARE_CHAT__DEFAULT_MODE.

Mode	What happens on every prompt
Ad-Hoc	MAGE generates a chain, CARL runs it on the spot, the answer prints inline. The agent may loop (ReAct) until it decides the task is done. Nothing is saved.
Production	MAGE generates a reproducible chain, CARE saves it to Memory under a stable chain_id, runs one baseline to seed a dataset entry, and (when Platform is wired) kicks off an evolution run. Use /dataset list <chain_id> / /dataset run <chain_id> / /evolution watch <run_id> to follow up.

Production requires CARE_MEMORY__BASE_URL (and CARE_MEMORY__API_KEY when the deployment enforces auth). Without Memory configured, selecting Production auto-falls back to Ad-Hoc with a warning line — the toggle's tooltip explains why.

First boot (no ~/.config/care/config.toml on disk) lands on the Settings screen so you can configure Memory / Platform base URLs + the MAGE LLM credentials before doing anything else. Returning users land on the chat surface; /library opens the saved-agents table (last-run time, favourite status, fitness scores, row-action keys below).

Canonical user flow

Generate Agent A → save it → generate B and C → return to A from the library → re-run from the same task + context files → optionally evolve A and accept the best individual back into the stable channel.

Screens

CARE ships 18+ screens covering the full lifecycle:

Screen	Purpose
WelcomeScreen	Boot splash + recents sidebar
LibraryScreen	Saved-agent table, row actions, search
QueryScreen	+ New agent — task description + context files
GenerationScreen	Live MAGE progress
InspectionScreen	Saved-chain detail + run history
EditAgentScreen	Inline edit + Save / Promote-to-stable
ExecutionScreen	Live CARL run + token streaming
EvolutionScreen	GA + Pareto picker + accept-winner
ReplayScreen	Step through a saved ReasoningResult
CatalogScreen	Browse installed capabilities (skills/MCP/tools)
MarketplaceScreen	Search shared agent_skill listings on Memory
HelpScreen	Tutorial + key cheat-sheet
SettingsScreen	Edit MAGE / Memory / Platform / theme
TaskListDrawer	In-flight tasks panel
CommandPaletteModal	Fuzzy palette over commands + saved entities
DiffModal	Side-by-side compare two chains
LineageModal	Walk a chain's ancestry DAG
ConflictModal	Resolve a name collision on save

Global keys

• Ctrl+P — Command palette (search commands + chains + skills)
• Ctrl+B — Task list drawer
• Ctrl+K — Capability catalog
• Ctrl+S — Save current artifact
• Ctrl+R — Re-run current chain
• ? — Help (tutorial + every binding)
• Esc — Back / cancel
• Ctrl+Q — Quit

Each screen layers its own bindings — see ? (Help) for the full set filtered by the active screen.

A single-page reference table covering every screen + modal lives at docs/screens/README.md. It maps each surface to its slash command + status (M0/M1) + primary purpose so a new contributor can locate the right module from one click.

Demo

A short asciicast walks the three CLI surfaces against a hermetic seed directory. Reproduce or re-record with:

scripts/record_demo.sh

See examples/asciicast/recording_script.md for the per-act keystroke list. The output lands at docs/asciicasts/care-tour.cast and can be embedded in this README once recorded (asciinema upload for a hosted player or a local relative link for offline reading).

Architecture

CARE is the consumer at the top of a four-module stack — see docs/ARCHITECTURE.md for the layer-by-layer walk-through (generation / execution / persistence / evolution) with cross-links to the upstream modules and CARE's internal module boundaries.

Configuration

CARE reads its configuration from three sources, in increasing precedence:

1. Defaults baked into care.config.CareConfig.
2. ~/.config/care/config.toml (user-global TOML).
3. ./care.toml in the current working directory (per-project overrides).
4. CARE_* environment variables.

Nested fields use double-underscores in env-var form, mirroring how the TOML sections nest. For example, [mage] mode = "fast" in TOML is CARE_MAGE__MODE=fast in the environment.

See .env.example for the complete list of supported variables with descriptions and defaults. Copy it to .env (or export the vars in your shell) and override only what you need.

Quick reference

Section	Env-var prefix	Purpose
mage	CARE_MAGE__*	MAGE generator (provider, API key, …)
memory	CARE_MEMORY__*	GigaEvo Memory connection
platform	CARE_PLATFORM__*	GigaEvo Platform connection
sandbox	CARE_SANDBOX__*	AgentSkill sandbox backend + limits
tools	CARE_TOOLS__*	@carl_tool registry + bundled builtins (web_search, …) + on-the-fly synthesis
telemetry	CARE_TELEMETRY__*	Opt-in event-stream sink (Langfuse, …)
defaults	CARE_DEFAULTS__*	UI defaults (language, history size)

CLI

care (no subcommand) launches the TUI. The headless subcommands share the CareConfig and data layers the TUI uses — every screen's primary affordance has a terminal twin.

Setup

• care init [--non-interactive] [--api-key X] [--base-url Y] [--model Z] [--mode ad_hoc|production] [--force] — one-shot quick-start: writes a minimal .env with the four MAGE + chat keys a fresh checkout needs. Refuses to overwrite an existing .env without --force.

Discovery & validation

• care catalog [--json] [--kind ...] — list installed AgentSkills, MCP servers, tools, capability memory cards.
• care validate <chain.json> — parse + preflight a CARL chain.
• care import <pattern>... [--apply] — batch-validate (dry-run default) or import chain JSON files.

Generate / run / replay

• care generate "<task>" [--mode fast|deep] [--save NAME] [--output PATH] — one-shot MAGE generation.
• care run <chain_id> [--execute] [--task TEXT] [--input KEY=VAL] [--save-result NAME] — fetch a saved chain, preflight, and optionally execute via CARL.
• care replay <run.json> — step through a saved ReasoningResult / RunRecord JSON.

Memory browse

• care memory ls [--entity-type ...] [--tag ...] [--q ...] — list saved entities.
• care memory show <entity_id> [--content-only] — drill down on a single entity.
• care memory history <chain_id> — list recorded runs for a chain.
• care search "<query>" [--search-type bm25|vector|hybrid] — BM25 / vector / hybrid search across saved entities.
• care diff <left_id> <right_id> — side-by-side chain compare.
• care lineage <chain_id> — walk the ancestry DAG.
• care favourite <entity_id> [--off] — star / unstar a library entity.

Capabilities & evolution

• care marketplace "<query>" — search shared agent_skill listings.
• care evolve <chain_id> [--wait] [--accept] — submit + watch + accept an evolution run.

UX

• care help [--markdown] — render the tutorial + cheat-sheet.

Run care <subcommand> --help for the full flag set on each.