---
since: 1.1.1
---

# Local Development Setup

## 1. Environment Setup

gitaiflow requires Python 3.11+ and native compilation toolchains (`gcc`/`clang`, `patchelf`, `zstandard`) if you intend to compile the binary locally.

```bash
git clone https://gitlab.com/clizero/gitaiflow.git
cd gitaiflow

python3 -m venv .venv
source .venv/bin/activate

pip install -e .[dev]
pip install -U nuitka zstandard
```

Or via the `Makefile`:

```bash
make install
```

## 2. Test Suite Execution

```bash
python3 -m pytest tests/ -v
```

Or:

```bash
make test
```

Tests import the package directly from the checkout (`pythonpath = ["."]` in `pyproject.toml`). Filesystem-sensitive tests (usage log, telemetry consent) always isolate `HOME` to a temporary directory rather than touching the developer's real `~/.gitaiflow`.

For the full deterministic regression suite (date parsing, version resolution, commit parsing, diff helpers, artifacts, JSON/Markdown output, usage logging, changelog bucketing/validation/rendering/merging) or telemetry consent tests specifically, see the internal regression-suite docs (not published here).

## 3. Linting

```bash
ruff check .
```

Or:

```bash
make lint
make format   # ruff check . --fix
```

## 4. Local Native Compilation (macOS ARM64)

```bash
chmod +x scripts/install/compile.sh
./scripts/install/compile.sh
```

Or invoke Nuitka manually:

```bash
PYTHONPATH=. python3 -m nuitka \
  --standalone \
  --onefile \
  --remove-output \
  --assume-yes-for-downloads \
  --include-package=gitaiflow \
  --include-package-data=gitaiflow \
  --include-package=httpx \
  --include-package-data=certifi \
  --output-dir=bin \
  --output-filename=gitaiflow \
  gitaiflow/generate_summary.py

chmod +x bin/gitaiflow
./bin/gitaiflow --version
```

Or via `Makefile`:

```bash
make compile
# copies bin/gitaiflow -> installers/gitaiflow-darwin-arm64
```

## 5. Cleaning Build Artifacts

```bash
make clean
```

Removes `build/`, `dist/`, `bin/`, `*.egg-info`, `.cache/`, `*.build`, `*.dist`, and every file under `installers/`.

## Repository Layout

Two independent things ship from this one repository: the `gitaiflow` binary (what end users install), and the telemetry receiver (a small internal service you run separately, not part of the binary). They share a repo and a CI pipeline but nothing else at runtime.

```text
gitaiflow/                        (repo root)
├── gitaiflow/                     <- source package compiled into the binary
│   ├── config/
│   ├── 
│   ├── prompts/
│   ├── templates/
│   └── generate_summary.py        <- entry point
├── telemetry_server/               <- standalone Flask receiver, deployed separately
│   ├── app.py                        to its own host (internal runbook, not published here)
│   └── requirements.txt
├── scripts/
│   ├── install/
│   │   ├── compile.sh
│   │   ├── install.sh
│   │   └── install.ps1
│   ├── r2/
│   │   ├── gitai_manifest.json
│   │   ├── gitai_r2.sh
│   │   └── generate_gitai_manifest.py
│   └── release/
│       └── registry_update.sh
├── tests/
├── Makefile
├── pyproject.toml
└── README.md
```

For the architecture behind the `gitaiflow/` package, see [`../architecture/gitaiflow.md`](../architecture/gitaiflow.md).