Architecture

caretta is organized as a Cargo workspace with a focused separation between shared types, provider adapters, and the main application runtime.

Workspace layout

crates/
  cli-common/     Shared enums, workflow/config types, event model
  agent-common/   AgentCliAdapter trait and adapter helpers
  claude/         Claude adapter crate
  cline/          Cline adapter crate
  codex/          Codex adapter crate
  copilot/        Copilot adapter crate
  cursor/         Cursor adapter crate
  gemini/         Gemini adapter crate
  junie/          Junie adapter crate
  xai/            xAI adapter crate
  cli/            Main application crate (package `caretta`)
assets/
  skills/         Bundled skill files
  workflows/      Bundled workflow presets and prompts

Main crate responsibilities

crates/cli/src/main.rs is a thin binary shim.

crates/cli/src/lib.rs handles:

CLI argument parsing (clap).
Runtime dispatch for subcommands.
Asset materialization for workflow/skill availability.
Dioxus app bootstrapping and state wiring.

Agent runtime modules

Key modules under crates/cli/src/agent/ include:

adapter_dispatch.rs: maps shared Agent enum values to adapter implementations.
actions.rs: one-shot action registry.
assets.rs: bundled asset materialization and lookup.
workflow.rs and workflows.rs: workflow discovery and execution.
tracker.rs: issue/PR parsing and tracker-related prompting.
run.rs: subprocess execution and event parsing.
refresh.rs: refresh docs/agents actions.
config_store.rs: keychain-backed secret storage logic.

UI architecture

The Dioxus UI is split into domain-focused modules under src/ui/:

sidebar.rs: run controls and project action surfaces.
editor.rs: tabbed event/content surfaces.
personas.rs: persona management UI + persistence hooks.
security.rs: security scan panel and finding presentation.
server.rs: web server support for caretta serve.

Runtime flow summary

Parse CLI and config.
Materialize bundled assets if needed.
Resolve model, workspace, and adapter settings.
Dispatch to UI launch or command handler.
Stream agent events into unified output timelines.

Platform-specific behavior

The codebase uses #[cfg(target_arch = "wasm32")] guards for web-specific behavior and desktop-only persistence paths.

Desktop mode can perform local file operations for features such as personas. Web mode serves UI and avoids desktop-only storage responsibilities.

Last modified: 02 July 2026