Xyro-Cli

      ___           ___           ___           ___     
     |\__\         |\__\         /\  \         /\  \    
     |:|  |        |:|  |       /::\  \       /::\  \   
     |:|  |        |:|  |      /:/\:\  \     /:/\:\  \  
     |:|__|__      |:|__|__   /::\~\:\  \   /:/  \:\  \ 
 ____/::::\__\     /::::\__\ /:/\:\ \:\__\ /:/__/ \:\__\
 \::::/~~/~       /:/~~/~    \/_|::\/:/  / \:\  \ /:/  /
  ~~|:|~~|       /:/  /         |:|::/  /   \:\  /:/  / 
    |:|  |       \/__/          |:|\/__/     \:\/:/  /  
    |:|  |                      |:|  |        \::/  /   
 \|__|                       \|__|         \/__/

◆ Built with XYRO

Built with XYRO — terminal-native AI coding agent (xyberclan.dev)

◆ What is XYRO?

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.

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

✦ Features

⚡ Quickstart

# Install globally
npm install -g xyro-cli

# Or run directly
npx xyro-cli

# First run walks you through setup
xyro

Environment

OPENAI_API_KEY=sk-...           # default for any provider
XYRO_NO_BANNER=1                # suppress the ASCII banner

Provider presets

# Use a specific provider
xyro --provider groq
xyro --provider openrouter --model openai/gpt-4o
xyro --provider deepseek

# Full manual config
xyro --api-key sk-... --base-url https://api.example.com/v1 --model gpt-4o

◆ Usage

Usage: xyro [options]

Options:
  --api-key <key>          API key
  -m, --model <model>      LLM model
  --base-url <url>         OpenAI-compatible base URL
  --provider <id>          Provider ID (groq, openrouter, deepseek)
  --max-tool-calls <n>     Max tool calls per turn (default: 25)
  --resume                 Resume previous conversation
  --no-banner              Skip interactive setup and banner
  --json                   JSON output mode (skips banner)
  -V, --version            output the version number
  -h, --help               display help for command

Interactive Commands

▸ Architecture

┌─────────────────────────────────────────────────────┐
│                     XYRO CLI                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ commander │  │  clack   │  │  gradient-string │  │
│  │ (args)    │  │(prompts) │  │  (banners)       │  │
│  └────┬─────┘  └────┬─────┘  └────────┬─────────┘  │
│       │             │                  │            │
│  ┌────▼─────────────▼──────────────────▼─────────┐  │
│  │              Agent Loop                        │  │
│  │  ┌──────────┐  ┌──────────┐  ┌─────────────┐  │  │
│  │  │   LLM    │  │  Tools   │  │  History     │  │  │
│  │  │ Provider │──│ Registry │──│  Persistance │  │  │
│  │  └──────────┘  └──────────┘  └─────────────┘  │  │
│  └────────────────────────────────────────────────┘  │
│                                                       │
│  ┌─────────────────────────────────────────────────┐  │
│  │  Tools                                          │  │
│  │  read ├── write ├── shell ├── search ├── glob   │  │
│  └─────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Core Loop

1. CLI parses arguments and reads persisted config (provider, model, key)
2. Agent Loop creates an OpenAI-compatible client and enters the interaction loop
3. User input is sent to the LLM alongside tool definitions
4. LLM responds with text or tool call requests
5. Tool Registry dispatches calls to filesystem/shell/search operations
6. Results are fed back to the LLM for the next turn
7. History is saved on exit for --resume

Tool System

● Stack

Runtime     ◆  Node.js / TypeScript / ES2022
CLI         ◆  commander
Prompts     ◆  @clack/prompts
Terminal    ◆  picocolors + gradient-string
AI API      ◆  openai SDK (OpenAI-compatible)
Build       ◆  TypeScript compiler (tsc)
Dev runner  ◆  tsx

❖ Known Gaps & Roadmap

XYRO is in early development. Here is what it does not yet have, in rough priority order:

✦ Development

# Clone
git clone [email protected]:CYBERCLAN237/Xyro-Cli.git
cd xyro

# Install
npm install

# Dev (runs via tsx)
npm run dev

# Build
npm run build

# Run built version
npm start

▸ Releasing to npm

Releases are automated via GitHub Actions (.github/workflows/publish.yml). Pushing a v* tag triggers npm publish:

# 1. Bump version in package.json first, commit
npm version patch   # or minor / major — this commits and tags for you

# 2. Push the tag
git push --follow-tags
# GitHub Actions now: installs → builds → verifies tag == package.json version → publishes

The workflow requires an NPM_TOKEN secret in the repo (Settings → Secrets → Actions). Use a granular access token with "Read and write" packages permission, and 2FA bypass enabled for automation.

✦ Updating

XYRO checks npm for a newer release in the background (at most every 12 hours, never blocking start-up). When one exists, the home screen and the status rail say so — type /update to install it without leaving XYRO, then restart.

/update                         # inside XYRO
npm install -g xyro-cli@latest  # or from your shell
XYRO_NO_UPDATE_CHECK=1 xyro     # opt out of the background check

✦ Releasing

Releases are cut by CI — no local publishing needed.

Automatic (default): every push to main that users would notice is published by auto-release.yml. The commit messages decide the version: feat: → minor, fix:/perf:/revert: → patch, type!: or BREAKING CHANGE → major (minor while on 0.x). Pushes that only change docs, chores, tests or CI publish nothing. Add [release] to a commit message to force a patch release, or [skip release] to skip one. Users see a "New version" pop-up with what's new the next time they start XYRO.

Manual:

1. Actions → Release → Run workflow, pick patch, minor, major or prerelease (or run npm run release, npm run release:minor, npm run release:major with the GitHub CLI).
2. The workflow typechecks, builds, runs the tests, bumps package.json, tags vX.Y.Z, publishes to npm with provenance, and creates a GitHub Release with generated notes.
3. Pre-releases publish to the next dist-tag, so npm install -g xyro-cli stays on stable.

Pushing a v* tag manually (npm version patch && git push --follow-tags) runs the same gate through publish.yml, and skips versions already on npm.

One-time setup: add an npm automation token as the NPM_TOKEN repository secret, and allow GitHub Actions to push to main (or exempt github-actions[bot] from branch protection).

▸ License

MIT — see LICENSE