SysClaw Reporting (Client)

Report issues and submit requests to SysClaw. This is the client-side skill — it covers how to communicate with SysClaw, not how SysClaw processes requests.

Prerequisites

1. Install Python dependency

CODEBLOCK0

2. Set environment variables

Set these before running scripts. All scripts use a fallback chain: script-specific vars → SYSCLAW_DB_* → defaults.

CODEBLOCK1

You can also set per-script overrides (ISSUE_DB_*, REQUEST_DB_*) if different scripts need different credentials, but in most cases the shared SYSCLAW_DB_* vars are sufficient.

Ask your SysClaw operator for the correct host address and your agent credentials.

Report an Issue

For errors, warnings, and problems that need attention:

CODEBLOCK2

Severity: info | warning | critical
Categories: disk | service | error | resource | network | config | INLINECODE13

Examples:
CODEBLOCK3

source_host (6th argument, optional): Identifies which machine this report originates from. Defaults to the current hostname if omitted.

Request Something from SysClaw

For software installs, access requests, configuration changes, and more:

CODEBLOCK4

Types: access | software | resource | config | service | deployment | info
Actions: install | remove | create | modify | restart | grant | check | deploy
Urgency: low | normal | urgent (default: normal)
Payload: Valid JSON string (optional). Validated before submission.

Examples

CODEBLOCK5

What Happens Next

1. 1. Your request is submitted and SysClaw is automatically notified
2. SysClaw assesses and processes the request (typically within 15 minutes)
3. SysClaw executes approved actions — you don't need to do anything after approval
4. You receive a notification with the result (e.g., "DONE: nginx installed and running")

Verdicts:

• - approved + DONE — SysClaw completed the work, see notification for details
• INLINECODE35 — see notification for reason
• INLINECODE36 — human operator reviewing, you'll be notified when decided

Check Notifications

Check for responses from SysClaw:

CODEBLOCK6

Workflow:

1. 1. Run check-notifications.sh at session start or after submitting a request
2. Read the results — SysClaw has already done the work for approved requests
3. Mark as read when done

Automatic Notification Checking

Set up a cron job so responses are ready when your session starts:

CODEBLOCK7

Then at session start: INLINECODE38

Direct SQL (Alternative to Scripts)

If you prefer direct database access:

CODEBLOCK8

Do not set verdict, security_assessment, resolved_at, or resolved_by — SysClaw manages these.

Post-Install

1. 1. TOOLS.md — Add DB host, user, and connection details
2. Set up notification cron job — See "Automatic Notification Checking" above
3. Test:

Technical Notes

• - Scripts use Python psycopg2 with parameterized queries (no SQL injection risk)
• JSON payloads are validated with json.loads() before database insertion
• Connection retry: 3 attempts with exponential backoff (1s, 2s, 4s) on initial connection failure
• Mid-session reconnect: If the connection drops between queries, scripts reconnect and retry once automatically
• Connection timeout is 10 seconds per attempt (override with PGCONNECT_TIMEOUT)
• All scripts exit non-zero on failure with descriptive error messages