GitHub - flockcap/cantrip: Speak plainly. Get the incantation. A beautiful, keyless shell companion.

A plain-English wish becomes a highlighted command, then converts three PNGs to WebP.

A small, beautiful terminal tool that turns a wish into the exact shell command. Uses the Claude Code / Codex / Gemini / opencode you already have — no API key, no new subscription.

Install

curl -fsSL https://cantrip.fyi/install | sh

brew install flockcap/tap/cantrip

irm https://cantrip.fyi/install | iex

cargo binstall cantrip-cli       # once the crate is published
cargo install cantrip-cli        # once the crate is published
nix run github:flockcap/cantrip -- "find the largest files here"

Run cantrip update for the latest stable release. Homebrew installs update through Homebrew; Nix installs stay managed by your flake. Update checks happen only when requested.

Or grab a prebuilt binary.

Usage

cantrip resize every png here to 800px webp
cantrip find files larger than 100mb
cantrip --agent codex undo the last commit but keep my changes
cantrip                          # a quiet input line

enter run · e edit · a alternatives · c copy · r regenerate · q quit

cantrip --json "find listening ports" returns structured JSON and never executes. Flags go before the wish; --dry-run previews, --explain adds detail, and --yolo skips the first confirmation.

Gruvbox by default. --theme rose-pine or --theme flock for a change of scenery.

Dangerous shapes are flagged locally and require a second, default-No confirmation; only explicit --yolo --force bypasses it. These checks are heuristics: review commands before running them.

No telemetry, analytics, or phone-home. Wishes, directory context, and optional history go only through your own agent CLI; its provider and privacy settings still apply. Explicit installs and updates contact cantrip.fyi and GitHub. History is off by default.

Configuration, shell widgets, and Nix

mkdir -p ~/.config/cantrip
cantrip config > ~/.config/cantrip/config.toml
cantrip completions zsh          # bash / zsh / fish / powershell / elvish
source <(cantrip widget zsh)      # Alt-G turns your buffer into an editable command
# fish: cantrip widget fish | source

agent_precedence = ["claude", "codex", "gemini", "opencode"]
theme = "gruvbox"
auto_run = false
include_history = false
context_richness = "normal"      # minimal / normal / rich
history_lines = 10
agent_timeout_seconds = 120

$XDG_CONFIG_HOME is honored. Minimal context sends cwd, OS, architecture, and shell only. Normal adds a capped filename/type listing, git branch/state, and tool availability. Rich raises the listing cap. File contents are never collected. Opt-in history adds at most history_lines entries from $HISTFILE or the shell's history file. Suggestions are cached in process memory only.

Sign in to an installed agent first. Selection is claude → codex → gemini → opencode; --agent overrides it. Current agent CLIs are required; invocation details and their tool restrictions are in the adapter source. A forced agent's authentication failure is reported directly.

Nix: the flake exports packages.<system>.cantrip, overlays.default, and homeManagerModules.default for nix-darwin and home-manager:

inputs.cantrip.url = "github:flockcap/cantrip";
# in your home-manager configuration:
imports = [ inputs.cantrip.homeManagerModules.default ];
programs.cantrip = {
  enable = true;
  settings.theme = "gruvbox";
  enableZshIntegration = true;
};

Shell widgets require python3. Unix commands run in $SHELL; Windows uses %COMSPEC%. Use VISUAL or EDITOR for editing, otherwise enter a replacement inline. Clipboard uses pbcopy, clip.exe, wl-copy, xclip, or xsel.

Build and reproduce the artwork

cargo test --locked
cargo clippy --all-targets -- -D warnings
cargo build --release --locked
npm ci
npm run art                      # Chrome; bundled Iosevka fonts
vhs tapes/demo.tape               # VHS, cwebp, python3; recorded response, real execution
sh scripts/generate-release.sh    # cargo-dist 0.34

The demo uses a recorded response to keep timing repeatable. Art follows Flock's seeded dither and quiet monochrome identity. The runtime stays gruvbox.

by Flock · MIT OR Apache-2.0

flockcap/cantrip

Measured star growth

About

README.md

Install

Usage