auto-commit-service/CLAUDE.md

CLAUDE.md

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

Commands

# Install
uv pip install -e .              # basic
uv pip install -e ".[dev]"       # with test deps

# Tests
pytest                            # unit/smoke tests (GPU tests excluded by default)
pytest tests/test_daemon.py -v    # single file
pytest tests/test_daemon.py::TestDaemon::test_start -v  # single test
pytest -m gpu -v                  # GPU integration tests (needs model-boss coordinator running)
pytest --cov=auto_commit_service  # with coverage

# Lint/type check
ruff check src/ tests/
ruff format src/ tests/
mypy src/

# Run service
python -m auto_commit_service     # direct entry
commits start 5m -R               # CLI: daemon with 5m cycle, recursive discovery
commits status --all              # check all running daemons

# Systemd
systemctl --user restart auto-commit-applications.service
journalctl --user -u auto-commit-applications -f

Architecture

Periodic sweep + synchronous queue-mediated inference. The daemon loops every cycle_interval_seconds (default 180s), processes repos sequentially, and each LLM call blocks on model-boss coordinator's queue. The commits-tray macOS app can also act as a remote commit agent: with --commit-local, it scans repos on the local Mac, forwards diffs to apricot's /generate-message endpoint for LLM inference, commits and pushes locally, and reports back via /record-commit — no second daemon needed on the Mac.

Execution flow

CommitDaemon.start() — main loop
  for each dirty repo:
    PipelineCommitProcessor.commit_repo()
      → Pipeline orchestrator (11 stages):
        PreFilter → Discover → Retrieve(RAG) → Group → Analyze(14B) → Format(3B)
        → Commit → Push → VersionDetect → PublishVerify → Recover
      → Each LLM stage calls MultiModelLlamaClient._chat()
        → InferenceClient.chat() → POST coordinator:8210/v1/chat/completions
        → model-boss coordinator queues and executes on GPU
  sleep(cycle_interval_seconds)

Two-model LLM pipeline

All inference routes through model-boss coordinator (port 8210). No direct model loading.

• Reasoning (ministral-14b-reasoning): Analyzes diffs, groups files, understands changes
• Instruct (ministral-3b-instruct): Formats commit messages from analysis
• Recovery (claude:sonnet via model-boss): Two-phase recovery for git failures — Claude diagnoses, ACS executes the plan locally

Key modules

Module	Role
scheduler/daemon.py	Main loop, cycle orchestration, repo discovery
scheduler/pipeline_processor.py	Per-repo processing, monorepo submodule handling
pipeline/orchestrator.py	Creates the 11-stage pipeline chain
pipeline/stages/	Individual pipeline stages
pipeline/init.py	Global ML provider initialization (must call before pipeline)
llm/multi_model_client.py	Routes inference to model-boss via InferenceClient
recovery/handlers.py	Error classification → recovery strategy routing
recovery/claude_fallback.py	Two-phase Claude recovery (diagnose via model-boss, execute locally)
database/	Async SQLite (aiosqlite) for commit/cycle/error history
cli/	Typer CLI (commits command) for multi-daemon management
app.py	FastAPI factory with 20+ monitoring/control endpoints
config.py	All settings with AUTO_COMMIT_ env prefix

External dependencies

• model-boss coordinator (port 8210): GPU model management, inference queue, VRAM scheduling
• rag-retrieval (optional): Contextual retrieval for commit analysis
• git: All operations via asyncio.create_subprocess_exec (no shell)

Configuration

All settings via env vars prefixed AUTO_COMMIT_ or ~/.config/commits/startup-config.json.

Key settings: REASONING_MODEL_ID, INSTRUCT_MODEL_ID, CYCLE_INTERVAL_SECONDS, CLAUDE_FALLBACK_ENABLED, CLAUDE_RECOVERY_MODEL.

Per-directory git identity and push behavior via directory_overrides in config.

Testing

• asyncio_mode = "auto" — all async tests run automatically
• GPU tests require model-boss coordinator running, marked @pytest.mark.gpu
• Fixtures: temp_git_repo (creates temp git repo), mock_settings (unit), gpu_settings (integration)
• ruff: line-length 100, select E,F,I,N,W,UP,B,C4,SIM,RUF,PTH,ERA
• mypy: strict mode, Python 3.11+

Data paths

Path	Contents
~/.cache/commits/auto_commit.db	SQLite: commits, cycles, errors, repo status
~/.cache/commits/activity.jsonl	Activity log (JSON Lines)
~/.cache/commits/auto-commit.log	Rotated log file
~/.config/commits/startup-config.json	Daemon registry config
~/.config/commits/daemons.json	Running daemon instances

Important notes

• Never commit from this repo — ACS itself handles all commits across the workspace
• Pipeline stages access ML providers via globals initialized by init_ml_providers() — must be called before pipeline execution
• ACS uses default_priority="batch" (lowest) in model-boss queue, so interactive requests preempt it
• Recovery commands are validated against an allowlist (no --force, --hard, --no-verify)