# VibeBridge

<div align="center">

### A secure local bridge between Gemini Spark and your development workspace.

Give an AI agent controlled access to your **files, codebase, and terminal** without handing it unrestricted access to your machine.

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-2024--11--05-6E56CF.svg)](https://modelcontextprotocol.io/)
[![Tauri](https://img.shields.io/badge/Tauri-1.5-FFC131.svg?logo=tauri&logoColor=black)](https://tauri.app/)

</div>

---

## Overview

**VibeBridge** is a local runtime and desktop interface that exposes a developer's selected workspace to **Gemini Spark** through the **Model Context Protocol (MCP)**.

Think of it as a controlled execution layer:

- **Gemini Spark** handles reasoning and decides which tools it needs.
- **VibeBridge** performs those actions locally.
- **The security layer** keeps file operations inside the selected workspace.
- **The permission layer** lets the user control writes and command execution.

VibeBridge is **not an LLM or agent framework**. It is the local bridge that gives an external AI agent access to a real development environment.

## Why VibeBridge?

AI coding tools are most useful when they can actually work with a project: inspect files, search a codebase, modify source files, and run commands.

The problem is trust. Giving an AI unrestricted access to a computer is a bad security boundary.

VibeBridge is designed around a narrower model:

> **Expose one workspace, provide explicit tools, enforce a filesystem boundary, and keep sensitive actions behind permissions.**

### What it provides

| Capability | What VibeBridge does |
| --- | --- |
| 📁 Workspace access | Restricts filesystem operations to the selected project directory |
| 🔎 Code search | Lets the agent search files and inspect relevant source code |
| ✏️ File editing | Supports safe exact-match edits instead of blind overwrites |
| 🖥️ Command execution | Runs development commands with the workspace as the working directory |
| 🔐 Permission controls | Separates read, write, and execute operations |
| 🌐 MCP over HTTPS | Exposes the MCP server through a configurable tunnel |
| 🖥️ Desktop UI | Provides workspace selection, endpoint information, activity logs, and permission dialogs |

---

## Architecture

```mermaid
flowchart LR
    A[Gemini Spark] <-->|MCP / HTTPS| B[Public Tunnel]
    B <--> C[VibeBridge Runtime]

    C --> D[MCP Server]
    C --> E[Permission Manager]
    C --> F[Security Sandbox]
    C --> G[Activity Logger]

    F --> H[Filesystem Tools]
    F --> I[Terminal Executor]
    H --> J[(Selected Workspace)]
    I --> J
```

The main packages are separated by responsibility:

```text
VibeBridge
├── apps/
│   └── desktop/          # React + TypeScript + Tauri desktop UI
├── packages/
│   ├── mcp-server/       # MCP transport, server, tools and tunnel handling
│   ├── security/         # Workspace sandbox and permission policy
│   └── shared/           # Shared types, schemas and contracts
└── tests/                # Security, permission and integration tests
```

### Request flow

1. Gemini Spark connects to VibeBridge through the MCP endpoint.
2. VibeBridge validates the requested tool and its arguments.
3. Filesystem paths are resolved against the selected workspace.
4. Sensitive write/execute operations are passed through the permission policy.
5. The tool executes locally and returns a structured MCP response.
6. Activity is logged by the runtime.

---

## Security Model

Security is one of the core design goals of VibeBridge.

### Workspace sandbox

File operations are resolved against the canonical workspace path rather than relying on string-prefix checks. This is intended to prevent common traversal and symlink-escape scenarios.

### Permission tiers

| Tier | Tools | Typical policy |
| --- | --- | --- |
| **Read** | `list_files`, `read_file`, `search_files` | Can be auto-approved |
| **Write** | `create_file`, `edit_file`, `delete_file`, `move_file` | User approval recommended |
| **Execute** | `run_command` | User approval recommended |

Available permission modes are:

- `prompt` — ask before writes and command execution
- `auto_approve_read` — automatically allow reads, prompt for writes and execution
- `auto_approve_all` — automatically allow all actions
- `deny_writes` — read-only mode; reject writes and commands

### Safer file editing

`edit_file` works with an exact `old_text` match. If the expected text is not found, the edit fails instead of silently modifying the wrong location.

### Command limits

Command execution uses the selected workspace as `cwd`, supports configurable timeouts, and caps command output to reduce the impact of runaway processes or extremely large logs.

> **Important:** VibeBridge is a security boundary, not a guarantee that arbitrary AI-generated commands are safe. Review your tunnel configuration, permission mode, and commands before enabling broad access.

---

## MCP Tools

VibeBridge currently exposes eight tools:

| Tool | Purpose |
| --- | --- |
| `list_files` | List files and directories in the workspace |
| `read_file` | Read text files, optionally by line range |
| `search_files` | Search the workspace using text or regex |
| `create_file` | Create a new file |
| `edit_file` | Replace an exact text match in an existing file |
| `delete_file` | Delete a file or directory |
| `move_file` | Move or rename a file or directory |
| `run_command` | Execute a shell command from the workspace |

---

## Quick Start

### Prerequisites

- [Node.js](https://nodejs.org/) 18+
- [npm](https://www.npmjs.com/) 9+
- [ngrok](https://ngrok.com/) account and auth token when using the ngrok tunnel
- [Rust](https://rustup.rs/) and Cargo when building/running the native Tauri shell

### 1. Clone

```bash
git clone https://github.com/assishmoncs/vibebridge.git
cd vibebridge
```

### 2. Install dependencies

```bash
npm install
```

### 3. Configure the environment

```bash
cp .env.example .env
```

A minimal configuration looks like:

```env
PORT=3000
HOST=127.0.0.1
VIBEBRIDGE_WORKSPACE=/absolute/path/to/your/project

ENABLE_TUNNEL=true
TUNNEL_PROVIDER=ngrok
NGROK_AUTHTOKEN=your_ngrok_auth_token

PERMISSION_MODE=prompt
```

### 4. Build the project

```bash
npm run build
```

### 5. Run VibeBridge

For the desktop development UI:

```bash
npm run dev:desktop
```

For the server/runtime:

```bash
npm start
```

Or run the Tauri desktop shell:

```bash
npm run tauri dev
```

Once the runtime is running, use the MCP endpoint shown by VibeBridge to connect Gemini Spark.

---

## Tunnel Configuration

VibeBridge supports a pluggable tunnel configuration through environment variables.

### ngrok

```env
ENABLE_TUNNEL=true
TUNNEL_PROVIDER=ngrok
NGROK_AUTHTOKEN=your_ngrok_auth_token
```

VibeBridge can then expose the local MCP server through an HTTPS endpoint suitable for a remote client.

### Direct mode

The environment configuration also supports a `direct` tunnel provider when the surrounding network setup already provides the required connectivity.

---

## Development

### Useful commands

| Command | Purpose |
| --- | --- |
| `npm install` | Install workspace dependencies |
| `npm run build` | Build all workspace packages |
| `npm test` | Run the test suite |
| `npm run dev:desktop` | Start the desktop frontend in development mode |
| `npm run dev:server` | Start the MCP server workspace |
| `npm start` | Start the built MCP server |
| `npm run tauri dev` | Run the native Tauri desktop app |

### Testing

```bash
npm test
```

The repository includes tests for permission handling, filesystem/security behavior, editing, command execution, and MCP-related integration behavior.

---

## Project Status

VibeBridge is currently at **v0.1.0** and is actively evolving.

### Implemented

- [x] Streamable HTTP MCP transport
- [x] Workspace-scoped filesystem sandbox
- [x] Canonical path / symlink escape checks
- [x] Exact-match file editing
- [x] Command execution with timeout and output limits
- [x] Permission management for read, write, and execute operations
- [x] React + Tauri desktop interface
- [x] Configurable HTTPS tunnel provider

### Planned

- [ ] Visual Git diff inspection
- [ ] Cloudflare Quick Tunnel support
- [ ] Workspace indexing and symbol search
- [ ] Further desktop UX improvements

---

## Contributing

Contributions are welcome.

A good starting point is to keep changes focused within the existing package boundaries:

- `apps/desktop` for the UI
- `packages/mcp-server` for MCP/runtime behavior
- `packages/security` for sandboxing and permission logic
- `packages/shared` for shared contracts and schemas

Before opening a pull request, run:

```bash
npm test
npm run build
```

---

## License

VibeBridge is released under the [MIT License](LICENSE).

---

<div align="center">

**VibeBridge** — controlled local execution for AI-powered development.

</div>