Contribute

Contribute to APEX

APEX welcomes contributions from everyone. Every contribution matters — from bug reports to major features.

Development Setup

1. Clone & Install

bash

git clone https://github.com/Ggboykxz/APEX.git
cd APEX
pip install -e ".[dev]"

2. Run Tests

bash

# Run all tests
pytest

# Run specific test file
pytest tests/test_tools/test_file_ops.py

# Run with coverage
pytest --cov=apex --cov-report=html

3. Run Linter

bash

# Check style
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

Code Style Guide

Python 3.11+

All code must be compatible with Python 3.11 and above. Use modern type hints.

Ruff Linter

Use ruff for linting and formatting. Configuration in pyproject.toml.

100 Char Lines

Maximum line length of 100 characters. Docstrings follow Google style.

Type Hints

All public functions must have type hints. Use Pydantic for data validation.

No Truncation

Never use "...rest of file..." or similar. Always provide complete code.

Error Handling

All functions must handle errors gracefully. Use proper exception types.

Testing Guidelines

Use pytest for all tests. Follow the existing test structure.
All new features must include tests. Aim for 80%+ coverage on new code.
Use fixtures for common test data. Keep tests isolated and deterministic.
Follow the refactoring pattern: write failing test → implement → make test pass → refactor.
Mock external dependencies (API calls, file system) using unittest.mock.
Run pytest --cov before submitting PRs to ensure coverage.

Pull Request Process

Fork & Clone

Fork the repository on GitHub and clone your fork locally.

Create Branch

Create a feature branch from main: git checkout -b feature/my-feature

Make Changes

Write your code following the style guide. Add tests for new functionality.

Run Tests

Run pytest to ensure all tests pass. Add new tests for your changes.

Lint & Format

Run ruff to check code style. Fix any linting issues.

Commit & Push

Write clear commit messages. Push to your fork.

Open PR

Open a pull request with a clear description of your changes.

Issue Types

🐛

Bug

Something is broken. Include steps to reproduce, expected behavior, and actual behavior.

✨

Feature

A new capability. Describe the use case and proposed solution.

📝

Documentation

Improvements to docs. Typos, missing info, new guides, or clearer explanations.

🔧

Refactoring

Code improvement without changing behavior. Better structure, performance, or readability.

Project Structure

text

APEX/
├── apex/
│   ├── agent/            # Agent implementations
│   │   ├── coder.py      # Coder agent (default)
│   │   ├── architect.py   # Architect agent (read-only)
│   │   ├── reviewer.py    # Reviewer subagent
│   │   ├── shell.py       # Shell agent
│   │   └── planner.py     # Planner subagent
│   ├── tools/            # 75+ built-in tools
│   │   ├── file_ops.py   # File operations
│   │   ├── git_tools.py  # Git integration
│   │   ├── search.py     # Search & navigation
│   │   ├── lsp.py        # LSP integration
│   │   ├── web.py        # Web search & fetch
│   │   ├── sandbox.py    # Sandbox execution
│   │   └── ...
│   ├── config/           # Configuration management
│   ├── mcp/              # MCP client support
│   ├── security/         # Permission & rate limiting
│   ├── plugins/          # Plugin system
│   ├── tui/              # Textual TUI frontend
│   ├── cli/              # CLI interface
│   └── utils/            # Shared utilities
├── tests/                # 2,842+ tests (0 failures)
│   ├── test_agents/
│   ├── test_tools/
│   ├── test_security/
│   └── ...
├── docs/                 # Documentation
├── pyproject.toml        # Project config
└── README.md

Key Dependencies

litellm— Unified interface for 100+ LLM providers

prompt_toolkit— Rich CLI input with autocomplete and history

textual— Full-featured TUI framework

pydantic— Data validation and settings management

pytest— Testing framework with 2,842+ tests

ruff— Fast Python linter and formatter

rich— Beautiful terminal formatting and markdown

click— CLI argument parsing and commands

Code of Conduct

We are committed to providing a welcoming and inclusive experience for everyone. Please read our Code of Conduct before contributing.

Start Contributing