agenix 0.0.2
A lightweight AI coding agent with file operations and shell execution capabilities
License: MIT
Requires Python: >=3.8
Keywords: ai, agent, coding, llm, openai, anthropic, claude, automation, cli, assistant, gpt-4, agenix

# Agenix 🤖

[![PyPI version](https://badge.fury.io/py/agenix.svg)](https://badge.fury.io/py/agenix)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-126%20passed-brightgreen.svg)](tests/)

A lightweight AI coding agent powered by LLMs.

## 🎯 Key Features

1. 📦 **Easy-to-Use Python Library** - Simple SDK that works as both CLI tool and importable library
2. 🔄 **Agent Loop with Tool Execution** - Autonomous REPL loop where agent calls tools and continues until task completion
3. 🛠️ **Simple Tools Without MCP** - Four core tools (Read, Write, Edit, Bash) + Grep, no MCP dependencies
4. 📚 **Progressive Disclosure Skills** - Skills loaded on-demand to keep context minimal until needed
5. 🔌 **Extension System** - Hot-reloadable extensions for custom tools, commands, and event handlers

## 📦 Installation

### From PyPI

```bash
pip install agenix
```

### From Source

```bash
git clone https://github.com/tczhangzhi/agenix.git
cd agenix
pip install -e .
```

### Using Conda

```bash
conda install -c conda-forge agenix
```

## 🚀 Quick Start

### Setup API Keys

```bash
export OPENAI_API_BASE="https://api.openai.com/v1"
export OPENAI_API_KEY="your-key-here"
```

### Usage

```bash
# Interactive mode (enter TUI)
agenix

# Direct message
agenix "Read the README.md file and summarize it"

# Use specific model
agenix --model claude-3-5-sonnet-20241022 "analyze this code"

# Specify working directory
agenix --working-dir /path/to/project

# Load a previous session
agenix --session 20240101_120000

# Custom system prompt
agenix --system-prompt "You are a Python expert"

# Both python -m and agenix command work
python -m agenix "your message"
```

### Interactive Commands

- `/help` - Show help message
- `/clear` - Clear conversation history
- `/sessions` - List saved sessions
- `/load <session_id>` - Load a session
- `/quit` or `/exit` - Exit the program

## 🔌 Programmatic SDK

Use agenix as a library in your Python applications:

```python
import asyncio
from agenix import create_session

async def main():
    # Create a session
    session = await create_session(
        api_key="your-openai-api-key",
        model="gpt-4o",
        working_dir="."
    )

    # Send prompts
    response = await session.prompt("What files are in the current directory?")
    print(response)

    # Continue conversation
    response = await session.prompt("Can you read the README?")
    print(response)

    # Get conversation history
    messages = session.get_messages()
    print(f"Conversation has {len(messages)} messages")

    # Clean up
    await session.close()

if __name__ == "__main__":
    asyncio.run(main())
```

See [SDK Documentation](docs/api/agenix/sdk.html) for full API reference.

## 🎯 Extensions

Extend agenix with custom tools, commands, and event handlers.

### Extension Locations

- **Global**: `~/.agenix/extensions/`
- **Project**: `.agenix/extensions/`

### Example Extension

```python
# ~/.agenix/extensions/weather.py
from agenix.extensions import ToolDefinition

async def setup(agenix):
    """Extension setup function."""

    async def get_weather(params, ctx):
        city = params["city"]
        # Fetch weather data...
        return f"Weather in {city}: Sunny, 72°F"

    # Register custom tool
    agenix.register_tool(ToolDefinition(
        name="get_weather",
        description="Get current weather for a city",
        parameters={
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"}
            },
            "required": ["city"]
        },
        execute=get_weather
    ))
```

### Event Handlers

```python
# .agenix/extensions/logger.py
from agenix.extensions import EventType

async def setup(agenix):
    @agenix.on(EventType.TOOL_CALL)
    async def log_tool_calls(event, ctx):
        print(f"🔧 Tool called: {event.tool_name}")
```

See [EXTENSIONS.md](EXTENSIONS.md) for complete documentation.

## 📚 Agent Skills

Agenix supports progressive disclosure of specialized knowledge through Agent Skills.

Skills are automatically loaded from:
1. **Default**: `agenix/default-skills/` (bundled)
2. **User**: `~/.agenix/skills/` (global)
3. **Project**: `.agenix/skills/` (local, highest priority)

Built-in skills:
- `pdf` - PDF manipulation and extraction
- `xlsx` - Excel spreadsheet operations
- `docx` - Word document processing
- `pptx` - PowerPoint presentations
- `browser-use` - Web automation
- `find-skills` - Skill discovery
- `skill-creator` - Skill creation guide

See [Skills Guide](docs/skills.md) for creating custom skills.

## 📚 Documentation

Comprehensive documentation available:

- **[Documentation Index](docs/README.md)** - Complete documentation hub
- **[CLI Reference](docs/cli.md)** - Command-line usage guide
- **[SDK Documentation](docs/sdk.md)** - Programmatic API reference
- **[Skills Guide](docs/skills.md)** - Progressive disclosure system
- **[Extensions Guide](EXTENSIONS.md)** - Build custom extensions
- **[Session Management](docs/sessions.md)** - Working with sessions
- **[Settings Reference](docs/settings.md)** - Configuration options
- **[API Reference](docs/api/index.html)** - Auto-generated API docs

## 🧪 Testing

Run tests using pytest:

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=agenix tests/

# Or use make
make test
```

## 🛠️ Development

### Setup Development Environment

```bash
git clone https://github.com/tczhangzhi/agenix.git
cd agenix
make dev  # or: pip install -e .[dev]
```

### Common Commands

```bash
make help       # Show all commands
make install    # Install in development mode
make test       # Run tests
make clean      # Clean build artifacts
make build      # Build distribution
make upload     # Upload to PyPI
```

### Project Structure

```
agenix/
├── agenix/              # Main package
│   ├── __init__.py      # Package exports (SDK)
│   ├── __main__.py      # Entry point for python -m agenix
│   ├── cli.py           # CLI implementation
│   ├── sdk.py           # Programmatic SDK
│   ├── core/            # Core modules
│   │   ├── agent.py     # Agent runtime
│   │   ├── llm.py       # LLM providers
│   │   ├── session.py   # Session management
│   │   ├── skills.py    # Skills system
│   │   └── messages.py  # Message types
│   ├── tools/           # Built-in tools
│   │   ├── read.py      # File reading
│   │   ├── write.py     # File writing
│   │   ├── edit.py      # File editing
│   │   ├── bash.py      # Shell execution
│   │   └── grep.py      # Code search
│   ├── extensions/      # Extension system
│   │   ├── types.py     # Event types & API
│   │   ├── loader.py    # Extension loading
│   │   └── runner.py    # Extension execution
│   ├── default-skills/  # Bundled skills
│   │   ├── pdf/
│   │   ├── xlsx/
│   │   ├── docx/
│   │   └── ...
│   └── ui/              # Terminal UI
├── tests/               # Test suite (126 tests)
│   ├── core/            # Core tests
│   ├── tools/           # Tool tests
│   └── ui/              # UI tests
├── examples/            # Usage examples
│   ├── sdk_basic.py     # SDK example
│   ├── extension_weather.py
│   └── extension_monitor.py
├── docs/                # Documentation
│   └── api/             # Generated API docs
├── setup.py             # Package configuration
├── Makefile             # Development commands
├── EXTENSIONS.md        # Extension guide
└── README.md
```

## 📚 Publishing

### To PyPI

```bash
# Build
make build

# Upload (requires twine and PyPI credentials)
make upload

# Or manually:
python setup.py sdist
twine upload dist/agenix-*.tar.gz
```

### To Conda

```bash
conda build conda/
anaconda upload <path-to-package>
```

## 📄 License

MIT License - See [LICENSE](LICENSE) file

## 👤 Author

**ZHANG Zhi** - [tczhangzhi](https://github.com/tczhangzhi)