Tools.AIBridge 1.0.6

AI Bridge — Usage Guide

A no-agent, no-extension workflow for applying AI-generated code changes to any project directly from your browser using the ai-bridge .NET Global Tool.

Works with any language or technology — .NET, Node.js, Python, React, or any project with a sensible folder structure.

The Big Picture

Your Project
    │
    ▼
[1] ai-bridge init  ──►  Scaffolds .aiignore, aiSkills/, aiPrompts/
    │
    ▼
[2] ai-bridge pack  ──►  aiArtifacts/*-context.txt
                                    │
                                    ▼
                         [3] Paste into Browser AI
                             (ChatGPT / Claude / Gemini)
                                    │
                             Ask for changes
                                    │
                                    ▼
                         [4] Save AI response
                             ──► aiArtifacts/ai-response.xml
                                    │
                                    ▼
                         [5] ai-bridge apply
                                    │
                                    ▼
                             Code lands in your project ✅

Prerequisites

• .NET 10 SDK installed on your machine.
• Git installed and on your PATH (the target project must be a git repo). AI Bridge uses git ls-files to automatically respect your .gitignore rules.
• A browser AI account: ChatGPT, Claude, or Gemini

Installation

Install the tool globally using the .NET CLI. Once installed, the ai-bridge command is available in any terminal window.

dotnet tool install --global Tools.AIBridge

(Note: If installing locally during development, use dotnet tool install --global --add-source ./AIBridge/bin/Release/ Tools.AIBridge).

Uninstallation

To remove the global tool from your machine:

dotnet tool uninstall --global Tools.AIBridge

Updating the Tool

To update the tool to the latest version from NuGet:

dotnet tool update --global Tools.AIBridge

Supported Ecosystems

AI Bridge automatically detects your project type and groups files intelligently:

Root-level files (e.g., docker-compose.yml, README.md) are always packed into a *-Solution-context.txt file.

Step 1 — Initialize Your Workspace

Open your terminal, navigate to your project directory, and run the init command.

cd D:\Code\Github\you\your-project
ai-bridge init

What it does:

1. Creates a .aiignore file for custom exclusion rules.
2. Extracts default AI skills and prompts to the aiSkills/ and aiPrompts/ folders.
3. Patches your .gitignore so these folders aren't checked into source control.
4. Creates the aiArtifacts/ folder and placeholder ai-response.xml.

Note: Running init is completely safe. It will never overwrite your files if you have customized the skills or prompts locally. If you want to pull down the newest default templates after updating the tool, you can run ai-bridge update to overwrite your local templates.

Step 2 — Pack Your Project Context

Once initialized, run the pack command to build your context file.

ai-bridge pack

What it does:

1. Uses git ls-files to determine which files to include — automatically respects all .gitignore rules (nested, negation, global).
2. Filters out binary files (images, fonts, executables, archives, etc.) so only source code and config are packed.
3. Applies .aiignore rules for any additional exclusions you define.
4. Groups files by project based on ecosystem detection.

Output: One *-context.txt file per project layer, saved to aiArtifacts\:

aiArtifacts\
    YourApp.WebApi-context.txt
    YourApp.DataProvider-context.txt
    YourApp.SharedContracts-context.txt
    YourApp-Solution-context.txt

Tip: You don't always need to upload all files. If you're only changing the API layer, just upload YourApp.WebApi-context.txt.

File Filtering

AI Bridge uses a layered approach to decide which files to pack:

Tip: If the packed context includes files you don't need, add your own rules to .aiignore and run ai-bridge pack again to regenerate the context files.

Fallback: If git is not available, AI Bridge uses built-in exclusion rules (common folders like bin/, obj/, node_modules/, etc.).

Step 3 — Give Context to the AI

1. Open your browser AI (ChatGPT, Claude, or Gemini).
2. Set the System Prompt — paste the contents of aiSkills/ai-system-prompt.md into the system / custom instructions area. You only need to do this once per chat session.
3. Upload the context file(s) — attach the relevant *-context.txt file(s) from aiArtifacts\.
4. Describe what you want — ask the AI to add a feature, fix a bug, refactor code, delete files, etc.

Step 4 — Apply the AI Response

The AI will respond with a valid XML document. AI Bridge performs strict validation on this response (ensuring only valid <file>, <patch>, or <delete> tags are present).

Once the AI generates the response, you have two ways to apply it to your project:

Option A: Direct Clipboard Paste (Easiest & Fastest ✨)

You don't even need to save a file! Simply select the entire AI response in your browser and copy it (Ctrl+C). Then, inside your project directory, run the apply command with the --paste flag:

ai-bridge apply --paste

This reads the AI's XML directly from your clipboard and applies the code changes instantly.

Option B: Save to File

If you prefer saving the file (or if the AI provides a direct download option), save the response as ai-response.xml inside your aiArtifacts\ folder. Then run:

ai-bridge apply

What the tool does

1. Phase 1 — Applies <file> blocks (creates or overwrites full files).
2. Phase 2 — Applies <patch> blocks (targeted search-and-replace).
3. Phase 3 — Applies <delete> blocks (removes files).
4. Phase 4 — Cleans up any folders left empty after deletions.
5. Prints a summary of all changes made.

After the run

• If some patches failed → paths are saved to aiArtifacts\failed-patches.txt. Go back to the AI and ask:

  "Some patches failed for these files. Please give me full <file> blocks instead: [paste failed-patches.txt contents]"

Apply Options

Continuous Watch Mode (Recommended workflow):

ai-bridge apply --watch

Leave this running in a separate terminal. Every time you paste an AI response into ai-response.xml and save, your code is updated automatically.

Dry-run example:

ai-bridge apply --dry-run

Output:

  CREATE: MyApp/Services/NewService.cs
  OVERWRITE: MyApp/Controllers/OrderController.cs
  PATCH: MyApp/Models/Order.cs
  DELETE: MyApp/Services/OldService.cs

Dry run complete: 2 file(s), 1 patch(es), 1 delete(s).
No files were modified. Run 'ai-bridge apply' to apply for real.

System Prompt

The AI needs a system prompt so it responds in the correct XML format that ai-bridge apply understands. After running ai-bridge pack, you'll find the system prompt at:

aiSkills/ai-system-prompt.md

Setup (one-time per AI chat session):

1. Open aiSkills/ai-system-prompt.md in any text editor.
2. Copy the entire contents of the file.
3. Paste it into your browser AI's system instructions:
   • ChatGPT: Settings → Personalization → Custom Instructions (top box)
   • Claude: Start a new Project → Project Instructions
   • Gemini: System instructions (in Gemini Advanced / API settings)

What it generates in your project

When you run ai-bridge init, it sets up these folders:

YourProjectRoot\
├── .aiignore                   ← Additional ignore rules (works alongside .gitignore)
├── aiSkills\                   ← Auto-created, gitignored
│   ├── ai-system-prompt.md     ← System prompt for your browser AI
│   └── ai-response-skill.md    ← Code modification protocol
├── aiPrompts\                  ← Auto-created, gitignored
│   └── ...                     ← Additional prompt templates
└── aiArtifacts\                ← Auto-created, gitignored
    ├── *-context.txt           ← Output of ai-bridge pack
    ├── ai-response.xml         ← AI response you paste/download here
    └── failed-patches.txt      ← Created only when patches fail

Troubleshooting

ai-bridge is not recognized as a command

Symptom:

ai-bridge: The term 'ai-bridge' is not recognized as the name of a cmdlet, function, script file, or executable program.

Cause: .NET global tools are installed to %USERPROFILE%\.dotnet\tools, which should be on your PATH. This entry can go missing after a Windows Update, .NET SDK update, or environment refresh — even though the tool itself is still installed and intact.

Fix: Run the following in PowerShell to permanently restore the entry to your user PATH:

[System.Environment]::SetEnvironmentVariable(
    "PATH",
    ([System.Environment]::GetEnvironmentVariable("PATH", [System.EnvironmentVariableTarget]::User) + ";$env:USERPROFILE\.dotnet\tools"),
    [System.EnvironmentVariableTarget]::User
)

Then restart your terminal. The command should work again.