AI Swissknife (VS Code Extension)

AI Swissknife is a universal cross-assistant package manager, marketplace browser, format translator, and structured editor for AI coding environments: Claude Code, Kilo Code, GitHub Copilot, OpenAI Codex CLI, and Google Gemini CLI.

It lets developers and AI agents register custom repositories, browse and preview catalogs, translate components losslessly across assistants, install them transactionally with full rollback safety, visually author them via a structured Form Editor, synchronize components across scopes and tools, detect local drift, track provenance, and monitor the entire AI tooling estate through an interactive Dashboard or a dedicated CLI.

Table of Contents

• Why AI Swissknife?
• Supported Artifacts & Locations
• Supported Source Types
• User Guide & Features Walkthrough
  • 1. Activity Bar Sidebar Views
  • 2. Visual Management Dashboard
  • 3. Structured Form Editor
  • 4. Transactional Install Engine & Rollback
  • 5. Cross-Assistant Translation & Sync
  • 6. Drift Detection, Provenance & Update All
  • 7. Unmanaged Discovery & Safe Promotion
  • 8. Trash Safety & Soft-Delete
  • 9. Non-Destructive Demarcated Rule Merges
• CLI Reference for AI Agents & Terminal Automation
  • CLI Invocation
  • Commands Overview
  • Multi-Root Workspace Scanning & Shadowing
• Extension Configuration & Commands
• Persistence Architecture
• Development & Verification

Why AI Swissknife?

When working across multiple AI coding assistants, configuration and tooling quickly fragment:

• Disparate Directory Conventions: Skills live in .claude/skills/ for Claude, .kilo/skills/ for Kilo, and .github/skills/ for Copilot.
• Incompatible Schemas: Claude defines agent tool permissions via tools: [...], whereas Kilo uses fine-grained permission: {...} blocks. Prompt and command templates vary from Markdown with YAML frontmatter to TOML descriptors.
• Configuration Sprawl & Drift: Developers customize skills locally, losing track of whether local copies have diverged from upstream git repositories.
• Shadowing & Duplicate Conflicts: Multiple copies of the same skill or prompt reside across global folders and nested project repositories without visibility into which version is active.

AI Swissknife solves these challenges by establishing a single, unified control plane that treats all AI assistant artifacts as first-class package objects.

Supported Artifacts & Locations

AI Swissknife manages artifacts across two distinct scopes:

• Workspace Scope (project): Local to the current repository or workspace folder (e.g. .<assistant>/...).
• Global Scope (global): Installed machine-wide in your user home directory (e.g. ~/.<assistant>/...).

Supported Source Types

Register source repositories and catalogs through any of the supported formats:

1. local-folder: Local directory containing skills, agents, commands, or MCP servers. Automatically ignores build directories, virtual environments (venv, .venv), and archive folders (_attic, _deprecated).
2. git-custom: Any Git repository accessible over HTTPS or SSH, with optional pinning by branch, tag, or specific commit SHA.
3. git-marketplace: Plugin marketplace repositories implementing .claude-plugin/marketplace.json or marketplace-skills.json.
4. git-single-item: Standalone Git repositories where the root directory itself represents a single skill or tool.
5. remote-url: Direct HTTP(S) raw URLs pointing to standalone component descriptors or gists.

User Guide & Features Walkthrough

1. Activity Bar Sidebar Views

Click the AI Swissknife icon in the Activity Bar to open the three integrated Tree Views:

AI Swissknife (Activity Bar)
├── 📁 Sources      Manage registered global and workspace source catalogs
├── 📦 Available    Browse downloadable artifacts with folder hierarchy & batch actions
└── ✅ Installed    Inspect installed components grouped by assistant & kind

• Sources View:
  • Shows registered sources divided into Global and Workspace sections.
  • Add Source Wizard (+): Interactive prompt sequence: Select Source Type → Scope (Global, Workspace, or Both) → Location/URL → Auto-derived ID & Name → Optional Git Branch/Tag Pin.
  • Single-Source Refresh: Click ⟳ on any source to refresh only that source with an active loading indicator.
  • Combined Removal Dialog: Deleting a source with installed items prompts you to choose between "Uninstall All Items & Remove Source" or "Remove Source Only".
• Available View:
  • Displays artifacts organized by source and folder hierarchy.
  • Shows visual badges indicating where an artifact is already installed.
  • Direct actions: 👁 Preview file content before install, ⬇ Install to chosen assistants/scopes, or ⬇ Install All in Folder / Source.
• Installed View:
  • Hierarchical view grouped by Assistant (Claude Code, Kilo Code, etc.) and Scope (Global, Workspace), then grouped by kind (Skills, Agents, Commands, MCP Servers).
  • Items display status badges: link, broken-link, orphan, duplicate, drift, or held.
  • Actions on hover: 👁 Preview, ⇄ Diff vs. Original, ⟳ Update, ⇧ Promote, and 🗑 Uninstall.

