<div align="center">

[![فارسی](https://img.shields.io/badge/🌐-فارسی-blue?style=flat-square)](README.fa.md)

# OpenCOOP

![Version](https://img.shields.io/badge/version-1.16.0-blue)
![License](https://img.shields.io/badge/license-Non--Commercial-green)
![OpenCode](https://img.shields.io/badge/OpenCode-Plugin-purple)
![MCP](https://img.shields.io/badge/MCP-SSE-orange)
![Node](https://img.shields.io/badge/Node.js-18+-black)
![Users](https://img.shields.io/badge/Teams-tested%20at%2050%20users-red)

**Real-time team collaboration for OpenCode — a whole team on the same project.**

[Getting Started](#installation) • [Documentation](#features) • [Contributing](#contributing)

</div>

---

## What is OpenCOOP?

**Turn any device into a shared coding server. Your whole team codes together on ONE project — from anywhere in the world.**

OpenCOOP is an **OpenCode plugin** that lets multiple developers (each with their own AI assistant) work simultaneously on the **same project folder** hosted on **one machine**.

### How It Works (Simple!)

```
  YOUR LAPTOP (HOST)                    TEAMMATE'S LAPTOP (REMOTE)
  ┌──────────────────┐                  ┌──────────────────┐
  │  Your Project    │                  │  Teammate's      │
  │  /home/you/app   │◄──── INTERNET ───│  OpenCode + AI   │
  │                  │   (via tunnel)   │                  │
  │  OpenCOOP Server │                  │  OpenCOOP Plugin │
  │  Port 31313      │                  │  (proxies to you)│
  └──────────────────┘                  └──────────────────┘
        ▲                                        │
        │                                        ▼
        │                               Teammate's AI reads/writes
        │                               YOUR files in real-time!
        │
  Every change is LOGGED:
  ✅ Who changed what file
  ✅ Full diff (red/green view)
  ✅ Timestamp
```

### Real-World Example

1. **You** have a project on your laptop at `/home/you/my-app`
2. You open OpenCOOP web UI → select **HOST** → pick your folder → click **Generate Invite Link**
3. You send the link to your teammate (e.g., `https://abc123.tinyfi.sh/ui/invite/xyz`)
4. **Teammate** installs the plugin, pastes your link, clicks **Connect**
5. Now teammate's AI can **read, write, and edit YOUR project files** as if they were local!
6. You both see every change in the **Changes** page with **who made it** and a **visual diff**

**No Git push/pull. No screen sharing. No "send me the file". Just code together live.**

### Key Concepts

| Concept | Explanation |
|---------|-------------|
| **HOST** | The one device that holds the real project files. Shares them over the internet via a secure tunnel. |
| **REMOTE** | Any other device that connects to the host. Their AI works on the host's files as if local. |
| **Invite Link** | A secure URL the host generates. Contains the tunnel address + access token. Share it with teammates. |
| **Change Tracking** | Every file read/write/edit is logged with the user's name, timestamp, and full diff. |
| **File Locking** | Prevent two people from editing the same file at the same time (avoids conflicts). |

### Coming Soon 🚀

- **Admin Dashboard**: Manage team members, permissions, and access
- **Conflict Resolution**: Smart merge when two users edit the same lines

Teams of dozens work simultaneously with full audit trails. ("Up to 50" is the design
budget we test against, not an enforced seat limit — invites have no per-team cap.)

## Features

| Feature | Description |
|---------|-------------|
| 🔗 **Shared MCP Server** | Multiple OpenCode instances share the same project |
| 👥 **Team Scale** | Real-time collaboration with dozens of members; no seat limit in code |
| 📝 **Change Tracking** | Every file modification is logged with user attribution |
| 📸 **Auto Snapshots** | Every write/edit saves the previous version (last 20 per file, 2MB cap, binaries skipped) |
| ↩️ **One-Click Rollback** | Restore any file from Changes page, or let the AI undo its own mistakes via `rollback_file` |
| 🤖 **AI Self-Healing** | `opencoop_guide` teaches any model the rules; `rollback_file` lets it fix its own errors without human help |
| 💾 **Project-Local History** | All history lives in `<project>/.opencoop/` — survives restart, travels with the project, auto-gitignored |
| 🔒 **File Locking** | Prevents conflicts when multiple users edit the same file |
| 🌐 **Web Dashboard** | Beautiful UI for configuration and monitoring |
| 🔑 **Invite System** | Secure token-based team member invitations |
| 🛡️ **Sandbox Security** | Path traversal protection, symlink blocking, absolute path blocking, `.opencoop` store blocked from remote access, and input validation |
| 🌍 **Remote Access** | SSH tunnel (tinyfi.sh) — works behind NAT, firewall, or VPN |
| 📊 **Statistics** | View changes per user, recent activity, and more |
| 🔄 **Auto-Recovery** | Tunnel auto-reconnects, server auto-restarts on failure |
| 🔐 **Authenticated Remote Access** | Every tunnel/LAN request requires a token; local stays frictionless. Read/write/admin permissions enforced per call |
| 🛡️ **Hardened by Default** | Binds to 127.0.0.1, strict CORS + Host allowlist + CSRF guard, rate limiting, security event log, instant revocation |

## Security

OpenCOOP takes the shared-workspace boundary seriously (see [SECURITY.md](SECURITY.md)):

- **Local = trusted, Remote = token.** Your own OpenCode and browser connect
  over loopback and need no token. Anyone arriving through the public tunnel
  (or LAN when enabled) must present a valid token.
- **Invite redemption issues member tokens** (30 days). Permissions (`read`,
  `write`, `admin`) are enforced for every MCP tool call and API request, and
  re-checked against the team database on each request — revoking a member
  cuts access immediately.
- **The tunnel can never impersonate local.** The SSH tunnel connects to a
  local edge proxy that stamps public traffic with a per-process secret; the
  server refuses to treat stamped traffic as local even though it arrives
  from `127.0.0.1`.
- **The admin token never leaves the host** (localhost/admin views only).
- **The server binds `127.0.0.1` by default**; LAN exposure is opt-in via
  Settings and still requires tokens for non-local callers.

Found a vulnerability? Please follow the private reporting process in
[SECURITY.md](SECURITY.md). We credit responsible researchers.

## Installation

### Install via npm (Recommended)

```bash
npm install -g @opencoop/opencode-plugin
```

Then add to your `~/.config/opencode/opencode.json`:

**OpenCode V1** (`plugin` key):

```json
{
  "plugin": ["@opencoop/opencode-plugin"],
  "mcp": {
    "opencoop": {
      "type": "remote",
      "url": "http://localhost:31313/sse",
      "enabled": true
    }
  }
}
```

**OpenCode V2** (`plugins` key — same package, both generations supported):

```json
{
  "plugins": ["@opencoop/opencode-plugin"]
}
```

> OpenCOOP ships **dual V1 + V2 entry points**: one package works on both
> OpenCode generations. On V2 the plugin registers its tools through the
> Promise plugin API; no MCP block is needed.

### Install from GitHub

```bash
git clone https://github.com/Pajand/opencoop.git
cd opencoop
npm install
npm run build
npm link
```

Then add to your `~/.config/opencode/opencode.json`:

```json
{
  "plugin": ["opencoop"],
  "mcp": {
    "opencoop": {
      "type": "remote",
      "url": "http://localhost:31313/sse",
      "enabled": true
    }
  }
}
```

## Quick Start

1. **Install** the plugin (`npm install -g @opencoop/opencode-plugin`)
2. **Restart** OpenCode
3. **Open** `http://localhost:31313/ui` in your browser
4. **Select** HOST mode (project owner) or REMOTE mode (team member)

## Usage

### HOST Mode (Project Owner)

1. Select **HOST** mode in the web UI
2. Choose your **project folder**
3. Click **Generate Invite Link**
4. **Share** the link with your team

The invite link uses an **automatic SSH tunnel** via tinyfi.sh (`https://xxx.tinyfi.sh`), so team members can connect even behind NAT, firewall, or VPN.

### REMOTE Mode (Team Member)

1. **Install** the plugin on your machine
2. **Add** the MCP config to your `opencode.json`
3. **Restart** OpenCode
4. Open `http://localhost:31313/ui`
5. Select **REMOTE** mode
6. **Paste** the host's invite link
7. Click **Connect** — done.

Your local server now **proxies every tool call to the host** over its tunnel, so your AI reads/writes the **HOST's project folder live**.

### Automatic SSH Tunnel (Zero Setup)

When HOST mode is active, OpenCOOP automatically:

1. Opens an SSH reverse tunnel to `tinyfi.sh`
2. Forwards traffic to `http://localhost:31313`
3. Uses the public `https://xxx.tinyfi.sh` URL in all invite links

**Requirements:** Node.js 18+, OpenCode, and an SSH client (preinstalled on virtually all systems).

## MCP Tools

Once connected, your AI has access to 15 tools:

| Tool | Description |
|------|-------------|
| `read_file` | Read file contents from the shared project |
| `write_file` | Create or overwrite files |
| `edit_file` | Make targeted edits using search & replace |
| `list_files` | List directory contents |
| `search_files` | Search files by glob pattern |
| `grep_content` | Search file contents with regex |
| `directory_tree` | Get folder structure overview |
| `lock_file` | Acquire exclusive lock before editing |
| `unlock_file` | Release lock after editing |
| `view_changes` | View recent changes by team members |
| `view_stats` | View project statistics |
| `who_is_online` | See who is currently connected |
| `invite_member` | Generate invite link for new members |
| `list_members` | List all team members |
| `revoke_access` | Revoke a member's access |
| `opencoop_guide` | START HERE — AI calls this first; teaches the rules + confirmation question |
| `list_snapshots` | List saved previous versions of a file |
| `rollback_file` | Undo a mistake: restore a file (just path = undo last change) |

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        Team Members (any size)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Member A │  │ Member B │  │ Member C │  │ Member N │        │
│  │ OpenCode │  │ OpenCode │  │ OpenCode │  │ OpenCode │        │
│  │ + MCP    │  │ + MCP    │  │ + MCP    │  │ + MCP    │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
│       │              │              │              │              │
│       └──────────────┴──────────────┴──────────────┘              │
│                              │                                    │
│                    SSH Tunnel (tinyfi.sh)                         │
│                              │                                    │
│                              ▼                                    │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                    OpenCOOP MCP Server                      │  │
│  │  • SSE Transport (Server-Sent Events)                       │  │
│  │  • File Locking (prevent edit conflicts)                     │  │
│  │  • Change Tracking (user attribution)                        │  │
│  │  • Sandbox Security (path validation)                        │  │
│  │  • Web Dashboard (configuration UI)                          │  │
│  └──────────────────────────┬─────────────────────────────────┘  │
│                              │                                    │
│                              ▼                                    │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                  Shared Project Folder                       │  │
│  │  • Symlink protection                                       │  │
│  │  • Absolute path blocking                                   │  │
│  │  • Path traversal prevention                                 │  │
│  └────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

## AI Agent Instructions

**If you are an AI agent reading this, follow these exact steps to install and configure OpenCOOP:**

### Step 1: Install

```bash
which opencode || echo "OpenCode not found - user needs to install it first"
npm install -g @opencoop/opencode-plugin
```

### Step 2: Configure

Add the plugin to `~/.config/opencode/opencode.json`:

```json
{
  "plugin": ["@opencoop/opencode-plugin"],
  "mcp": {
    "opencoop": {
      "type": "remote",
      "url": "http://localhost:31313/sse",
      "enabled": true
    }
  }
}
```

### Step 3: Verify

```bash
npm list -g @opencoop/opencode-plugin
```

### Step 4: Access Web UI

```
http://localhost:31313/ui
```

### Diagnostics

```bash
# 1. Is OpenCode installed?
which opencode || echo "NOT IN PATH"

# 2. Is the plugin installed?
npm ls -g @opencoop/opencode-plugin 2>&1

# 3. Is the HTTP server up?
curl -s --max-time 3 http://localhost:31313/health || echo "SERVER DOWN"

# 4. Does SSE work (not HTML)?
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' --max-time 3 -H 'Accept: text/event-stream' http://localhost:31313/sse
```

### Platform Notes

**Termux (Android):**
- OpenCode binary is usually at `$PREFIX/bin/opencode` or `$HOME/.opencode/bin/opencode`.
- If `which opencode` fails, add to PATH: `export PATH="$HOME/.opencode/bin:$PATH"`

**Windows:**
- Config path: `%USERPROFILE%\.config\opencode\opencode.json`
- Plugin cache: `%USERPROFILE%\.cache\opencode\packages\@opencoop`

**Mac:**
- Homebrew: `/opt/homebrew/bin/opencode`
- curl script: `~/.opencode/bin/opencode`

## Troubleshooting

### Plugin recognized by OpenCode but UI not loading / MCP not starting

1. **Plugin version too old**: Must be `1.16.0` or newer. Check with `npm ls -g @opencoop/opencode-plugin`.
2. **Stale plugin cache**: Clear and restart:
   ```bash
   rm -rf ~/.cache/opencode/packages/@opencoop
   ```
3. **Port 31313 already in use**: Check with `lsof -i :31313` or `ss -ltnp | grep 31313`.

### MCP stays red / won't connect

1. Make sure the OpenCode web UI (or TUI) is open — the plugin server only starts when OpenCode loads the plugin.
2. Verify the server: `curl http://localhost:31313/health`
3. Verify SSE: `curl -N -H 'Accept: text/event-stream' http://localhost:31313/sse`
4. Make sure your MCP `url` ends with `/sse` (not `/mcp`).

### Invite link shows local IP instead of tunnel URL

1. **Fully restart OpenCode after install/update** — the plugin code loads only at startup.
2. **Wait a few seconds on first run** — the SSH tunnel connects to tinyfi.sh.
3. **Mode must be HOST and saved** — click Save after selecting HOST.
4. **Check the badge**: green = links use the tunnel; red = shows the exact error.

### Tools fail or return errors

Open the web UI (`http://localhost:31313/ui`), select HOST or REMOTE mode and configure your project folder. Tools need a configured workspace before they can read/write files.

## Support the project

OpenCOOP is built and maintained by one developer, with no company behind it.
If it saves your team time, **a star is the whole marketing budget**:

[![Star OpenCOOP](https://img.shields.io/github/stars/Pajand/opencoop?style=social&label=Star%20OpenCOOP)](https://github.com/Pajand/opencoop/stargazers)

A star also gets us into the [awesome-opencode](https://github.com/awesome-opencode/awesome-opencode)
catalog, which is how most people find OpenCode plugins. It takes ten seconds
and it genuinely moves the project.

Other ways to help, if a star feels cheap:

- **Report a bug** — especially security issues; the last one (unauthenticated MCP
  transport) came from a user and is now documented in [SECURITY.md](SECURITY.md).
- **Tell one person** who runs OpenCode with a team.
- **Write about it** — a post, a gist, a comment. Anything that links back here.

## Contributing

Contributions are welcome! Please read the contributing guidelines first.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

OpenCOOP Non-Commercial License — Free for non-commercial use, commercial use requires permission.

See [LICENSE](LICENSE) file for details.

## Author

**Hamid Pajand** — [GitHub](https://github.com/Pajand) — [Email](mailto:HamidPajand@gmail.com)

---

<div align="center">

**Made with ❤️ for the OpenCode community**

</div>