Provides context-aware Python linting with pattern-based heuristics for reviewing GitHub pull requests.
# pylinter-assist — OpenClaw Skill
name: pylinter-assist
version: 0.6.3
## Prerequisites
Before installing this skill, ensure you have the following installed:
### Python (via pyenv or system package manager)
This project uses standard **pyenv + pip + venv** — no remote install scripts required.
**Install pyenv (no `curl | sh`):**
```bash
# macOS
brew install pyenv
# Linux — auditable git clone (can be pinned to a specific commit)
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
# Then follow https://github.com/pyenv/pyenv#set-up-your-shell-environment
```
**Install Python 3.11 and activate:**
```bash
pyenv install 3.11 # reads .python-version automatically if present
pyenv local 3.11 # creates .python-version in the project root
```
Alternatively, use any system Python 3.11+ (`python3 --version`) — pyenv is optional if you already have a suitable Python.
### npm (Node.js package manager, for ClawHub CLI)
```bash
# macOS/Linux
brew install node # or your preferred package manager
# Or download from https://nodejs.org/
```
### clawhub CLI (OpenClaw skill installer)
```bash
npm i -g clawhub
```
## Description
Context-aware Python linting with smart pattern heuristics for PR review.
Automatically integrates into GitHub workflows to lint pull requests and provide feedback.
## Features
- Combines Pylint with custom pattern checks (hardcoded secrets, missing docstrings, etc.)
- Auto-lints PRs when integrated via GitHub Actions
- Supports multiple output formats (markdown, text, json)
- Configurable rules via `.linting-rules.yml`
## Installation via ClawHub
Install the skill using the ClawHub CLI:
```bash
clawhub install pylinter-assist
```
The skill will be installed to `~/.openclaw/workspace/skills/pylinter-assist`.
## Integration Steps
### Step 0: Post-Installation Setup
After the skill is installed as a snapshot, create a venv and install the CLI:
```bash
cd ~/.openclaw/workspace/skills/pylinter-assist
python -m venv .venv
source .venv/bin/activate
pip install -e .
```
This registers the `lint-pr` command for the duration of your shell session.
Deactivate when done: `deactivate`
### Step 1: Use the CLI
```bash
# Create and activate the virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install the package and its dependencies
pip install -e .
# Run the linter
lint-pr pr 42 --post-comment
```
Or run the wrapper script directly (no venv activation needed if dependencies are installed):
```bash
python scripts/lint_pr.py pr 42 --post-comment
```
### Step 2: Add GitHub Actions Workflow
> **Security warning:** GitHub Actions workflows run with your repository's permissions
> and can read secrets. Only commit a workflow file whose full contents you have read
> and understood. Never copy a file from a URL without inspecting it first.
**Recommended — copy from a local clone** (you can `git log` and `git show` the file
before copying; no network fetch at commit time):
```bash
git clone https://github.com/claytantor/pylinter-assist.git /tmp/pylinter-assist
# Review the workflow source before copying
cat /tmp/pylinter-assist/.github/workflows/lint-pr.yml
mkdir -p .github/workflows
cp /tmp/pylinter-assist/.github/workflows/lint-pr.yml .github/workflows/
```
**Last resort — direct download.** Pin to a specific commit SHA, not `main`, so the
file cannot change under you. Replace `<COMMIT_SHA>` with the exact commit you reviewed
on GitHub:
```bash
# Find the commit SHA: https://github.com/claytantor/pylinter-assist/commits/main
COMMIT_SHA=<COMMIT_SHA>
mkdir -p .github/workflows
curl -o .github/workflows/lint-pr.yml \
"https://raw.githubusercontent.com/claytantor/pylinter-assist/${COMMIT_SHA}/.github/workflows/lint-pr.yml"
# Verify the download — compare against what you saw on GitHub
cat .github/workflows/lint-pr.yml
sha256sum .github/workflows/lint-pr.yml # record this for future reference
```
### Step 3: Add Configuration (Optional)
Copy and customize the rules file:
```bash
cp /path/to/pylinter-assist/.linting-rules.yml .linting-rules.yml
```
### Step 4: Set Repository Permissions
Ensure your repository has these permissions enabled:
```yaml
permissions:
contents: read
pull-requests: write
issues: write
```
### Step 5: Commit and Push
The workflow will automatically trigger on new PRs.
## Enabling a New Project for Support
> **Security warning:** The workflow file you are about to commit runs with your
> repository's permissions and can access secrets. Read every line of the file before
> committing. Do not use `curl … | sh` or copy files from a branch tip (`main`) without
> pinning to a reviewed commit.
**Recommended approach — clone, review, then copy:**
```bash
# 1. Clone the skill repo to a temporary location
git clone https://github.com/claytantor/pylinter-assist.git /tmp/pylinter-assist
# 2. Review the files you are about to add to your repo
cat /tmp/pylinter-assist/.github/workflows/lint-pr.yml
cat /tmp/pylinter-assist/.linting-rules.yml
# 3. Switch to your project and copy the reviewed files
cd <your-project-root>
git checkout dev
git pull origin dev
mkdir -p .github/workflows
cp /tmp/pylinter-assist/.github/workflows/lint-pr.yml .github/workflows/
cp /tmp/pylinter-assist/.linting-rules.yml .linting-rules.yml
# 4. Commit only after you are satisfied with the contents
git add .github/workflows/lint-pr.yml .linting-rules.yml
git commit -m "ci: add pylinter-assist workflow for PRs targeting dev"
git push origin dev
```
The workflow requires these permissions in your repository settings:
```yaml
permissions:
contents: read
pull-requests: write
issues: write
```
## Usage
```bash
# Activate venv first
source .venv/bin/activate
lint-pr [TARGET] [OPTIONS]
```
### Targets
| Target | Description |
|--------|-------------|
| `pr <number>` | Lint all files changed in a GitHub PR |
| `staged` | Lint git-staged files |
| `diff <file>` | Lint files from a unified diff file |
| `files <path>...` | Lint explicit files or directories |
### Examples
```bash
# Activate venv
source .venv/bin/activate
# Lint PR #42 and post comment
lint-pr pr 42 --post-comment
# Lint staged changes
lint-pr staged
# Lint a diff file
lint-pr diff /tmp/changes.diff
# Lint specific files
lint-pr files src/ tests/
```
### Options
| Flag | Description |
|------|-------------|
| `--format text\|json\|markdown` | Output format (default: markdown) |
| `--config <path>` | Custom `.linting-rules.yml` path |
| `--post-comment` / `--no-post-comment` | Post result as GitHub PR comment |
| `--fail-on-warning` | Also fail on warnings (default: errors only) |
## Checks Performed
| Check | Code | Severity | Catches |
|-------|------|----------|---------|
| Pylint | C/W/R/E/F | varies | Standard Python quality issues |
| Hardcoded password/secret | HCS001 | ERROR | `password = "abc123"` |
| Credentials in URL | HCS002 | ERROR | `https://user:pass@host` |
| Hardcoded IP address | HCS003 | ERROR | `HOST = "10.0.0.5"` |
| Hardcoded localhost URL | HCS004 | ERROR | `"http://localhost:8000"` |
| AWS/GCP access key | HCS005 | ERROR | `AKIAIOSFODNN7EXAMPLE` |
| FastAPI missing docstring | FAD001 | WARNING | `@router.get("/")` without docstring |
| useEffect missing deps | RUE001 | WARNING | React useEffect with no deps array |
| useEffect suspicious deps | RUE002 | INFO | useEffect referencing outer vars |
## Configuration
Copy `.linting-rules.yml` to your project root and customize:
```yaml
pylint:
enabled: true
disable: [C0114, C0115] # suppress module/class docstring warnings
hardcoded_secrets:
enabled: true
skip_ip_check: false
fastapi_docstring:
severity: warning
react_useeffect_deps:
severity: warning
github:
post_comment: true
fail_on_error: true
fail_on_warning: false
```
## Workflow Triggers
- **pull_request**: Auto-lints all files changed in a PR
- **workflow_dispatch**: Manual trigger via GitHub UI or API
## Manual Trigger Examples
**GitHub CLI (preferred — token is handled by `gh auth`, not exposed in shell):**
```bash
gh workflow run lint-pr.yml -f pr_number=42 -f format=markdown -f post_comment=true
```
**REST API:**
> **Security note:** The token passed via `-H "Authorization: token $GITHUB_TOKEN"` must
> be a Personal Access Token or a fine-grained token scoped to `actions:write`. Never
> hard-code the token value in scripts; always expand it from an environment variable.
```bash
curl -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
https://api.github.com/repos/OWNER/REPO/actions/workflows/lint-pr.yml/dispatches \
-d '{"ref":"main","inputs":{"pr_number":"42","format":"markdown","post_comment":"true"}}'
```
## Output
- Markdown reports posted as PR comments (when enabled)
- JSON artifacts uploaded for 14 days retention
- Exit code 1 if errors found (when `fail_on_error: true`)
## Troubleshooting
### `command not found: lint-pr` after installation
The `lint-pr` CLI is installed inside the virtual environment. Either activate it or call it directly:
```bash
# Activate the venv
source .venv/bin/activate
# Or call it directly without activation
./.venv/bin/lint-pr pr 42
```
### `python3: command not found` or wrong Python version
Ensure Python 3.11+ is installed and on your PATH:
```bash
python3 --version
# If using pyenv, install the required version
pyenv install # reads .python-version automatically
pyenv versions # list installed versions
```
### `pip install -e .` fails
Ensure the venv is activated before installing:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```
## GitHub Actions Monitoring
The skill can automatically monitor GitHub Actions workflow runs and notify you when lint results are ready.
### Monitor a Repository
Use the `monitor` command to watch for completed workflow runs:
```bash
# Basic monitoring - download report only
lint-pr monitor owner/repo --token $GITHUB_TOKEN
# Monitor with timeout and custom polling interval
lint-pr monitor owner/repo --token $GITHUB_TOKEN --timeout 3600 --poll-interval 60
```
> **Security note:** Avoid passing secrets (bot tokens, webhook URLs) directly as
> `--callback` command-line arguments — they are visible in process listings (`ps aux`).
> Prefer setting notification credentials in `.linting-rules.yml` with values read from
> environment variables, or ensure your shell history is protected before using the
> `--callback` flag.
```bash
# Monitor with Telegram notification (tokens visible in process list — use with caution)
lint-pr monitor owner/repo --token $GITHUB_TOKEN \
--callback telegram:$TELEGRAM_BOT_TOKEN:$TELEGRAM_CHAT_ID
# Monitor with Discord notification
lint-pr monitor owner/repo --token $GITHUB_TOKEN \
--callback discord:$DISCORD_WEBHOOK_URL
# Monitor with multiple channels
lint-pr monitor owner/repo --token $GITHUB_TOKEN \
--callback telegram:$TELEGRAM_BOT_TOKEN:$TELEGRAM_CHAT_ID \
--callback discord:$DISCORD_WEBHOOK_URL
```
### Configuration
Enable notifications in `.linting-rules.yml`:
```yaml
notifications:
enabled: true
channels:
- type: telegram
bot_token: $TELEGRAM_BOT_TOKEN
chat_id: 123456789
- type: discord
webhook_url: https://discord.com/api/webhooks/...
username: "Lint Bot"
- type: slack
webhook_url: https://hooks.slack.com/services/...
```
### Monitoring Configuration
```yaml
github_actions:
polling_interval: 30 # Seconds between status checks
max_timeout: 1800 # Max seconds to wait (30 minutes)
retry_attempts: 3 # Retry failed API calls
```
### Supported Notification Channels
| Channel | Setup |
|---------|-------|
| Telegram | Create bot via @BotFather, get chat_id from bot |
| Discord | Create webhook in channel settings |
| Slack | Create incoming webhook in apps |
| Email | Configure SMTP server credentials |
### Error Handling
The monitoring system handles:
- **API rate limiting** (429): Exponential backoff with `Retry-After` header
- **Missing artifacts**: Retry 3x with 10s delay, then fail gracefully
- **Network timeouts**: Retry up to 3 attempts with increasing timeout
- **Invalid tokens**: Clear error message with validation hint
### Workflow Integration
When enabled in a repository, the workflow automatically:
1. Runs lint on PRs or manual trigger
2. Uploads `lint-report.json` as artifact
3. Can be monitored externally via the `monitor` command
4. Sends notifications when results are ready
See [Enabling a New Project for Support](#enabling-a-new-project-for-support) to set up monitoring in your repository.
```
don't have the plugin yet? install it then click "run inline in claude" again.