Cantrip Documentation

Learn how to use Cantrip to build production-quality Juju charms with AI.

This documentation follows the Diataxis framework, organising content by what you need: learning, solving problems, looking things up, or understanding how the system works.

Start here

  1. Install Cantrip. The tutorial starts with the end-user install flow; if you still need to choose a provider, continue with Choose an LLM provider.
  2. Pick your surface. Use Choose an interface to decide between the TUI, Web UI, CLI REPL, and print mode.
  3. Decide whether you are building or improving. For a new charm, start with the tutorial. For an existing charm, jump to Improve an existing charm.
  4. Need automation or tighter governance? Go straight to print mode, tool permissions, and audit trail inspection.
Tutorial

Build your first charm

A guided walkthrough from installation to a deployed, tested charm. No prior Cantrip experience required.

How-to

Choose an LLM provider

Pick the right provider and model for your situation — cloud API, local inference, or hybrid.

How-to

Choose an interface

Decide between the TUI, Web UI, CLI REPL, and print mode based on your terminal, browser, or automation workflow.

How-to

Improve an existing charm

Audit and upgrade an existing charm: add tests, fill observability gaps, modernise deprecated APIs.

How-to

Export transcripts

Export session transcripts as HTML, Markdown, or JSONL for documentation or review.

How-to

Run a single goal non-interactively

Drive one goal end to end in CI, shell pipelines, or scheduled jobs with cantrip run --print.

How-to

Configure light models

Route internal tasks to cheaper models to reduce cost without sacrificing output quality.

How-to

Index the charm docs

Crawl Canonical's documentation surfaces (Juju, ops, charmcraft, rockcraft, jubilant, Charmhub) and let the agent cite passages via docs_search and @docs <site> <query> instead of paraphrasing from memory.

How-to

Use durable memory

Record lessons with /remember, let the auto-writer capture corrections, export shareable SKILL.md bundles, and keep the index fresh via revalidation and TTL.

How-to

Share with teammates

Three opt-in toggles — shared memory, shared decisions log, human co-author trailer — turn Cantrip into a small-team tool by committing .cantrip-shared/ to git. No server, no live collab, just files alongside the charm.

How-to

Add a custom skill

Drop a standard-format skill into ~/.claude/skills/ or ~/.config/cantrip/skills/ and Cantrip picks it up at startup — vendor-neutral format, optional tools: list, bundled skills can be overridden.

How-to

Run a recipe

Parameterised, retryable workflows committed alongside the charm: /recipe charm-cos-add or /recipe charm-reactive-to-ops ship the same prompt, the same parameter shapes, and the same convergence checks every time.

How-to

Walk a flow

Mermaid decision trees the agent walks step by step: /flow charm-cos-enable, /flow charm-reactive-to-ops, or /flow charm-upgrade-ladder. The agent announces branch decisions inline so you can follow its reasoning.

How-to

Configure MCP servers

Attach third-party tools via cantrip.mcp.yaml — stdio and HTTP transports, OAuth 2.1, mid-task elicitation, and marketplace discovery.

How-to

Search the charm library

Use the Librarian subagent and /search-charms to find existing Charmhub and Launchpad charms before reinventing them — quality flags surface stale or borderline hits.

How-to

Generate a charm icon

Paint a Charmhub-style icon.svg for a charm via /icon — LLM-driven, square, designer-polish recommended; bounded by a per-session USD cap.

How-to

Add identity-platform login

Wire OIDC, OAuth, or federated login into a charm via Hydra, Kratos, and identity-platform-login-ui — the bundled identity-platform skill picks the right relation and library for the charm's role.

How-to

Configure hooks

Run shell commands at lifecycle events via cantrip.hooks.yaml — pre/post tool calls, compaction, subagent start/stop; JSON payload piped to stdin.

How-to

Configure tool permissions

Control which tool calls auto-run, ask for confirmation, or are denied outright with repository and user-level policy files.

How-to

Convene the inner parliament

Run emotion subagents over your charm for a multi-lens review — delight, risk, friction, taste, empathy.

Reference

CLI reference

Complete listing of all commands, flags, and environment variables.

Reference

Audit policy decisions

Inspect .cantrip-audit.jsonl after unattended runs or export it as JSONL or CSV for review and CI artefacts.

Reference

Agent tools

Every tool the agent can use, grouped by category, with descriptions and parameters.

Explanation

How Cantrip works

The two-loop architecture, work queue, subagents, and why autonomous operation matters.

Explanation

The three charm paths

Why there are three approaches to charm building and how the agent selects the right one.

Explanation

Observability and debugging

How Cantrip uses COS, Tempo, and Loki to debug charms autonomously.

Explanation

Quickpack Rust backend

Why quickpack has a Rust implementation, how Cantrip selects it, and measured performance.

Explanation

Charmlint Rust backend

Why charmlint has a Rust implementation, how Cantrip selects it, and measured performance.

Explanation

Emotion subagents

Why there are five personality-driven review lenses, how they're scoped to avoid overlap, and the tradeoffs.

Explanation

Racing and Arena

How Cantrip ranks Best-of-N candidates by charm quality and how blind A/B /arena captures your model preferences.

Explanation

TUI screens and shortcuts

The function-key modals — Logs, Traces, Graph, File detail — and the Dev and COS status panes.