Metadata-Version: 2.4
Name: zeer
Version: 0.2.3
Summary: Agentic AI CLI with tool calling and extensible skills system
Author-email: M Aliyan <mahunxai@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/muhdaliyan/zeer
Project-URL: Documentation, https://github.com/muhdaliyan/zeer#readme
Project-URL: Repository, https://github.com/muhdaliyan/zeer
Project-URL: Issues, https://github.com/muhdaliyan/zeer
Keywords: ai,agent,cli,tool-calling,agentic,openai,gemini,claude,agentskills
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: inquirer>=3.1.3
Requires-Dist: colorama>=0.4.6
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: ollama>=0.1.0
Dynamic: license-file

# Zeer

[![PyPI version](https://img.shields.io/pypi/v/zeer?color=blue&label=pypi)](https://pypi.org/project/zeer/)
[![Python](https://img.shields.io/pypi/pyversions/zeer?color=blue)](https://pypi.org/project/zeer/)
[![License](https://img.shields.io/github/license/muhdaliyan/zeer?color=green)](https://github.com/muhdaliyan/zeer/blob/main/LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Downloads](https://img.shields.io/pypi/dm/zeer?color=blue)](https://pypi.org/project/zeer/)
[![GitHub stars](https://img.shields.io/github/stars/muhdaliyan/zeer?style=social)](https://github.com/muhdaliyan/zeer)

**Zeer** is an OpenSource agentic AI CLI that connects to multiple providers (OpenAI, Gemini, Claude, Ollama) with **tool-calling capabilities** and an **extensible skills system**.  

Think of it as **Claude Code for the terminal**, provider-agnostic and developer-friendly.

<img src="https://i.ibb.co/sxRF8qQ/image.png" alt="image" border="0">

---

## 🎯 Why Zeer?

Tools like Claude Code, Kiro, and Cursor are powerful but come with limitations:

* **Subscription Required** – Monthly fees for access
* **Fixed Models** – Locked into specific AI providers
* **Closed Source** – Limited customization options

**Zeer is different:**

* ✅ **Use Your Own API Keys** – Pay only for what you use, no subscriptions
* ✅ **Multi-Provider Support** – Switch between OpenAI, Gemini, Claude, Ollama, or add your own
* ✅ **Local AI Support** – Run models locally with Ollama (no API key required)
* ✅ **100% Open Source** – Customize, extend, and contribute freely
* ✅ **Extensible Skills System** – Create custom agent behaviors without code changes
* ✅ **Background Process Management** – Start and manage dev servers in the background
* ✅ **Terminal-First** – Lightweight, fast, and integrates with your workflow

> **Note:** Zeer is currently in beta. We appreciate your contributions and feedback as we continue to improve. This project will always remain open source.

---

## 🚀 Get Started

Start using Zeer quickly with the following installation options.

### **For Users (PyPI)**

```bash
pip install zeer
```

### **For Developers (Local / Editable)**

```bash
# Clone the repository
git clone https://github.com/muhdaliyan/zeer.git
cd zeer

# Install dependencies
pip install -r requirements.txt

# Install in editable mode
pip install -e .

# Run Zeer
zeer
```

> Any code changes will reflect immediately without reinstalling.

---

## 🎯 Quick Start

```bash
zeer
```

1. Select your AI provider
2. Enter your API key
3. Choose a model
4. Start chatting and using AI tools

---

## 💻 Usage Examples

```bash
# AI automatically executes tasks
> create a PDF report about machine learning
> list all Python files in this directory
> set up a new React project structure
> read and summarize config.json

# Start dev servers in background
> start a React dev server on port 3000
> run the Flask app in the background

# Commands
/skills    # View available skills
/tools     # View available tools
/processes # View running background processes
/clear     # Clear conversation
/providers # Switch provider
/models    # Switch model
```

---

## 🤖 AI Providers

Zeer supports multiple AI providers:

### Cloud Providers (API Key Required)
* **OpenAI** – GPT-4, GPT-3.5, and more
* **Gemini** – Google's AI models
* **Claude** – Anthropic's Claude models
* **Ollama Cloud** – Cloud-hosted Ollama models

### Local Provider (No API Key)
* **Ollama Local** – Run AI models entirely on your machine
  * No internet required
  * No API costs
  * Full privacy
  * See [OLLAMA_SETUP.md](OLLAMA_SETUP.md) for setup guide

---

## 🚀 Ollama Quick Start

Want to run AI locally without API keys?

1. Install Ollama from [ollama.ai](https://ollama.ai)
2. Pull a model: `ollama pull llama3.2`
3. Start Zeer: `zeer`
4. Select "Ollama" provider
5. Press Enter (skip API key for local)
6. Choose your model and start chatting

See [OLLAMA_SETUP.md](OLLAMA_SETUP.md) for detailed setup instructions.

---

## 🔄 Background Process Management

Zeer can start and manage development servers in the background:

```bash
# AI automatically detects and manages servers
> start a Next.js dev server
> run the Django development server
> start the Express API on port 8080

# View running processes
/processes

# AI can stop processes when needed
> stop the React dev server
```

Features:
* Automatic URL detection
* Output monitoring
* Clean process termination
* Multiple concurrent servers

---

## 🔧 Built-in Skills

* **pdf-builder** – Generate PDF documents with reportlab
* **code-helper** – Project setup & code organization
* **file-operations** – File system operations
* **text-processing** – Text manipulation & analysis
* **frontend-designer** – Frontend development assistance

---

## ✨ Creating Custom Skills

1. Create `skills/your-skill/SKILL.md`:

```markdown
---
name: your-skill
description: What this skill does and when to use it
allowed-tools: create_file read_file run_code
---

## Goal
Your skill's purpose

## Procedure
Step-by-step instructions for the AI

## Examples
Usage examples
```

2. Restart Zeer – skills are auto-discovered.

See [SKILLS_IMPLEMENTATION.md](SKILLS_IMPLEMENTATION.md) for advanced details.

---

## 🏗️ Architecture

```
zeer/
├── src/
│   ├── providers/          # AI provider implementations
│   ├── tools.py            # Tool registry & execution
│   ├── skills_manager.py   # Skills loading & validation
│   └── chat_session.py     # Context management
└── skills/                 # Modular agent skills
    ├── backend-developer/
    │   ├── SKILL.md        # Skill definition
    │   ├── scripts/        # Executable Python scripts
    |   |   └── script.py
    │   └── references/     # Additional documentation
    ├── code-helper/
    │   └── SKILL.md
    ├── file-operations/
    │   └── SKILL.md
    └── ...
```

---

## 🔄 Tool Calling Flow

1. User sends a message
2. AI decides to use tools
3. Tools execute (file ops, code, etc.)
4. Results fed back to AI
5. AI responds with final answer

---

## 📜 Skills System

* **Metadata Loading**: Only names/descriptions loaded initially
* **On-Demand Activation**: Full skill content loaded when referenced
* **Scripts Support**: Skills can include executable Python scripts
* **References**: Additional documentation files
* **Validation**: Automatic format checking on load

---

## ⚙️ Requirements

* Python 3.8+
* API key for at least one cloud provider (OpenAI, Gemini, or Claude)
* OR Ollama installed for local AI (no API key needed)

---

## 🤝 Contributing

Contributions are welcome! Follow these steps:

### Development Setup

```bash
git clone https://github.com/muhdaliyan/zeer.git
cd zeer
pip install -r requirements.txt
pip install -e .
```

### Making Changes

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Test locally with `zeer`
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Adding Custom Tools

Edit `src/tools.py` and add to the registry in `create_default_registry()`.

### Adding Custom Skills

Create a new folder in `skills/` with a `SKILL.md` following the [agentskills.io](https://agentskills.io) specification.

---

## 📜 License

MIT

---

## 🔗 Links

* [GitHub Repository](https://github.com/muhdaliyan/zeer)
* [PyPI Package](https://pypi.org/project/zeer/)
* [Agent Skills Specification](https://agentskills.io)
