Zephyr

Your AI terminal agent for understanding, editing, and shipping code.

Zephyr is a cross-platform AI coding agent that runs in your terminal. Connect it to your preferred AI model (OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, or local models via Ollama) and get an intelligent coding assistant that understands your project folder.

Features

• Agentic code assistance — explain code, find bugs, refactor, write tests, generate docs, and more
• Workspace-aware — Zephyr treats your current folder as its workspace, reading files and understanding project structure
• Multi-provider — works with OpenAI, Anthropic Claude, Google Gemini, DeepSeek, OpenRouter, Ollama (local), or any OpenAI-compatible API
• Tool system — read, write, edit, search files, run commands, and check git status — all from natural language
• Safety first — never edits files or runs destructive commands without confirmation
• Beautiful terminal UI — modern, clean, fast, streaming responses
• Cross-platform — Windows, macOS, Linux

Installation

npm (global)

npm install -g @yasith-perera/zephyr-ai

npx (no install)

npx @yasith-perera/zephyr-ai

macOS / Linux (curl)

curl -fsSL https://zephyr-ai.dev/install.sh | sh

Windows (PowerShell)

iex "& { $(irm https://zephyr-ai.dev/install.ps1) }"

Quick Start

1. Configure

zephyr login

Follow the prompts to choose your AI provider and enter your API key.

2. Start a chat

cd your-project
zephyr

Zephyr will analyze your project and start an interactive session.

3. Ask questions

zephyr ask "explain this project"
zephyr ask "find the bug in src/main.ts"
zephyr ask "write tests for the auth module"

Commands

| Command | Description | |---------|-------------| | zephyr | Start interactive chat in the current folder | | zephyr ask <question> | One-shot question mode | | zephyr init | Create project-level .zephyr.json config | | zephyr login | Set up API key and provider | | zephyr logout | Remove saved credentials | | zephyr config show | View config (safe — no raw keys) | | zephyr config set-provider | Change AI provider | | zephyr config set-model | Change model | | zephyr config path | Show config file location | | zephyr models | List available models | | zephyr doctor | System diagnostics | | zephyr update | Update instructions | | zephyr --version | Show version | | zephyr --help | Show help |

Interactive Chat Commands

When in interactive mode (zephyr):

| Command | Description | |---------|-------------| | /help | Show available commands | | /clear | Clear conversation | | /context | Show workspace context | | /tools | List available tools | | /config | Show current config | | /models | Show current model info | | /exit or /quit | Exit Zephyr |

Environment Variables

Zephyr respects these environment variables (they take precedence over saved config):

| Variable | Description | |----------|-------------| | ZEPHYR_API_KEY | API key for your provider | | ZEPHYR_PROVIDER | Provider type (openai, anthropic, gemini, etc.) | | ZEPHYR_MODEL | Model name | | ZEPHYR_BASE_URL | Custom API base URL |

Project Quality

• Clean folder structure
• TypeScript throughout
• Error handling
• Configuration validation
• Security checks (path traversal protection, sensitive file detection)
• Extensible provider architecture
• Open source (MIT)

Available Tools

Zephyr's agent can use these tools to help you:

• list_files — browse project structure
• read_file — inspect file contents
• write_file — create or overwrite files (requires approval)
• edit_file — search-and-replace edits (requires approval)
• search_files — grep across the project
• run_command — execute shell commands (requires approval for destructive ones)
• get_git_status — check git state

Architecture

src/
├── index.ts          # Entry point
├── cli.ts            # CLI command definitions (Commander)
├── types/            # TypeScript type definitions
├── config/           # Configuration store & schema
├── providers/        # AI provider adapters
│   ├── base.ts       # Base provider abstract class
│   ├── openai.ts     # OpenAI-compatible API
│   ├── anthropic.ts  # Anthropic Claude
│   ├── gemini.ts     # Google Gemini
│   ├── deepseek.ts   # DeepSeek
│   ├── openrouter.ts # OpenRouter
│   ├── ollama.ts     # Ollama (local)
│   └── custom.ts     # Custom OpenAI-compatible endpoint
├── tools/            # Agent tool implementations
├── ui/               # Terminal UI components
├── chat/             # Chat loop & session management
├── commands/         # CLI command handlers
└── utils/            # Utilities (security, workspace, errors)

Provider Support

| Provider | Streaming | Tools | Status | |----------|-----------|-------|--------| | OpenAI (GPT-4, etc.) | ✓ | ✓ | Active | | Anthropic Claude | ✓ | ✓ | Active | | Google Gemini | ✓ | ✗ | Active | | DeepSeek | ✓ | ✗ | Active | | OpenRouter | ✓ | ✓ | Active | | Ollama (local) | ✓ | ✗ | Active | | Custom API | ✓ | ✓ | Active | | Zephyr native (future) | — | — | Planned |

Security

• Zephyr never accesses files outside your workspace
• API keys are stored in ~/.zephyr/config.json with restricted permissions
• File writes and destructive commands always require user confirmation
• Sensitive files (.env, credentials, keys) are not readable by the agent
• Environment variables take precedence over stored config

Development

# Clone and install
git clone https://github.com/zephyr-ai/zephyr.git
cd zephyr
npm install

# Development mode
npm run dev

# Build
npm run build

# Lint
npm run lint

# Test
npm run test

Roadmap

• [ ] Built-in update command
• [ ] Session history and resumption
• [ ] Custom Zephyr model (zephyr-1, zephyr-coder)
• [ ] Plugin system for custom tools
• [ ] Multi-turn editing workflows
• [ ] IDE integrations (VS Code, JetBrains)
• [ ] Team/CI mode for automated code review
• [ ] Standalone binaries (no Node required)

License

MIT

Built with determination. Zephyr connects to your preferred AI models today, with a future-ready architecture for native Zephyr models.