# Zeer

An agentic AI CLI that connects to multiple providers (OpenAI, Gemini, Claude) with tool calling and extensible skills system.

## What is Zeer?

Zeer is a command-line interface for AI agents that can:
- Execute tools (file operations, code execution, system commands)
- Load modular skills following the [agentskills.io](https://agentskills.io) specification
- Switch between AI providers seamlessly
- Maintain conversation context with progressive disclosure

Think of it as Claude Code, but for the terminal and provider-agnostic.

## Key Features

### Agentic Tool Calling
- **File Operations**: Create, read, write, delete files and directories
- **Code Execution**: Run Python code directly from AI responses
- **Extensible**: Add custom tools easily

### Agent Skills System
- **Progressive Disclosure**: Skills load on-demand to save context
- **Modular**: Each skill is self-contained with instructions and scripts
- **Standard**: Follows [agentskills.io](https://agentskills.io) specification
- **Validated**: Automatic format checking

### Multi-Provider Support
- OpenAI (GPT-4, GPT-3.5-Turbo)
- Google Gemini (Gemini Pro, Flash)
- Anthropic Claude (Claude 3 models)
- Credentials stored per provider

## Installation

```bash
pip install zeer
```

## Quick Start

```bash
zeer
```

Select provider, enter API key, choose model, and start chatting.

## Usage Examples

```bash
# Natural language commands - AI uses tools automatically
> 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

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

## Built-in Skills

- **pdf**: Generate PDF documents with reportlab
- **code-helper**: Project setup and code organization
- **file-operations**: File system operations
- **text-processing**: Text manipulation and 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 - skill is auto-discovered

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

## Architecture

```
zeer/
├── src/
│   ├── providers/          # AI provider implementations
│   ├── tools.py           # Tool registry and execution
│   ├── skills_manager.py  # Skills loading and validation
│   └── chat_session.py    # Context management
└── skills/                # Modular agent skills
    ├── pdf/
    ├── code-helper/
    └── ...
```

## Tool Calling Flow

1. User sends 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 AI mentions it
- **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 provider (OpenAI, Gemini, or Claude)

## License

MIT

## Links

- [GitHub](https://github.com/muhdaliyan/zeer)
- [PyPI](https://pypi.org/project/zeer/)
- [Agent Skills Spec](https://agentskills.io)
