Pylinter Assist

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):

# 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:

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)

# macOS/Linux
brew install node  # or your preferred package manager
Or download from https://nodejs.org/

clawhub CLI (OpenClaw skill installer)

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

Installation via ClawHub

Install the skill using the ClawHub CLI:

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:

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

# 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):

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):

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 with the exact commit you reviewed on GitHub:

# Find the commit SHA: https://github.com/claytantor/pylinter-assist/commits/main
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:

cp /path/to/pylinter-assist/.linting-rules.yml .linting-rules.yml

Step 4: Set Repository Permissions

Ensure your repository has these permissions enabled:

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:

# 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 
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:

permissions:
  contents: read
  pull-requests: write
  issues: write

Usage

# Activate venv first
source .venv/bin/activate
lint-pr [TARGET] [OPTIONS]

Targets

| Target | Description | |--------|-------------| | pr | Lint all files changed in a GitHub PR | | staged | Lint git-staged files | | diff | Lint files from a unified diff file | | files ... | Lint explicit files or directories |

Examples

# 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 | 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:

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

Manual Trigger Examples

GitHub CLI (preferred — token is handled by gh auth, not exposed in shell):

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.

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

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:

# 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:

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:

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:

# 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.

# 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:

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

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:

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 to set up monitoring in your repository. ```

# 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 | 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) |

Copy .linting-rules.yml to your project root and customize:

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

command not found: lint-pr after installation

The lint-pr CLI is installed inside the virtual environment. Either activate it or call it directly:

# 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:

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:

python -m venv .venv
source .venv/bin/activate
pip install -e .