Skip to content

Contributing to Attocode

Getting Started

git clone https://github.com/eren23/attocode.git
cd attocode

uv sync --all-extras          # creates .venv, installs everything
# or: python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"

Development Workflow

  1. Create a feature branch from main
  2. Make changes, add tests
  3. Run pytest tests/unit/ -x -q for fast feedback
  4. Run ruff check src/ tests/ for linting
  5. Open a pull request

Running Tests

# All tests
pytest tests/

# Unit tests only (fast, no I/O)
pytest tests/unit/ -x -q

# Specific module
pytest tests/unit/integrations/test_agents.py -v

# With coverage
pytest tests/ --cov=src/attocode --cov-report=term-missing

# Skip known pre-existing failures
pytest tests/unit/ --ignore=tests/unit/attoswarm -x

Code Style

  • Formatter/Linter: Ruff
  • Type checker: mypy (strict mode)
  • Test framework: pytest with pytest-asyncio
  • Use @dataclass for data containers
  • Use AsyncMock for async dependencies in tests
  • Group related tests in classes: class TestFeatureName:

Project Structure

src/
  attocode/          Main agent package
  attoswarm/         Standalone swarm orchestration
  attocode_core/     Shared AST indexing
tests/
  unit/              Fast tests, no I/O
  integration/       Slower tests requiring I/O

See Architecture for detailed module documentation.

Adding a New Tool

  1. Create src/attocode/tools/my_tool.py implementing BaseTool
  2. Register in src/attocode/tools/registry.py
  3. Add tests in tests/unit/tools/test_my_tool.py
  4. Update the policy table in src/attocode/integrations/safety/policy_engine.py if the tool needs special permissions

Adding a New Provider

  1. Create adapter in src/attocode/providers/adapters/
  2. Implement LLMProvider base class from providers/base.py
  3. Register in providers/registry.py
  4. Add model defaults in config.py
  5. See Providers

Adding a New Integration

  1. Pick the appropriate subdirectory under src/attocode/integrations/ (or create one)
  2. Add your module
  3. Export from the subdirectory's __init__.py
  4. Write tests in tests/unit/integrations/

Commit Messages

Use conventional commit style:

feat(budget): add dynamic budget reallocation
fix(sandbox): handle missing Landlock kernel support
test(recording): add playback engine unit tests
docs(providers): add OpenAI adapter reference

Known Pre-existing Test Failures

These tests fail in CI due to environment assumptions and are safe to ignore:

Test Reason
test_mcp.py::test_empty_when_no_files Global MCP defaults now include context7
test_attoswarm_smoke.py::test_two_claude_smoke_fake_worker Swarm integration timing
test_cli.py::test_init_interactive_minimal_existing_repo Attoswarm CLI change