Metadata-Version: 2.4
Name: chyrd
Version: 0.4.2
Summary: AI coding agent in your terminal: 34 providers, 159 models, MCP servers, per-turn /undo, subagents, skills, permission modes, loop mode - and a mascot owl.
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, 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. 159 models are catalogued, and you can 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):

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

## MCP servers

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

```json
"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:

```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",
  "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
```

## License

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