Agenix 🤖

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

pip install agenix

From Source

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

Using Conda

conda install -c conda-forge agenix

🚀 Quick Start

Setup API Keys

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

Usage

# 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:

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 for full API reference.

🎯 Extensions

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

Extension Locations

• Global: ~/.agenix/extensions/
• Project: .agenix/extensions/

Example Extension

# ~/.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

# .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 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 for creating custom skills.

📚 Documentation

Comprehensive documentation available:

• Documentation Index - Complete documentation hub
• CLI Reference - Command-line usage guide
• SDK Documentation - Programmatic API reference
• Skills Guide - Progressive disclosure system
• Extensions Guide - Build custom extensions
• Session Management - Working with sessions
• Settings Reference - Configuration options
• API Reference - Auto-generated API docs

🧪 Testing

Run tests using pytest:

# Run all tests
pytest

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

# Or use make
make test

🛠️ Development

Setup Development Environment

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

Common Commands

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

# 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

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

📄 License

MIT License - See LICENSE file

👤 Author

ZHANG Zhi - tczhangzhi