{"_id":"@almightosan/xyro","name":"@almightosan/xyro","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@almightosan/xyro","version":"0.1.0","description":"XYRO — a terminal-native AI coding agent built from scratch","type":"module","bin":{"xyro":"dist/index.js"},"scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js"},"dependencies":{"@clack/prompts":"^0.9.0","commander":"^12.0.0","gradient-string":"^3.0.0","openai":"^4.80.0","picocolors":"^1.1.0"},"devDependencies":{"@types/gradient-string":"^1.1.6","@types/node":"^22.0.0","tsx":"^4.19.0","typescript":"^5.7.0"},"gitHead":"f535e32774289389cf3a18e2284c0b45edec60ed","_id":"@almightosan/xyro@0.1.0","_nodeVersion":"20.20.2","_npmVersion":"11.16.0","dist":{"integrity":"sha512-5FSeUi80yLMoAJ35j5NkXnvuv5ifMEfxJmg9+1oCC8VSthSGgMt63iM2La7/6+PnN2M9LB8HxVVQ4WnDV30SpA==","shasum":"7f00edd637a14f159be3b5b37f234dcf5202c9d4","tarball":"https://registry.npmjs.org/@almightosan/xyro/-/xyro-0.1.0.tgz","fileCount":38,"unpackedSize":112586,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA8FMK48SPptZxDP8Dvshy8dK9jVOrcwPhJd+C0ELLq0AiEArd1srPye0vDbt3wSxCk+bcMzNH/BBfQ33CJ9kbnaI0A="}]},"_npmUser":{"name":"almightosan","email":"josiasaaron38@gmail.com"},"directories":{},"maintainers":[{"name":"almightosan","email":"josiasaaron38@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xyro_0.1.0_1783679326893_0.4626004154620884"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-10T10:28:46.730Z","0.1.0":"2026-07-10T10:28:47.036Z","modified":"2026-07-10T10:28:47.216Z"},"maintainers":[{"name":"almightosan","email":"josiasaaron38@gmail.com"}],"description":"XYRO — a terminal-native AI coding agent built from scratch","readme":"<div align=\"center\">\n\n```\n██╗  ██╗██╗   ██╗██████╗  ██████╗\n╚██╗██╔╝╚██╗ ██╔╝██╔══██╗██╔═══██╗\n ╚███╔╝  ╚████╔╝ ██║  ██║██║   ██║\n ██╔██╗   ╚██╔╝  ██║  ██║██║   ██║\n██╔╝ ██╗   ██║   ██████╔╝╚██████╔╝\n╚═╝  ╚═╝   ╚═╝   ╚═════╝  ╚═════╝\n```\n\n<br>\n\n<p>terminal-native ai coding agent  ◆  built from scratch  ◆  no dependencies beyond what you see</p>\n\n<br>\n\n<a href=\"#features\">Features</a> ◆ <a href=\"#quickstart\">Quickstart</a> ◆ <a href=\"#usage\">Usage</a> ◆ <a href=\"#architecture\">Architecture</a> ◆ <a href=\"#roadmap\">Roadmap</a> ◆ <a href=\"#gaps\">Known Gaps</a>\n\n<br>\n\n</div>\n\n---\n\n## ◆ What is XYRO?\n\n**XYRO** is a terminal-native AI coding agent written in TypeScript from scratch. It operates as an interactive CLI that connects to OpenAI-compatible LLM providers (OpenAI, Groq, OpenRouter, DeepSeek, and others) and helps you navigate, analyze, understand, and modify codebases — all without leaving your terminal.\n\nUnlike most AI coding tools that require a VS Code extension, a web dashboard, or proprietary infrastructure, XYRO is a single binary that runs wherever Node.js runs. It uses the **model context protocol (MCP)** pattern: the LLM drives the session, calls tools (file read, file write, shell commands, code search), and XYRO executes them locally.\n\n---\n\n## ✦ Features\n\n| Icon | Area | Description |\n|------|------|-------------|\n| ◆ | **Provider-Agnostic** | Works with OpenAI, Groq, OpenRouter, DeepSeek, or any OpenAI-compatible API |\n| ▸ | **Persistent Sessions** | Auto-saves conversation history; resume with `--resume` |\n| ● | **Tool System** | Filesystem read/write, shell execution, code search, glob matching |\n| ⚡ | **Interactive Prompts** | Rich terminal UI via clack prompts, gradient banners, colored output |\n| ★ | **Config Persistence** | Remembers your provider, model, and API key across sessions |\n| ❖ | **No-Banner Mode** | Headless/JSON output for CI pipelines and scripting |\n| ◈ | **Free-Tier Friendly** | Built-in provider presets for Groq, OpenRouter, DeepSeek free tiers |\n| ▣ | **Error Handling** | Granular API error formatting per provider (auth, rate-limit, model-not-found) |\n\n---\n\n## ⚡ Quickstart\n\n```bash\n# Install globally\nnpm install -g xyro\n\n# Or run directly\nnpx xyro\n\n# First run walks you through setup\nxyro\n```\n\n### Environment\n\n```\nOPENAI_API_KEY=sk-...           # default for any provider\nXYRO_NO_BANNER=1                # suppress the ASCII banner\n```\n\n### Provider presets\n\n```bash\n# Use a specific provider\nxyro --provider groq\nxyro --provider openrouter --model openai/gpt-4o\nxyro --provider deepseek\n\n# Full manual config\nxyro --api-key sk-... --base-url https://api.example.com/v1 --model gpt-4o\n```\n\n---\n\n## ◆ Usage\n\n```\nUsage: xyro [options]\n\nOptions:\n  --api-key <key>          API key\n  -m, --model <model>      LLM model\n  --base-url <url>         OpenAI-compatible base URL\n  --provider <id>          Provider ID (groq, openrouter, deepseek)\n  --max-tool-calls <n>     Max tool calls per turn (default: 25)\n  --resume                 Resume previous conversation\n  --no-banner              Skip interactive setup and banner\n  --json                   JSON output mode (skips banner)\n  -V, --version            output the version number\n  -h, --help               display help for command\n```\n\n### Interactive Commands\n\n| Command | Action |\n|---------|--------|\n| `exit` / `quit` | Save and exit |\n| `clear` | Reset conversation history |\n| `resume` | Reload last session |\n\n---\n\n## ▸ Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                     XYRO CLI                        │\n│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │\n│  │ commander │  │  clack   │  │  gradient-string │  │\n│  │ (args)    │  │(prompts) │  │  (banners)       │  │\n│  └────┬─────┘  └────┬─────┘  └────────┬─────────┘  │\n│       │             │                  │            │\n│  ┌────▼─────────────▼──────────────────▼─────────┐  │\n│  │              Agent Loop                        │  │\n│  │  ┌──────────┐  ┌──────────┐  ┌─────────────┐  │  │\n│  │  │   LLM    │  │  Tools   │  │  History     │  │  │\n│  │  │ Provider │──│ Registry │──│  Persistance │  │  │\n│  │  └──────────┘  └──────────┘  └─────────────┘  │  │\n│  └────────────────────────────────────────────────┘  │\n│                                                       │\n│  ┌─────────────────────────────────────────────────┐  │\n│  │  Tools                                          │  │\n│  │  read ├── write ├── shell ├── search ├── glob   │  │\n│  └─────────────────────────────────────────────────┘  │\n└─────────────────────────────────────────────────────┘\n```\n\n### Core Loop\n\n1. **CLI** parses arguments and reads persisted config (provider, model, key)\n2. **Agent Loop** creates an OpenAI-compatible client and enters the interaction loop\n3. **User input** is sent to the LLM alongside tool definitions\n4. **LLM responds** with text or tool call requests\n5. **Tool Registry** dispatches calls to filesystem/shell/search operations\n6. **Results** are fed back to the LLM for the next turn\n7. **History** is saved on exit for `--resume`\n\n### Tool System\n\n| Tool | Capability |\n|------|-----------|\n| `read` | Read file contents with line numbers |\n| `write` | Write or overwrite files |\n| `shell` | Execute shell commands with timeout |\n| `search` | Regex/grep file contents |\n| `glob` | Pattern-based file discovery |\n\n---\n\n## ● Stack\n\n```\nRuntime     ◆  Node.js / TypeScript / ES2022\nCLI         ◆  commander\nPrompts     ◆  @clack/prompts\nTerminal    ◆  picocolors + gradient-string\nAI API      ◆  openai SDK (OpenAI-compatible)\nBuild       ◆  TypeScript compiler (tsc)\nDev runner  ◆  tsx\n```\n\n---\n\n## ❖ Known Gaps & Roadmap\n\nXYRO is in early development. Here is what it does not yet have, in rough priority order:\n\n| Area | Gap | Status |\n|------|-----|--------|\n| ◈ | **Multi-file edits** — single-file writes only, no diff/patch | Planned |\n| ▣ | **Diff preview** — no staged review of changes before apply | Planned |\n| ⚡ | **Cost tracking** — no per-session token/cost meter | Planned |\n| ▸ | **Git integration** — no automatic commits or branch management | Planned |\n| ◆ | **Context window management** — no summarization or sliding window | Planned |\n| ● | **Plugin system** — tools are hard-coded, not extensible at runtime | Future |\n| ❖ | **File watching** — no `--watch` mode for continuous feedback | Future |\n| ★ | **Config profiles** — single saved config only | Future |\n| ▣ | **Streaming output** — blocks until full LLM response | Future |\n| ◈ | **Test runner** — no built-in test execution harness | Future |\n| ▣ | **Self-hosted docs** — no `xyro --help` beyond commander output | Future |\n| ⚡ | **Multi-turn planning** — no explicit plan/approve step before execution | Future |\n\n---\n\n## ✦ Development\n\n```bash\n# Clone\ngit clone git@github.com:CYBERCLAN237/Xyro-Cli.git\ncd xyro\n\n# Install\nnpm install\n\n# Dev (runs via tsx)\nnpm run dev\n\n# Build\nnpm run build\n\n# Run built version\nnpm start\n```\n\n---\n\n## ▸ License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n<div align=\"center\">\n<br>\n<p>\n  <sub>\n  built from scratch with TypeScript  ◆  by CYBERCLAN237  ◆  icon set: unicode geometric shapes\n  </sub>\n</p>\n<br>\n</div>\n","readmeFilename":"README.md","_rev":"1-6a832d38910c4a187c49d7bd9fd6bd76"}