chyrd 0.4.0__tar.gz

chyrd-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mazen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chyrd-0.4.0/PKG-INFO

@@ -0,0 +1,352 @@
+Metadata-Version: 2.4
+Name: chyrd
+Version: 0.4.0
+Summary: CHYRD - the bird-fast AI coding agent that lives in your terminal. Every model, every provider, one beautiful TUI.
+Author: Mazen
+License: MIT
+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 :: OSI Approved :: MIT 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 and
+closed, Gemini CLI is Google-only, OpenCode leans on a hosted layer -
+CHYRD is open, 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
+
+MIT. See [LICENSE](LICENSE).