singlarity: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Singlarity (DevAssist) is a Python CLI application that aggregates context from multiple developer tools (Gmail, Slack, JIRA, GitHub) and uses Claude Agent SDK to generate intelligent morning briefs. The project uses Model Context Protocol (MCP) servers for context sources and features a unified AppConfig architecture with static session management.

Development Commands

Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\activate  # Windows

# Install in development mode
pip install -e ".[dev]"

Container Engine Setup (Docker/Podman)

DevAssist MCP servers run in containers. The default configuration uses Docker, but Podman is fully supported.

For Podman-only systems (without Docker):

# Create a symlink to allow MCP servers to work with Podman
sudo ln -s $(which podman) /usr/local/bin/docker

Alternative approach: Modify src/devassist/resources/mcp-servers.json to use "command": "podman" instead of "command": "docker".

Testing

# Run all tests
pytest

# Run with coverage (minimum 80% required)
pytest --cov=devassist

# Run unit tests only
pytest tests/unit/

# Run integration tests (requires real API credentials, skipped in CI)
pytest tests/integration/ -m integration

# Run contract tests (validate adapter implementations)
pytest tests/contract/

# Run specific test file
pytest tests/unit/test_brief_generator.py -v

# Skip slow/integration tests
pytest -m "not integration and not slow"

Code Quality

# Type checking (strict mode enabled)
mypy src/

# Linting
ruff check src/

# Format code
ruff format src/

Code Quality Policy: Linter and type checker warnings should be ignored unless they are breaking functionality. The project prioritizes working features over perfect code quality metrics. Fix errors that prevent the code from running, but warnings from ruff and mypy can be addressed later during refactoring phases.