# opencode-plugins

**Repository Path**: hivedark/opencode-plugins

## Basic Information

- **Project Name**: opencode-plugins
- **Description**: 本仓库包含 Opencode 插件，通过事件钩子扩展 Opencode 的功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Opencode Plugins

A collection of plugins that extend Opencode's functionality through event hooks.

## Features

- 🎣 **Event-driven** - Listen and respond to command, file, session events
- 🧩 **Modular** - Independent plugin files, easy to extend and maintain
- 🔌 **Hot-reload** - Changes apply without restart

## Project Structure

```
./
├── opencode.json          # Plugin configuration
├── README.md              # Chinese docs
├── README-en.md           # English documentation
├── AGENTS.md              # Developer guidelines
├── .opencode/
│   ├── package.json      # Dependencies
│   └── plugins/          # Plugin source files (*.js)
│       └── notification.js
```

## Quick Start

### Loading Plugins

**Local plugins** (place in plugins directory):
- `.opencode/plugins/` - Project-level plugins
- `~/.config/opencode/plugins/` - Global plugins

**npm packages** (configure in `opencode.json`):
```json
{
  "plugins": ["notification", "@my-org/custom-plugin"]
}
```

### Creating a Plugin

`.opencode/plugins/my-plugin.js`:
```javascript
export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    session: {
      idle: async () => {
        console.log('Session idle!')
      },
    },
  }
}
```

### Plugin Parameters

| Parameter | Description |
|------------|-------------|
| `project` | Current project info |
| `directory` | Current working directory |
| `worktree` | Git worktree path |
| `client` | Opencode SDK client |
| `$` | Bun shell API for command execution |

## Available Plugins

| Plugin | Description |
|--------|-------------|
| [notification](./.opencode/plugins/notification.js) | Sends Windows notification when session is idle |
| [opencode-mobile](https://github.com/doza62/opencode-mobile) | Mobile push notifications via Expo for Opencode events |

## Event Types

### Session
`session.created`, `session.compacted`, `session.deleted`, `session.diff`, `session.error`, `session.idle`, `session.status`, `session.updated`

### Tool
`tool.execute.before`, `tool.execute.after`

### Message
`message.part.removed`, `message.part.updated`, `message.removed`, `message.updated`

### File
`file.edited`, `file.watcher.updated`

### Other
`command.executed`, `installation.updated`, `lsp.client.diagnostics`, `lsp.updated`, `permission.asked`, `permission.replied`, `server.connected`, `todo.updated`, `shell.env`, `tui.prompt.append`, `tui.command.execute`, `tui.toast.show`

## Adding Dependencies

Add npm packages in `.opencode/package.json`:
```json
{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}
```

## TypeScript Support

```typescript
import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}
```

## Mobile Push Notification Plugin (opencode-mobile)

Sends Opencode event notifications to mobile devices via Expo, supporting session idle, errors, permission updates, and other events.

### Features

- 📱 **Mobile Notifications** - Receive Opencode event notifications on mobile devices
- 🔗 **Tunnel Connection** - Supports Cloudflare, ngrok, Localtunnel tunnels
- 📲 **QR Code Connection** - Scan QR code for quick mobile device connection
- ⚡ **Event-driven** - Automatically listens to session events and sends notifications

### Installation & Configuration

1. Install the plugin:
   ```bash
   npx opencode-mobile install
   ```

2. Add plugin to `opencode.json`:
   ```json
   {
     "plugins": ["opencode-mobile"]
   }
   ```

3. Start Opencode and use:
   ```bash
   opencode serve
   # Enter /mobile in session to get connection code
   ```

### Usage Example

1. Start Opencode server
2. Run `/mobile` command to get QR code
3. Install OpenCode Mobile app or Expo Go on mobile device
4. Scan QR code to connect
5. Receive Opencode event notifications

### Related Commands

- `npx opencode-mobile install` - Install plugin
- `npx opencode-mobile update` - Check for updates
- `npx opencode-mobile filters` - Manage notification filters
- `npx opencode-mobile qr` - Display QR code

### Environment Variables

- `TUNNEL_PROVIDER` - Tunnel provider (`auto`, `ngrok`, `cloudflare`, `localtunnel`)
- `OPENCODE_MOBILE_DEBUG` - Debug mode (`1` to enable)
- `OPENCODE_PORT` - Local server port

### Troubleshooting

1. **Connection failed** - Check network connection, try different tunnel providers
2. **Notifications not showing** - Confirm mobile device is properly connected and notification permissions granted
3. **QR code invalid** - Re-run `/mobile` command to generate new connection code

## Related Links

- [Developer Guidelines](./AGENTS.md)
- [Opencode Documentation](https://opencode.ai)