container-dashboard/
├── index.ts       # Entry point, permission gates, lifecycle hooks
├── runtime.ts     # Runtime detectio

n (docker → podman → nerdctl), CLI abstraction ├── commands.ts # /docker:* slash commands with formatted output ├── tools.ts # 13 LLM tools registered via TypeBox schemas └── widget.ts # Live TUI sidebar widget

### Runtime Detection: Auto-Discovery
The system probes available container engines in priority order, caching version strings for UI display:

```typescript
const RUNTIMES = ["docker", "podman", "nerdctl"] as const;

export async function detectRuntime(pi: ExtensionAPI): Promise<RuntimeState> {
  for (const runtime of RUNTIMES) {
    try {
      const result = await pi.exec(runtime, ["--version"], { timeout: 3000 });
      if (result.code === 0 && result.stdout) {
        return { runtime, version: result.stdout.trim(), available: true };
      }
    } catch {
      continue;
    }
  }
  return { runtime: null, version: "", available: false };
}

Cross-Runtime Compatibility & JSON Normalization

All lifecycle functions (listContainers, getContainerLogs, pruneSystem, getContainerStats) abstract CLI differences. The extension executes docker ps --format '{{json .}}', normalizes status fields, and maps Podman/Nerdctl schema variations to a unified internal model. This ensures LLM tool calls receive consistent, predictable payloads regardless of the underlying engine.

Safety-First Permission Gates

Destructive operations are intercepted using pattern matching before execution:

const dangerousPatterns = [
  /(?:docker|podman|nerdctl)\s+(?:rm|container\s+rm)\s+-f/i,
  /(?:docker|podman|nerdctl)\s+system\s+prune\s+-a/i,
  /(?:docker|podman|nerdctl)\s+stop\s+\$\(docker\s+ps\s+-aq\)/i,
  // ...
];

When a match occurs, the extension triggers a confirmation dialog. The AI agent must explicitly receive user approval before proceeding, eliminating autonomous infrastructure destruction.

LLM Tool Registration & Slash Commands

13 tools (container_ps, container_stats, container_logs, container_prune_system, etc.) are registered using TypeBox schemas for runtime validation. 14 slash commands (/docker:ps, /docker:logs <name>, /docker:inspect <name>) render colorized, padded terminal tables instead of raw JSON:

 Containers

CONTAINER ID   NAME                IMAGE                    STATUS      PORTS
a1b2c3d4e5f6   my-postgres         postgres:16              ▶ running   5432→5432
b2c3d4e5f6a7   redis-cache         redis:7-alpine           ▶ running   6379→6379
c3d4e5f6a7b8   old-test-container  node:18                  ● exited    —

Smart Inspect Parsing

/docker:inspect extracts critical configuration bits (ports, env vars, mounts, IP, command) from the raw JSON dump, presenting a structured summary optimized for both human review and LLM context windows.

Pitfall Guide

1. Blind AI Execution: Granting LLMs unrestricted CLI access without confirmation gates leads to catastrophic state loss. Best Practice: Implement regex-based interception for destructive patterns and enforce explicit user approval before execution.
2. Hardcoded Runtime Assumptions: Tying agent logic to a single engine (e.g., Docker) breaks compatibility in Podman/Nerdctl environments. Best Practice: Use priority-based auto-discovery with graceful fallback and unified CLI abstraction.
3. Raw JSON Overload: Feeding unstructured inspect or ps output directly to LLMs increases token usage and parsing errors. Best Practice: Normalize outputs server-side, extract only actionable fields, and return structured summaries.
4. Missing Permission Boundaries: AI agents require explicit safe/unsafe pattern definitions. Best Practice: Maintain a centralized allowlist/denylist registry and validate all tool parameters via runtime schema validation (e.g., TypeBox).
5. Stale State Synchronization: Relying on on-demand commands causes drift between actual container state and AI context. Best Practice: Implement a live TUI widget with periodic polling or event-driven updates to maintain real-time visibility.
6. Over-Aggressive Pruning Automation: Autonomous cleanup without scope limits can delete active images or CI caches. Best Practice: Restrict prune operations to stopped containers by default, require --images or --all flags explicitly, and enforce confirmation dialogs.

Deliverables

• 📐 Architecture Blueprint: Complete TypeScript module breakdown with dependency graph, CLI abstraction layer design, and TypeBox schema mapping for LLM tool registration.
• ✅ Safety & Permission Checklist: Step-by-step verification guide for implementing destructive command interception, runtime detection fallbacks, and confirmation dialog workflows.
• ⚙️ Configuration Templates: Ready-to-use pi install commands, local extension loading scripts, and environment-specific runtime priority overrides (Docker → Podman → Nerdctl).
• 📊 LLM Tool Schema Registry: Pre-validated TypeBox definitions for all 13 container management tools, including parameter constraints, return type schemas, and error handling patterns.