PSKit

Neural-safe PowerShell automation for AI agents

CI PyPI Python 3.11+ License: MIT

PSKit is a Model Context Protocol server that gives AI agents 38 PowerShell tools backed by a 5-tier neural safety pipeline. Every command passes through a KAN (Kolmogorov-Arnold Network) neural scorer before execution — catching dangerous patterns in under 1 millisecond.

Works on Windows, Linux, and macOS with any MCP-compatible client: Claude Desktop, Claude Code, Cursor, Windsurf, Continue.dev, and more.

---

Install

Recommended — no virtual environment needed

uvx pskit-mcp

With pip

pip install pskit-mcp

With HTTP transport (for shared/remote use)

pip install "pskit-mcp[http]"
pskit serve --http --port 8000

Platform support

OS	Install PowerShell 7	Notes
Windows 10/11	ships pre-installed or winget install Microsoft.PowerShell	full feature set
Ubuntu / Debian	Microsoft apt repo → sudo apt-get install powershell	✅
Fedora / RHEL	sudo dnf install powershell (after MS repo setup)	✅
Arch Linux	yay -S powershell-bin	✅
macOS	brew install --cask powershell	✅

On Linux and macOS the system-info tools use native POSIX sources: /proc/meminfo (Linux) or sysctl+vm_stat (macOS) for memory, df for disks, ss -tlnp (Linux) or lsof (macOS) for open ports. Package installer auto-detects apt, dnf, pacman, and brew alongside pip, npm, cargo, and winget.

---

Quick Start

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows), ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), or ~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "pskit": {
      "command": "uvx",
      "args": ["pskit-mcp"],
      "env": {
        "PSKIT_ALLOWED_ROOT": "/home/you/projects"
      }
    }
  }
}

Replace PSKIT_ALLOWED_ROOT with your project root: C:\Your\Projects on Windows, /home/you/projects on Linux, /Users/you/projects on macOS.

Claude Code

claude mcp add pskit -- uvx pskit-mcp

Verify it works

pskit doctor

PSKit Doctor
+---------------------------+------+------------------------------------------+
| PowerShell (pwsh)         |  OK  | PowerShell 7.5.0                         |
| git                       |  OK  | git version 2.47.1                       |
| ripgrep (rg)              |  OK  | ripgrep 14.1.0 -- fast search active     |
| nvidia-smi                | WARN | not found -- gpu_status returns error    |
| Ollama                    |  OK  | running at localhost:11434               |
| Allowed root              |  OK  | /home/you/projects/myapp  (or C:\... on Windows)  |
| KAN model                 | WARN | no trained weights -- heuristic active  |
+---------------------------+------+------------------------------------------+

---

What AI Agents Can Do

Once connected, an agent can autonomously work across your entire project:

# Map the project structure
find_files("*.py", max_results=50)
list_directory("src/")

# Read, search, and edit files precisely
read_file("src/auth.py")
search_code("TODO", include="*.py", context=3)
edit_file("src/auth.py",
    old_text="def login(user):",
    new_text="def login(user: str) -> bool:")

# Full git workflow
git_status()               # branch, changes, ahead/behind
git_diff(staged=True)
git_commit("feat: add type hints to auth module")
git_push()

# Run builds and tests with structured results
result = build_project()
# { success: true, exit_code: 0, stdout: "...", duration_ms: 4821 }

result = test_project(filter_expr="test_auth")
# { success: true, passed: 12, failed: 0, skipped: 2, duration_ms: 1203 }

# System and network inspection
disk_usage()               # { drive: "C", free_gb: 142.3, total_gb: 476.9 }
port_status("8080,11434,5432")          # which services are listening
http_request("http://localhost:8000/health")  # localhost only

# Check and install dependencies
which("rg")                # { found: true, version: "14.1.0" }
install_package("requests", manager="pip")

---

Safety Pipeline

Every command passes through 5 tiers before execution:

 Command Input
      |
      v
+---------------------------------------------+
|  Tier 1 . Result Cache                      |
|  SHA-256 keyed . 30s TTL . 128 LRU entries  |
|  Read-only hits served instantly            |
+--------------------+------------------------+
                     | miss
                     v
+---------------------------------------------+
|  Tier 2 . KAN Neural Scorer                 |
|  24 features . Kolmogorov-Arnold Network    |
|  Sub-millisecond risk classification        |
+--------------------+------------------------+
                     |
                     v
+---------------------------------------------+
|  Tier 3 . Dangerous Command Blocklist       |
|  Hard-blocks: Format-Volume, rm -rf,        |
|  mass deletion, privilege escalation        |
+--------------------+------------------------+
                     |
                     v
+---------------------------------------------+
|  Tier 4 . Path Safety Check                 |
|  Enforces PSKIT_ALLOWED_ROOT boundary       |
|  Blocks writes outside project root         |
+--------------------+------------------------+
                     | elevated only
                     v
