locci 0.1.0

A fast, local-first CI engine.

Locci (Local CI)

Locci is a fast, local-first CI preflight tool that runs the safe parts of your CI on your machine before you push. It uses an embedded DAG engine, content-hash caching, GitHub Actions-aware parsing, and clear skip reporting for unsafe or unsupported work.

Locci is intentionally host-native for the MVP: it does not claim to replace your hosted CI runner or Docker-isolate production deploys. Instead, it catches the common lint/test/build failures locally and tells you what still needs remote CI.

Security Caveats

⚠️ Local Safety Heuristics are Best-Effort Locci uses a keyword-based heuristic (looking for words like "deploy", "publish", "release") to identify and skip unsafe side-effect jobs. This is not a security boundary. A job that modifies production state without using these specific keywords will still execute locally.

⚠️ Remote Cache Supply Chain Risk When using the --remote-cache s3://... feature, Locci pulls and restores cache artifacts directly into your workspace. There is currently no cryptographic signature or authenticity verification on these artifacts. Anyone with write access to the shared cache bucket could plant a malicious payload or falsify a test outcome. Use shared remote caching with trusted teams only.

Why Python?

Locci is distributed via pip and written in Python 3.9+. While traditional tools often aim for a single static binary to avoid runtime dependencies, we deliberately chose Python to make installation ubiquitous across all OSes via PyPI, and to allow for rapid iteration and community-driven plugins.

The Tradeoff: You will need a Python 3.9+ runtime to use Locci, even if your project is written in Node.js, Go, or Rust.

Recommendation: We strongly recommend installing Locci globally via pipx to isolate its dependencies from your system Python:

pipx install locci

This gives you a globally available locci command that feels exactly like a static binary, without cluttering your environment.

Usage

# First-time setup in a repo
locci setup

# Daily local CI check
locci check

# Affected pre-push check
locci preflight

# Watch for file changes and incrementally rerun only affected steps
locci watch

Useful commands:

locci setup --preview        # print the generated locci.yml without writing
locci check --dry-run        # show the local execution graph
locci check --strict-coverage
locci hook install           # install a managed pre-push hook
locci doctor                 # inspect required local tools