Skip to content

Contributing

Jump to bottom
Brian Weisberg edited this page Feb 17, 2026 · 2 revisions

Contributing

Development Setup

# Clone the repository
git clone https://github.com/weisberg/tooli.git
cd tooli

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest tests

# Run with coverage
pytest tests --cov=tooli

# Run a specific test
pytest tests/test_app.py::test_tooli_creates_basic_app

Linting and Formatting

# Lint
ruff check .

# Auto-fix lint issues
ruff check . --fix

# Format
ruff format .

# Type check
mypy tooli

Project Structure

tooli/
├── __init__.py          # Public API exports
├── app.py               # Tooli class (extends Typer)
├── command.py           # TooliCommand (captures return values)
├── output.py            # Output mode detection and routing
├── envelope.py          # JSON envelope model
├── errors.py            # ToolError hierarchy
├── exit_codes.py        # Exit code taxonomy
├── input.py             # StdinOr[T] input type
├── schema.py            # JSON Schema generation
├── config.py            # Configuration precedence
├── annotations.py       # Behavioral annotations
├── detect.py            # Caller detection (TOOLI_CALLER convention + heuristics)
├── testing.py           # Test utilities (TooliTestClient)
├── docs/
│   ├── skill.py         # SKILL.md generation
│   └── llms_txt.py      # llms.txt generation
└── mcp/
    ├── export.py        # MCP tool definition export
    └── server.py        # MCP server (stdio/HTTP)
tests/
├── conftest.py          # Shared fixtures
├── test_app.py          # Core app tests
└── ...

Style Guide

  • Python >= 3.10, use from __future__ import annotations
  • Line length: 88 characters
  • Lint rules: ruff with E, W, F, I, UP, B, SIM, TCH
  • Type annotations: strict mypy
  • Tests: pytest, use CliRunner from typer.testing
  • Commit messages: concise, imperative mood

Issue Workflow

Issues are tracked across three milestones:

  • Phase 1: Core Foundation (MVP) — Issues #2-#16
  • Phase 2: Agent Differentiation — Issues #17-#28
  • Phase 3: Advanced Features — Issues #29-#39

Labels indicate area: core, output, errors, schema, input, mcp, docs, testing, security, observability, architecture, infrastructure, api.

Dependencies

Runtime

  • typer >= 0.9 — CLI framework (Tooli extends this)
  • pydantic >= 2.0 — Schema generation and validation
  • rich >= 13.0 — Human-mode output formatting

Optional

  • fastmcp — MCP server support (required for mcp serve)

Dev

  • pytest — Test framework
  • pytest-cov — Coverage reporting
  • ruff — Linting and formatting
  • mypy — Type checking

Clone this wiki locally