2. Visual Management Dashboard

Open the Dashboard via the Command Palette (AI Swissknife: Open Dashboard), the status bar badge, or the Dashboard button in the sidebar.

Key Dashboard Capabilities:

• Metric Cards:
  • Total Objects: Total unique AI tools managed across all assistants.
  • Updates Available: Count of outdated items; click to trigger Update All.
  • Unmanaged Items: Discovered local tools not yet tracked; click to filter or trigger Promote All Identical.
  • Missing on Disk: Ghost items registered in state but removed from disk; click to Prune Registry.
• Collapsible Object Tree:
  • Collapses multi-assistant installations into a single parent row per object with an environment icon strip showing where it is deployed.
  • Displays the worst drift status across all copies on the parent row.
  • Expands to reveal individual place sub-rows with instant inline actions (Preview, Diff, Update, Uninstall).
• Interactive Pill Filters:
  • Filter simultaneously by Scope (All, Global, Workspace), Assistant (Claude, Kilo, Copilot, Codex, Gemini), Kind (Skill, Agent, Command, MCP), and Status (All, Up-to-date, Update Available, Modified Locally, Unmanaged).
• Expand / Collapse All:
  • One-click toolbar buttons to expand or collapse every object row, with persistent state across data refreshes.
• Sticky Detail Panel:
  • Clicking any item docks a detailed inspection panel at the bottom of the viewport showing:
    • Complete provenance: Source ID, repository URL, source commit SHA, and local file path.
    • Drift explanation: Clear English diagnostic explaining whether files differ and why.
    • Direct actions: Side-by-side Diff, Preview, Copy/Move to Another Assistant, Hold from Update All (Pin), and Delete / Soft-delete.

3. Structured Form Editor

Create or modify artifacts visually without manually editing raw YAML frontmatter or JSON schemas:

1. Run AI Swissknife: Create New Artifact from the Command Palette or click 📝 Form Editor.
2. Select the artifact kind: Skill, Agent, Command, or MCP Server.
3. Choose the target Assistant and Scope.
4. Fill in structured fields:
   • Agents: Edit system prompts, primary vs. subagent modes, select model aliases, and configure tool permissions.
   • Skills: Define name, description, parameters, and authoring guidelines.
   • Commands: Configure prompt arguments and execution targets.
   • MCP Servers: Configure command executable, arguments, environment variables, and auto-start rules.
5. Click Save — the engine validates syntax, builds the target structure, and transactionally stages the file.

4. Transactional Install Engine & Rollback

Every installation executes through a 5-stage transactional pipeline:

Resolve Source ──► Generate Plan ──► Interactive Preview ──► Atomic Staging ──► Verification
                                                                    │
                                                        (On Failure: Auto Rollback)

• Atomic Staging: Files are assembled in a temporary staging directory before touching target locations.
• SHA-256 Verification: Checksums are computed and stored in machine-local state.json.
• Automatic Rollback: If any file write fails, previous states are restored cleanly without partial corruption.

5. Cross-Assistant Translation & Sync

AI Swissknife transparently translates components between assistant ecosystems:

• Claude Code ↔ Kilo Code:
  • Converts Claude tools: [bash, edit, read] into Kilo permission: { bash: "allow", edit: "allow", read: "allow" } and vice versa.
  • Bridges command schemas into strict Kilo E77 command formats.
• Copilot / Codex / Gemini:
  • Maps tool instructions into appropriate .github/, .codex/, or .gemini/ frontmatter formats.
• 1-Click Sync & Move:
  • Duplicate or migrate any component to another assistant or scope with the Copy to Another Assistant / Scope... or Move to Another Assistant / Scope... actions.

6. Drift Detection, Provenance & Update All

• Git Commit Provenance: Tracks the exact upstream Git commit SHA at install time.
• Drift Classification:
  • up-to-date: Installed content perfectly matches the latest upstream version.
  • update-available: Upstream has newer commits or changed content.
  • modified-locally: Local files were modified by the user.
  • modified-and-update-available: Both local edits and upstream updates exist.
  • source-unavailable / provenance-unknown: Source inaccessible or installed prior to provenance tracking.
• Adaptation Support (local.patch): Recognizes intentional assistant-specific edits (e.g. converting "Claude" to "Kilo") recorded in local.patch, preventing false drift warnings.
• Update All & Pinning (Hold):
  • Run Update All... from the command palette or dashboard.
  • Locally modified items are safely skipped by default (or backed up to trash if overwritten).
  • Use Hold (aiSwissknife.holdItem) on any item to pin its version and exclude it from bulk updates.

7. Unmanaged Discovery & Safe Promotion

