Metadata-Version: 2.4
Name: chyrd
Version: 0.4.1
Summary: CHYRD - the bird-fast AI coding agent that lives in your terminal. Every model, every provider, one beautiful TUI.
Author: Mazen
License: Proprietary - free to use, no redistribution (see LICENSE)
Keywords: ai,coding-agent,tui,terminal,llm,claude,openai,gemini,mcp,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.0
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.1.0; extra == "claude"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == "build"
Dynamic: license-file

# CHYRD

CHYRD (pronounced "chird" - it's a bird) is an AI coding agent that lives in
your terminal. It is the same genre as OpenCode, Gemini CLI, and Claude Code:
a model talks to your code through real tools - read, write, edit, shell, grep,
web search - inside a fast, animated TUI. What sets CHYRD apart is breadth and
craft in one package: it speaks to *every* model and provider - 30+ built in
(Anthropic, OpenAI, Google, OpenRouter, Groq, DeepSeek, xAI, Mistral, Together,
Fireworks, Moonshot, Cohere, Qwen, Z.AI/GLM, MiniMax, Perplexity, AI21,
Inception, Vercel AI Gateway, Poe, DeepInfra, Novita, Nebius, SiliconFlow,
Hyperbolic, plus the free tiers of GitHub Models, Cerebras, NVIDIA, SambaNova,
Hugging Face and Chutes, keyless local Ollama and LM Studio, and your own
OpenAI-compatible endpoints - 150+ catalogued models in all), it carries
Claude-Code-grade permission modes you cycle on the fly,
it ships subagents, a real skills library, web search, and session persistence,
and it does all of it behind a living terminal interface with a mascot bird that
reacts to what the agent is doing. One tool, every backend, no lock-in.

Where the alternatives each pick a lane - Claude Code is Anthropic-only,
Gemini CLI is Google-only, OpenCode leans on a hosted layer -
CHYRD is free, local-first, and provider-agnostic by design. Bring whichever
key you already have, or no key at all and a local model, and get the same
agent loop, the same modes, the same skills.

## 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`. If the SDK is not installed, that backend simply 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**.

## 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 running turn                          |
| F1 or `?`      | 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       open the model picker        /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 bird
/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
/exit        quit CHYRD                    /stop        end a running loop
```

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

```markdown
---
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:

```json
{
  "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 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 improving your project - one focused,
verified change per iteration, 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.dev

## License

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