Documentation

Install

pipx install chyrd          # recommended: isolated, on your PATH
pip install chyrd           # into the current environment
uv tool install chyrd       # if you use uv

To use the Claude Code engine as a backend (via the Claude Agent SDK), add the extra:

pipx install "chyrd[claude]"

CHYRD needs Python 3.10 or newer. It runs on Windows, macOS, and Linux.

Provider keys

API keys are read from environment variables first, then from ~/.chyrd/config.json. You only need one to get started.

Set keys without touching the shell from inside the app with /keys (masked input, saved to your global config), or list every model and its readiness with chyrd models.

Quickstart

Set one provider key and launch:

$env:ANTHROPIC_API_KEY = "sk-..."
chyrd

export ANTHROPIC_API_KEY=sk-...
chyrd

That opens the TUI in the current directory. Point it elsewhere with chyrd path/to/project. No key at all? Run a local model with Ollama - it is keyless.

Permission modes

Cycle modes live with Shift+Tab. The status bar shows the active mode - terracotta in bypass, sage otherwise.

In the approval dialog you can choose allow once, always allow (persists a rule like shell(git *) for the session), or deny.

Keybindings

Slash commands

Type / in the composer to open the menu. Built-ins:

Every discovered skill is also a slash command - /commit, /review, /debug, and so on.

Skills

Skills are expert playbooks the agent (or you, via /name) can pull into context on demand. CHYRD ships fifteen built-ins:

Add your own under ~/.chyrd/skills/<name>/SKILL.md (global) or ./.chyrd/skills/<name>/SKILL.md (per project). Frontmatter is name, description, and an optional argument-hint; the markdown body is the playbook.

Subagents

The task tool runs focused work in a nested agent. Three are built in: explorer (read-only codebase scout), builder (full tools, one job), and reviewer (read-only, severity-ranked). Define your own as markdown files in .chyrd/agents/ (project) or ~/.chyrd/agents/ (global):

---
name: reviewer
description: Reviews code for bugs. Use after writing significant code.
tools: read_file, grep_files, glob_files       # optional; default = read-only set
model: anthropic/claude-sonnet-4-6             # optional; default = main model
---
You are a rigorous reviewer. Examine the relevant code without modifying it and
report findings ranked by severity, each with a path:line and a concrete fix.

A subagent inherits the active permission mode but has no interactive approver, so mutating subagents only act in accept-edits or bypass mode (or under an explicit allow rule).

Configuration

CHYRD reads ~/.chyrd/config.json (global) merged with ./.chyrd/config.json (project; project wins). A full example:

{
  "model": "anthropic/claude-opus-4-8",
  "theme": "chyrd-dark",
  "mode": "normal",
  "mascot": true,
  "max_tokens": 8192,
  "allow": [
    "shell(git *)",
    "shell(npm test)",
    "write(**)"
  ],
  "api_keys": {
    "openrouter": "sk-or-..."
  },
  "ollama_url": "http://localhost:11434",
  "providers": [
    {
      "id": "myllm",
      "label": "My Gateway",
      "base_url": "https://gateway.internal/v1",
      "api_key_env": "MYLLM_API_KEY",
      "models": [
        {
          "id": "house-large",
          "name": "House Large",
          "context_window": 128000,
          "tier": "flagship"
        }
      ]
    }
  ]
}

allow rules grant standing permission so those actions never prompt. providers declares any OpenAI-compatible endpoint - a self-hosted gateway, a proxy, a vendor not built in - and its models show up everywhere a built-in provider does. Prefer environment variables for secrets (api_key_env); inline api_key is also accepted.

Headless usage

chyrd run executes one prompt without the TUI and streams the answer to stdout, which makes it scriptable and CI-friendly.

chyrd run "summarize what this project does"
chyrd run "add type hints to utils.py" --model anthropic/claude-opus-4-8 --mode bypass
chyrd run "list the failing tests" --quiet > report.txt

• --model provider/model picks the model (default: configured or auto-resolved).
• --mode normal|accept-edits|plan|bypass sets the permission mode. There is no interactive approver in headless mode, so anything short of bypass or accept-edits auto-denies mutating actions; CHYRD prints a one-line warning.
• --max-turns N caps the agent loop. --quiet hides tool-activity lines.
• Tool activity is dimmed to stderr; the answer goes to stdout. Exit code is 0 on success, 1 on an error stop.

List the catalog at any time:

chyrd models
chyrd models --provider anthropic