pulci 0.0.1

Continuous quality gate daemon for agent-driven Python development.

pulci

Continuous quality gate daemon for agent-driven Python development.

v0.0.1 — Apache-2.0 — docs/AGENTS.md

Why

When AI coding agents (Claude Code, Cursor, Codex) iterate on a Python project, they invoke ruff check, ty check, pytest over and over. Pre-commit hooks run at commit time. CI runs even later. Nothing in the existing tooling stack was designed for the loop an agent actually runs: edit → check → edit, fifty times an hour.

pulci is a small daemon — Rust core, Python CLI — that runs your configured quality gates continuously as files change, and exposes the aggregated state as structured JSON. Agents stop re-invoking tools; they query state.

Comparison

Tool	When it runs	Output format	Built for
pre-commit	Commit time	Human terminal	Humans
prek	Commit time (fast)	Human terminal	Humans
MegaLinter	CI time	Reports	CI/CD
pytest-watch	File change	Human terminal	Humans
pulci	Iteration time	Structured JSON	Agents

pulci does not replace any of these. It fills the empty quadrant.

For AI agents

If you are an AI coding agent, start here: docs/AGENTS.md

The short version: run pulci start --agent once, then call pulci status --json after each edit instead of invoking ruff/ty/pytest directly.

Install

Prerequisites: Rust stable and uv.

git clone https://github.com/grego-casparri/pulci
cd pulci
uv sync
uv run maturin develop --release
uv run pulci --version

PyPI wheels are planned for v0.1.

Usage

Start the daemon (runs in foreground; press Ctrl-C to stop):

pulci start                   # watches current directory, human output
pulci start /path/to/project  # explicit root
pulci start --agent           # compact JSON events — use this in agent loops

Agent mode output (one JSON line per check):

{"event":"check","files":2,"errors":3,"warnings":1,"checks_run":2,"stale":false}

(stale is always false in v0.0.1 — reserved for a future release)

Query current state (reads .pulci/state.json):

pulci status                        # human-readable table
pulci status --json                 # full JSON for agents
pulci status /path/to/project --json

Sample pulci status --json output:

{
  "schema_version": 1,
  "timestamp": "2026-05-16T12:00:00Z",
  "summary": { "errors": 2, "warnings": 1, "checks_run": 2, "stale": false },
  "diagnostics": [
    {
      "tool": "ruff",
      "file": "src/foo.py",
      "line": 12,
      "col": 1,
      "severity": "error",
      "code": "F401",
      "message": "'os' imported but unused"
    }
  ]
}

Configuration

Create pulci.toml in the project root (all fields optional):

[hooks]
ruff   = true    # ruff check on changed .py files (default: true)
ty     = true    # ty check on changed .py files  (default: true)
pytest = false   # pytest on tests/test_<changed>.py (default: false)

If pulci.toml is absent, defaults apply (ruff=true, ty=true, pytest=false).

Benchmark

A benchmark script is included to compare pulci against manual tool invocation and prek across N iterations:

uv run python benchmarks/bench_modes.py --iterations 50

Metrics: mean/p50/p95 latency per iteration, total wall time, estimated output tokens per iteration. pulci's compact state.json is a fixed-schema file; manual tool output grows linearly with the number of violations.

State file contract

.pulci/state.json is the primary contract between pulci and consumers. Schema version is 1 and will be bumped on breaking changes.

Full schema documented in docs/AGENTS.md.

Roadmap

• File watcher with debounce and ignore filters
• ruff, ty, and pytest hook adapters with parallel execution
• Aggregated JSON state, atomic write, hash-based cache
• pulci.toml config, --agent output mode
• Benchmark suite
• PyPI wheels (v0.1)
• MCP server interface (v0.2)
• mypy / basedpyright / bandit adapters (v0.2)

Contributing

See CONTRIBUTING.md.

License

Apache-2.0