If you create skills or agents manually or receive them from colleagues:

1. AI Swissknife's background file watcher automatically detects the files in your assistant folders.
2. The engine scans registered sources to find matching originals:
   • identical: Perfect SHA-256 match with an upstream source.
   • differs: Same artifact name but contains differences.
   • local only: Unique local component with no upstream match.
3. Click Promote to Managed:
   • Single matching source: Instantly links the item and begins tracking updates.
   • Multiple matching sources: QuickPick prompt lets you select the canonical source.
   • Bulk Promotion: Click Promote N Identical Source Items in the Dashboard to promote all exact matches in one click.

8. Trash Safety & Soft-Delete

Accidental file deletion is eliminated:

• When you uninstall a component or overwrite locally modified files during an update, AI Swissknife moves the previous version to the .ai-swissknife/trash/ folder.
• Restore from Trash (aiSwissknife.restoreFromTrash): Restores any trashed component back to its original location.
• Empty Trash (aiSwissknife.emptyTrash): Permanently purges trashed files when no longer needed.

9. Non-Destructive Demarcated Rule Merges

When installing global or project rules into CLAUDE.md or AGENTS.md, AI Swissknife never overwrites custom instructions:

• Inserts managed sections bounded by comment markers:

  <!-- ai-swissknife:managed -->
  ... managed rules injected here ...
  <!-- ai-swissknife:managed -->
  

• Any personal instructions placed before or after the markers remain untouched.

CLI Reference for AI Agents & Terminal Automation

AI Swissknife includes a command-line interface (dist/cli.js) designed for terminal use, CI scripts, and headless AI agents.

CLI Invocation

# If installed in VS Code:
node ~/.vscode/extensions/alfredooliviero.ai-swissknife-*/dist/cli.js <command> [options]

# Or via npx / local repository build:
npx ai-swissknife <command> [options]
# or: node dist/cli.js <command> [options]

Core CLI Principles:

• Pure JSON Output on stdout: All structured data is emitted as clean JSON on stdout; logs and diagnostic messages go to stderr.
• Plan First, Write with --write: Write commands run in dry-run mode by default, printing an execution plan. Pass --write to apply changes.
• Code Kind Guard: Modifying hook or mcp-server kinds requires passing --allow-code-kinds.

Commands Overview

Multi-Root Workspace Scanning & Shadowing

Inspect tooling across multiple projects simultaneously with --roots:

# Check installed items across all workspaces in ~/works up to depth 3
node dist/cli.js installed --roots ~/works --max-depth 3

# Detect shadowing conflicts and local divergence across repositories
node dist/cli.js shadowing --roots ~/works --max-depth 3

Each copy is classified as:

• identical: Exactly matches the canonical version.
• stale: Behind upstream commits (commitsBehind).
• ahead: Contains local modifications on top of upstream (closestCommit).
• unique: Exists only locally.
• Deletion Guard: AI Swissknife refuses to delete an ahead or unique copy without explicit --force.

Extension Configuration & Commands

Settings (settings.json)

{
  // Toggle visible assistants in sidebar views and target pickers
  "aiSwissknife.enabledAssistants": {
    "claude-code": true,
    "kilo-code": true,
    "github-copilot": true,
    "codex-cli": true,
    "gemini-cli": true
  }
}

Contributed Commands

Persistence Architecture

AI Swissknife maintains clean separation between declarative intent and local machine state:

Workspace / Home Directory
├── .vscode/ai-swissknife/
│   ├── manifest.json       Shared, version-controlled intent (sources, recommendations)
│   └── state.json          Machine-local runtime registry (applied installs, SHAs, commits)
└── ~/.ai-swissknife/
    ├── manifest.json       Global user-wide sources & intent
    ├── state.json          Global runtime state & installation records
    ├── cache/sources/      Local Git cache directories protected by mutexes
    └── trash/              Soft-delete trash storage with provenance metadata

• manifest.json: Safe to commit to Git. Records desired sources and project-recommended artifacts.
• state.json: Git-ignored. Records applied installation records, content SHA-256 hashes, and upstream Git commits.
• trash/: Stores soft-deleted items with original paths and timestamps for safe restoration.

Development & Verification

Scripts

# Install dependencies
npm install

# Run typechecker
npm run typecheck

# Run linter
npm run lint

# Run automated test suite (639 tests covering all components)
npm test

# Build extension and CLI bundles via esbuild
npm run build

# Start standalone webview workbench for rapid UI development
npm run dev:ui

# Package VSIX extension bundle
npx @vscode/vsce package --no-dependencies

Manual Installation of VSIX

code --install-extension ai-swissknife-0.7.2.vsix

License

This project is licensed under the MIT License.

The Activity Bar icon utilizes the Lucide pocket-knife icon (ISC License). The Marketplace icon is an AI-generated illustration.