+---------------------------------------------+
|  Tier 5 . Gemma LLM Review (optional)       |
|  Ollama-backed . Fail-open if offline       |
|  Deep semantic analysis of intent           |
+--------------------+------------------------+
                     |
                     v
                Execute

---

KAN Neural Safety

PSKit uses a Kolmogorov-Arnold Network to score every command across 24 structural features before execution:

Feature Group	What It Detects
Structure	command length, pipe depth, semicolons, nesting
Dangerous patterns	Invoke-Expression, deletion flags, --force --recurse
Network	outbound requests, drive mappings, mail
Credentials	Get-Credential, SecureString, -Password parameters
Obfuscation	base64 encoding, variable expansion, string interpolation
Persistence	registry writes, scheduled task creation, service installs
Output	redirection, file output, compression

Unlike rule-based filters, KAN learns non-linear risk combinations. Scores 0.0 (safe) to 1.0 (dangerous) in under 1ms, acting as an always-on pre-filter before the optional Ollama LLM review.

---

Built-In Agent Workflows

PSKit ships 6 ready-to-use MCP prompts accessible from Claude's prompt library:

Prompt	What It Does
Audit Project	Full sweep: git state, structure, build, tests, system health
Review Changes	Pre-commit diff review with commit message suggestion
Diagnose Build	Systematic failure investigation with specific code fix
Orient to Project	First-session orientation before starting any work
Refactor File	Targeted single-file cleanup with stash safety net
Write Tests For	Generate tests following existing project conventions

Plus a pskit://guide resource Claude can read anytime for the complete tool reference, and a pskit://status resource for live server health.

---

Tools (38 total)

Category	Tools
File	read_file, read_file_range, write_file, edit_file, move_file, delete_file, create_directory, list_directory, diff_files
Search	search_code (ripgrep + context lines), find_files
Shell	run_command (safety-gated arbitrary PS with progress)
Environment	get_env_vars, which, install_package
Git	git_status, git_diff, git_log, git_commit, git_branch, git_checkout, git_push, git_blame, git_stash, git_stash_pop
System	gpu_status, disk_usage, memory_usage
Network	port_status, process_info, http_request (private IPs only)
Build	build_project, test_project (structured results with pass/fail counts)

All 38 tools return typed structured output with auto-generated JSON schemas. Annotated with readOnly, destructive, and idempotent hints so clients auto-approve safe operations and warn on destructive ones.

---

CLI

pskit serve           # Start MCP server on stdio (default)
pskit serve --http    # Start on streamable HTTP (port 8000)
pskit doctor          # System health check
pskit audit           # View recent command audit log with KAN scores
pskit version         # Print version

---

Configuration

Variable	Default	Description
PSKIT_ALLOWED_ROOT	Current directory	File writes sandboxed to this path
PSKIT_POOL_SIZE	3	Pre-warmed PowerShell session count
PSKIT_SAFETY_MODEL	gemma4:e2b	Ollama model for Tier 5 review
OLLAMA_BASE_URL	http://localhost:11434	Ollama endpoint

Or use pskit.config.toml in your project root:

[pskit]
allowed_root = "."
pool_size = 5
safety_model = "gemma3:4b"

---

Audit Log

Every command is logged to .pskit/audit.jsonl with KAN score, safety verdict, and duration:

pskit audit

PSKit Audit (last 50)
+---------------------+----------+-------+------+-------------------------------------+
| Time                | Verdict  |  KAN  |  ms  | Command                             |
+---------------------+----------+-------+------+-------------------------------------+
| 2026-04-06 15:42:11 | safe     | 0.023 |   18 | Get-PSKitGitStatus                  |
| 2026-04-06 15:42:14 | safe     | 0.031 |  247 | Read-PSKitFile 'src/auth.py'        |
| 2026-04-06 15:42:19 | caution  | 0.441 |  892 | Invoke-PSKitHttpRequest 'localhost' |
+---------------------+----------+-------+------+-------------------------------------+

  Total: 47  Blocked: 0  Avg KAN: 0.089  Avg ms: 124

---

Requirements

• Python 3.11+
• PowerShell 7.0+ — pwsh on PATH (download)
• PyTorch 2.0+ — for the KAN neural scorer
• ripgrep (optional) — faster file search when rg is on PATH
• Ollama (optional) — enables Tier 5 Gemma LLM safety review

---

Powered by Loom

PSKit was extracted from Loom, a multi-agent orchestration platform. Loom uses PSKit as its PowerShell execution layer.

---

Contributing

git clone https://github.com/Nickalus12/pskit
pip install -e ".[dev]"
python -m pytest tests/ -q    # 38 tests, no live PS session required
ruff check src/               # lint

See CLAUDE.md for architecture docs and the guide to adding new tools.

---

License

MIT (c) 2025-2026 Nickalus Brewer