chyrd 0.4.7

AI coding agent in your terminal: 34 providers, 169+ models (hundreds via live discovery), MCP servers, per-turn /undo, subagents, skills, permission modes, loop mode - and a mascot owl.

CHYRD

CHYRD (pronounced "chird" - it's a bird) is an AI coding agent that lives in your terminal, in the same genre as OpenCode, Gemini CLI, and Claude Code: a model works in your codebase through real tools - read, write, edit, move, copy, delete, shell, grep, glob, web search and fetch - inside an animated Textual TUI with a mascot owl that reacts to what the agent is doing.

The point of CHYRD is that it talks to whatever model you already have. 34 providers are built in: Anthropic, OpenAI, Google, OpenRouter, Vercel AI Gateway, Poe, Groq, DeepSeek, xAI, Mistral, Together, Fireworks, Moonshot, Cohere, Qwen, Z.AI, MiniMax, Perplexity, AI21, Inception, DeepInfra, Novita, Nebius, SiliconFlow, Hyperbolic, the free tiers of GitHub Models, Cerebras, NVIDIA, SambaNova, Hugging Face and Chutes, keyless local Ollama and LM Studio, and the Claude Agent SDK. 169+ models are catalogued - and with a key set, providers with a live listing endpoint (NVIDIA NIM, OpenRouter, Groq, Together, Fireworks, Cerebras) show their FULL current model lists, hundreds of models, fetched at startup. You can also add any OpenAI-compatible endpoint or MCP server in one config block.

What you get, concretely:

• four permission modes cycled live with Shift+Tab (normal / accept-edits / plan / bypass)
• per-turn checkpoints: /undo reverses the last turn's file changes, including deleted directories
• MCP: declare servers in config and their tools become CHYRD tools
• subagents (the task tool) and 15 skill playbooks, both plain markdown
• ! command runs shell yourself; the output lands in the model's context
• sessions saved as JSONL, resumable, exportable to markdown with /export
• headless chyrd run for scripts and CI; chyrd loop for unattended passes
• token use and cost in the status bar (a ~ estimate when a local server reports none), plus a context-fill meter

Claude Code is Anthropic-only, Gemini CLI is Google-only, OpenCode leans on a hosted layer. CHYRD is free, local-first, and provider-agnostic. No key at all? Point it at Ollama and it works.

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]"

From a source checkout: pip install -e . in the project root.

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

Quickstart

Set one provider key and launch:

set ANTHROPIC_API_KEY=sk-...        REM Windows (PowerShell: $env:ANTHROPIC_API_KEY="sk-...")
export ANTHROPIC_API_KEY=sk-...     # macOS / Linux
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 (see below). Type your request, press Enter, and watch the agent work.

Provider keys

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

Provider	Environment variable	Notes
Anthropic	ANTHROPIC_API_KEY	Claude Opus / Sonnet / Haiku
OpenAI	OPENAI_API_KEY	GPT family (incl. Codex models)
Google	GEMINI_API_KEY	Gemini
OpenRouter	OPENROUTER_API_KEY	One key, hundreds of models (incl. :free)
Vercel AI Gateway	AI_GATEWAY_API_KEY	One key, routes to many vendors
Poe	POE_API_KEY	Spends your Poe subscription points
Groq	GROQ_API_KEY	Very fast inference
DeepSeek	DEEPSEEK_API_KEY	DeepSeek chat / reasoner
xAI	XAI_API_KEY	Grok
Mistral	MISTRAL_API_KEY	Mistral / Codestral / Devstral / Magistral
Together	TOGETHER_API_KEY	Open-weight hosting
Fireworks	FIREWORKS_API_KEY	Open-weight hosting
Moonshot	MOONSHOT_API_KEY	Kimi
Cohere	COHERE_API_KEY	Command family
Qwen	DASHSCOPE_API_KEY	Qwen via Alibaba DashScope
Z.AI	ZAI_API_KEY	GLM family (Flash tier is free)
MiniMax	MINIMAX_API_KEY	MiniMax M-series
Perplexity	PERPLEXITY_API_KEY	Sonar - answers with live web search
AI21	AI21_API_KEY	Jamba family
Inception	INCEPTION_API_KEY	Mercury diffusion LLMs (very fast)
DeepInfra	DEEPINFRA_API_KEY	Open-weight hosting
Novita	NOVITA_API_KEY	Open-weight hosting
Nebius	NEBIUS_API_KEY	Open-weight hosting
SiliconFlow	SILICONFLOW_API_KEY	Open-weight hosting
Hyperbolic	HYPERBOLIC_API_KEY	Open-weight hosting
GitHub Models	GITHUB_TOKEN	Free with a GitHub account (rate-limited)
Cerebras	CEREBRAS_API_KEY	Free tier, wafer-scale speed
NVIDIA NIM	NVIDIA_API_KEY	Free credits
SambaNova	SAMBANOVA_API_KEY	Free tier
Hugging Face	HF_TOKEN	Inference router; free monthly credits
Chutes	CHUTES_API_KEY	Decentralized; free tier
Ollama	none (keyless)	Local; serve on localhost:11434
LM Studio	none (keyless)	Local; serve on localhost:1234
Claude (SDK)	ANTHROPIC_API_KEY	Install chyrd[claude] (Agent SDK backend)

