Agenix 🤖
A lightweight AI coding agent powered by LLMs.
🎯 Key Features
- 📦 Easy-to-Use Python Library - Simple SDK that works as both CLI tool and importable library
- 🔄 Agent Loop with Tool Execution - Autonomous REPL loop where agent calls tools and continues until task completion
- 🛠️ Simple Tools Without MCP - Four core tools (Read, Write, Edit, Bash) + Grep, no MCP dependencies
- 📚 Progressive Disclosure Skills - Skills loaded on-demand to keep context minimal until needed
- 🔌 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/quitor/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:
- Default:
agenix/default-skills/(bundled) - User:
~/.agenix/skills/(global) - Project:
.agenix/skills/(local, highest priority)
Built-in skills:
pdf- PDF manipulation and extractionxlsx- Excel spreadsheet operationsdocx- Word document processingpptx- PowerPoint presentationsbrowser-use- Web automationfind-skills- Skill discoveryskill-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
Metadata
Release files for agenix 0.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agenix-0.0.2.tar.gz | 3.8 MB | Without provenance | Details for agenix-0.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agenix-0.0.2-py3-none-any.whl | Python 3 | none | any | Details for agenix-0.0.2-py3-none-any.whl |
Total release size: 8.1 MB
Release files / agenix-0.0.2.tar.gz
| Download URL | agenix-0.0.2.tar.gz |
|---|---|
| Size | 3.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f60169d7f3b92b1929262b6ca13ab85a688f957f883432c49e1d30600f5d731e
|
|
BLAKE2b-256 checksum How to use checksums |
1ad8c4ee150fd430efdf137750ea3044db3bfbc8c06f34daf0dccf811b249d10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.7
|
Release files / agenix-0.0.2-py3-none-any.whl
| Download URL | agenix-0.0.2-py3-none-any.whl |
|---|---|
| Size | 4.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5037660ff90c39a73e9a9b8864e9f9f900d8a1c6dc34fe196a7bf313f6e11c34
|
|
BLAKE2b-256 checksum How to use checksums |
52f0fa2a56a38bbc1cc42a82f43389ae8e64b5fa02004f1823eaf2829b28779f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.7
|
Security for agenix 0.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.