sensors-cli 0.1.0__tar.gz

sensors_cli-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: sensors-cli
+Version: 0.1.0
+Summary: Continuous code quality monitoring sensors for coding agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+
+# Sensors Sidecar CLI
+
+An **experimental** little "sidecar" system that can run a bunch of code quality sensors next to a coding agent. It can run linting, tests, and other checks on a schedule or in watch mode, persists structured state under `.sensors/` in the target codebase, and exposes a **`sensors`** CLI for running the service, checking the sensor status, or displaying the status in a human readable format.
+
+Companion repository to this article: [Maintainability sensors for coding agents](https://martinfowler.com/articles/sensors-for-coding-agents.html)
+
+Use `/_local-setup` skill to set it up on your machine (or use the `SKILL.md` file as documentation if you want to do it manually).
+
+**Platform note:** The control plane uses **Unix domain sockets**, tested only on MacOS.
+
+This tool was more or less vibe coded, though I did do regular refactorings with AI, and used the CLI to run sensors for this codebase ("eating my own dog food"). Check out [`.sensors/sensors-cli.sensors.yaml`](./.sensors/sensors-cli.sensors.yaml) to see the sensors used here. And look at [2026-06-15_modularity-review.md](./docs/reports/2026-06-15_modularity-review.md) for examples of why quick sensors like this can help with maintainability, but can only go so far when we don't spend much time on the larger code structure...
+
+## Commands
+
+(CLI needs to be installed via `uv tool install`, see `/_local-setup` skill)
+
+```bash
+# Is the sensors service running? (exit 0 = yes, 1 = no)
+sensors status .
+
+# All sensors start processes on this host (from /proc or ps)
+sensors status --all
+
+# Start the sensors
+sensors start .
+
+# Show the state
+sensors show .
+
+# Start the sensors and immediately jump into the display mode
+sensors show --start .
+
+# Agent-optimized runner results (failures included per runner); exit 0/1/2
+sensors check .
+
+sensors check . --runner eslint
+
+# Save a score snapshot via RPC (needs a process to be running)
+sensors snapshot .
+```
+
+## Configuration
+
+The CLI looks for a `*.sensors.yaml` file under `.sensors/`. 
+
+There are some skills in this repo that document this setup more and that you can reuse:
+- `.claude/skills/sensors_config-default` - a minimalist default setup that tries to determine one sensor example from your codebase. Use this to just get a taste
+- `.claude/skills/sensors_config-typescript` - my full Typescript sensors setup
+- `.claude/skills/sensors_config-python` - my full Python sensors setup
+
+## Parsers
+
+The project comes with a bunch of output parsers for common tools, like `eslint` or `ruff`. If you want to use a tool as a sensor that is not yet supported, you either have to add a new parser to the code (and reinstall the CLI), or you can use the default parser.
+
+### Adding a new parser
+
+This repo contains a skill that documents how to add a new parser [`.claude/skills/_new-parser/SKILL.md`](/.claude/skills/_new-parser/SKILL.md) in this repo for a guided template.
+
+## Default parser: Expected output format
+
+Use `parser: default` in your runner config to connect any tool that can emit a JSON object in the specified schema. You have to build a script for your tool that turns the tool's output into this schema, and use that script in your sensor configuration.
+
+This repo contains a skill that can help you write a wrapper script around your tool to transform your tool's data into the JSON schema [`.claude/skills/sensors_wrap-tool/SKILL.md`](/.claude/skills/sensors_wrap-tool/SKILL.md)
+
+### Schema
+
+```json
+{
+  "findings": [
+    {
+      "message": "Unused variable 'x'",
+      "severity": "error",
+      "file": "src/foo.py",
+      "line": 42,
+      "column": 9,
+      "rule": "F841",
+      "context": "x is assigned but never used"
+    }
+  ],
+  "metrics": [
+    {
+      "key": "errorCount",
+      "label": "Errors",
+      "value": 1,
+      "direction": "less"
+    }
+  ],
+  "guidance": [
+    {
+      "rule": "F841",
+      "body": "Remove variable or use it."
+    }
+  ],
+  "score": {
+    "value": 1,
+    "direction": "less",
+    "description": "Issues reported by tool"
+  },
+  "success": false,
+  "summary": "1 issue",
+  "extra": {
+    "any": "parser-specific payload"
+  }
+}
+```
+
+This schema mirrors the `SensorReading` model used by built-in parsers. All fields are optional; missing values are derived as follows:
+
+| Field | If absent or null |
+|---|---|
+| `findings` | treated as `[]` |
+| `metrics` | treated as `[]` |
+| `guidance` | treated as `[]` |
+| `extra` | treated as `{}` |
+| `success` | `true` when `findings` is empty, `false` otherwise |
+| `summary` | `"N issue(s)"` / `"No issues"` derived from findings count |
+| `score.value` | `len(findings)` |
+| `score.direction` | `"less"` (lower is better) |
+| `score.description` | `"Issues reported by tool"` |
+
+`success`, `summary`, and `score` can be set explicitly and are used as-is. This allows tools that do not produce per-finding rows (for example, coverage checks) to report a score directly.
+
+
+### Example config
+
+```yaml
+runners:
+  - name: my-custom-check
+    parser: default
+    enabled: true
+    mode: interval
+    command: some-tool | ./scripts/to-parser-default-format.sh
+    interval: 10000
+```
+
+### Minimal valid output
+
+A tool that only reports a count without individual violations:
+
+```json
+{"success": false, "summary": "Coverage 72% (threshold 80%)", "score": {"value": 72, "direction": "more"}}
+```
+
+A tool with no issues:
+
+```json
+{"findings": []}
+```

sensors_cli-0.1.0/README.md

@@ -0,0 +1,148 @@
+# Sensors Sidecar CLI
+
+An **experimental** little "sidecar" system that can run a bunch of code quality sensors next to a coding agent. It can run linting, tests, and other checks on a schedule or in watch mode, persists structured state under `.sensors/` in the target codebase, and exposes a **`sensors`** CLI for running the service, checking the sensor status, or displaying the status in a human readable format.
+
+Companion repository to this article: [Maintainability sensors for coding agents](https://martinfowler.com/articles/sensors-for-coding-agents.html)
+
+Use `/_local-setup` skill to set it up on your machine (or use the `SKILL.md` file as documentation if you want to do it manually).
+
+**Platform note:** The control plane uses **Unix domain sockets**, tested only on MacOS.
+
+This tool was more or less vibe coded, though I did do regular refactorings with AI, and used the CLI to run sensors for this codebase ("eating my own dog food"). Check out [`.sensors/sensors-cli.sensors.yaml`](./.sensors/sensors-cli.sensors.yaml) to see the sensors used here. And look at [2026-06-15_modularity-review.md](./docs/reports/2026-06-15_modularity-review.md) for examples of why quick sensors like this can help with maintainability, but can only go so far when we don't spend much time on the larger code structure...
+
+## Commands
+
+(CLI needs to be installed via `uv tool install`, see `/_local-setup` skill)
+
+```bash
+# Is the sensors service running? (exit 0 = yes, 1 = no)
+sensors status .
+
+# All sensors start processes on this host (from /proc or ps)
+sensors status --all
+
+# Start the sensors
+sensors start .
+
+# Show the state
+sensors show .
+
+# Start the sensors and immediately jump into the display mode
+sensors show --start .
+
+# Agent-optimized runner results (failures included per runner); exit 0/1/2
+sensors check .
+
+sensors check . --runner eslint
+
+# Save a score snapshot via RPC (needs a process to be running)
+sensors snapshot .
+```
+
+## Configuration
+
+The CLI looks for a `*.sensors.yaml` file under `.sensors/`. 
+
+There are some skills in this repo that document this setup more and that you can reuse:
+- `.claude/skills/sensors_config-default` - a minimalist default setup that tries to determine one sensor example from your codebase. Use this to just get a taste
+- `.claude/skills/sensors_config-typescript` - my full Typescript sensors setup
+- `.claude/skills/sensors_config-python` - my full Python sensors setup
+
+## Parsers
+
+The project comes with a bunch of output parsers for common tools, like `eslint` or `ruff`. If you want to use a tool as a sensor that is not yet supported, you either have to add a new parser to the code (and reinstall the CLI), or you can use the default parser.
+
+### Adding a new parser
+
+This repo contains a skill that documents how to add a new parser [`.claude/skills/_new-parser/SKILL.md`](/.claude/skills/_new-parser/SKILL.md) in this repo for a guided template.
+
+## Default parser: Expected output format
+
+Use `parser: default` in your runner config to connect any tool that can emit a JSON object in the specified schema. You have to build a script for your tool that turns the tool's output into this schema, and use that script in your sensor configuration.
+
+This repo contains a skill that can help you write a wrapper script around your tool to transform your tool's data into the JSON schema [`.claude/skills/sensors_wrap-tool/SKILL.md`](/.claude/skills/sensors_wrap-tool/SKILL.md)
+
+### Schema
+
+```json
+{
+  "findings": [
+    {
+      "message": "Unused variable 'x'",
+      "severity": "error",
+      "file": "src/foo.py",
+      "line": 42,
+      "column": 9,
+      "rule": "F841",
+      "context": "x is assigned but never used"
+    }
+  ],
+  "metrics": [
+    {
+      "key": "errorCount",
+      "label": "Errors",
+      "value": 1,
+      "direction": "less"
+    }
+  ],
+  "guidance": [
+    {
+      "rule": "F841",
+      "body": "Remove variable or use it."
+    }
+  ],
+  "score": {
+    "value": 1,
+    "direction": "less",
+    "description": "Issues reported by tool"
+  },
+  "success": false,
+  "summary": "1 issue",
+  "extra": {
+    "any": "parser-specific payload"
+  }
+}
+```
+
+This schema mirrors the `SensorReading` model used by built-in parsers. All fields are optional; missing values are derived as follows:
+
+| Field | If absent or null |
+|---|---|
+| `findings` | treated as `[]` |
+| `metrics` | treated as `[]` |
+| `guidance` | treated as `[]` |
+| `extra` | treated as `{}` |
+| `success` | `true` when `findings` is empty, `false` otherwise |
+| `summary` | `"N issue(s)"` / `"No issues"` derived from findings count |
+| `score.value` | `len(findings)` |
+| `score.direction` | `"less"` (lower is better) |
+| `score.description` | `"Issues reported by tool"` |
+
+`success`, `summary`, and `score` can be set explicitly and are used as-is. This allows tools that do not produce per-finding rows (for example, coverage checks) to report a score directly.
+
+
+### Example config
+
+```yaml
+runners:
+  - name: my-custom-check
+    parser: default
+    enabled: true
+    mode: interval
+    command: some-tool | ./scripts/to-parser-default-format.sh
+    interval: 10000
+```
+
+### Minimal valid output
+
+A tool that only reports a count without individual violations:
+
+```json
+{"success": false, "summary": "Coverage 72% (threshold 80%)", "score": {"value": 72, "direction": "more"}}
+```
+
+A tool with no issues:
+
+```json
+{"findings": []}
+```

sensors_cli-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sensors*"]
+
+[project]
+name = "sensors-cli"
+version = "0.1.0"
+description = "Continuous code quality monitoring sensors for coding agents"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0",  # For better CLI output
+]
+
+[project.scripts]
+sensors = "sensors.cli:main"
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=7.0.0",
+    "black>=26.3.1",
+    "mypy>=1.0.0",
+    "ruff>=0.4.0",
+    "import-linter>=2.5.2",
+    "pyinstaller>=6.22.0",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 100
+target-version = ['py310']
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",        # pycodestyle errors (indentation, spacing, etc.)
+    "F",        # Pyflakes (unused imports, undefined names, redefinitions)
+    "I",        # isort (import order and grouping)
+    "W",        # pycodestyle warnings (style nits; see ignore list)
+    "UP",       # pyupgrade (use modern Python syntax and builtins)
+    "B",        # flake8-bugbear (likely bugs and questionable patterns)
+    "SIM",      # flake8-simplify (redundant code that can be simplified)
+    "C901",     # McCabe complexity (too many branches/paths in one function)
+    "PLR0913",  # too many function/method parameters
+    "PLR0915",  # too many statements in one function/method body
+    "PLR0917",  # too many positional-only parameters
+]
+ignore = [
+    "E501",  # line too long (Black/format handles line length)
+    "W291",  # trailing whitespace
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10  # threshold for C901 (default is 10)
+
+[tool.ruff.lint.pylint]
+max-args = 5         # threshold for PLR0913 (default is 5)
+max-statements = 50  # threshold for PLR0915 (default is 50)
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

sensors_cli-0.1.0/sensors/__init__.py

@@ -0,0 +1,5 @@
+"""
+Sensors: Continuous code quality monitoring for coding agents.
+"""
+
+__version__ = "0.1.0"