The Claude Agent SDK backend runs the bundled Claude Code engine through the claude-agent-sdk extra (auth with ANTHROPIC_API_KEY, or Bedrock/Vertex env flags). Its models appear as claude-agent/opus, claude-agent/sonnet, and claude-agent/haiku. Honest caveat: it is a chat-only backend - CHYRD's own tools are disabled while it drives the session. If the SDK is not installed, the backend reports itself unavailable and the rest of CHYRD is unaffected.

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.

Permission modes

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

Mode	Behavior
normal	Ask before every mutating action (write, edit, shell, fetch).
accept-edits	File writes and edits auto-approved; shell and fetch still ask.
plan	Read-only. Mutating tools are refused with guidance; present a plan.
bypass	Everything auto-approved. Move fast; nothing prompts.

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

Undo

Every file mutation in a turn - write, edit, move, copy, delete, even a deleted directory - is journaled to ~/.chyrd/checkpoints/ before it happens. /undo reverses the most recent turn: prior bytes are restored, created files are removed, moves are moved back. Up to 20 turns deep, and the model is told what was reverted so it does not trust stale edits.

Keybindings

Key	Action
Enter	Submit the message
Shift+Enter	Newline in the composer
Up / Down	Browse input history (at the buffer edge)
/	Open the slash-command and skill menu
@	File-path autocomplete
Tab	Accept the highlighted suggestion
Shift+Tab	Cycle permission mode
Ctrl+M	Open the model picker
Ctrl+N	New session
Ctrl+P	Command palette
Ctrl+T	Next theme
Esc	Interrupt the turn (press twice to force-stop)
! cmd	Run a shell command directly - no model in the loop
F1	Help
Ctrl+C	Quit (press twice)

Slash commands

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

/help        keys and commands            /skills      list available skills
/model [ref] picker, or set directly      /agents      list subagents
/mode        cycle permission mode        /init        generate a CHYRD.md brief
/theme       switch theme                 /keys        set a provider API key
/new         start a fresh session        /mascot      toggle the mascot owl
/sessions    browse and resume            /compact     summarize older context
/resume      resume the most recent       /cost        show usage and spend
/clear       clear the conversation       /loop [n]    keep improving the project
/undo        revert last turn's files     /stop        end a running loop
/export      transcript to markdown       /mcp         list MCP servers + tools
/exit        quit CHYRD

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:

3d-model     Three.js scenes, procedural meshes, Blender bpy scripts
ai-app       LLM app patterns: streaming, tool use, caching, evals
image-gen    Stable Diffusion / ComfyUI / API image generation options
website      Next.js + Tailwind ship checklist
game-dev     game loop / ECS / collision basics plus Roblox Luau notes
commit       conventional-commit workflow
review       severity-ranked code review method
init         generate a CHYRD.md project brief
debug        scientific debugging
refactor     safe, incremental refactoring
test         the test pyramid plus table-driven tests
docs         documentation that stays true
data-viz     terminal braille charts and matplotlib
deploy       Vercel / Docker / systemd shipping
security     OWASP quick audit

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).

MCP servers

Declare any MCP server in config and every tool it advertises becomes a CHYRD tool, gated by the same permission system:

"mcp_servers": [
  {"name": "fs", "command": "npx",
   "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]}
]

Tools appear as fs__read_file, fs__write_file, and so on; /mcp lists what connected. The transport is stdio JSON-RPC. A server that fails to start is reported on a card and skipped - it never blocks the app.

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",
  "mcp_servers": [
    {
      "name": "fs",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  ],
  "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 so you are never surprised.
• --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.

Loop mode

chyrd loop runs unattended and keeps working on your project - one focused change per iteration (the prompt requires it to verify before finishing), until you stop it.

chyrd loop                          pick the highest-impact improvement, repeat
chyrd loop "tighten the test suite" --interval 5m --max-iterations 10
chyrd loop --model groq/llama-3.3-70b-versatile --mode bypass

• With no prompt it surveys the codebase and makes one concrete improvement each pass (bug fix, missing test, rough edge, doc gap, cleanup), then verifies it.
• --interval pauses between passes (30s, 5m, 1h; default back-to-back).
• --max-iterations N stops after N passes (default: until Ctrl+C).
• Defaults to bypass since it is unattended; it halts itself after three failed passes so a bad key never spins. In the TUI, /loop [n] does the same and /stop (or Esc) ends it.

Closed-source binary

Ship CHYRD without the source. python build/build.py produces a standalone chyrd executable (PyInstaller + optimized bytecode; --obfuscate adds PyArmor). See build/README.md for the honest scope of what that protects and how to harden further.

List the catalog at any time:

chyrd models
chyrd models --provider anthropic

Website

Project site and docs: https://chyrd.online

License

Free to install and use; closed source - no redistribution or derivative works. See LICENSE.