opencode-discord-presence

한국어 | English

Display your current OpenCode session status in Discord Rich Presence. Show which AI agent you're using, the current model, prompt/file activity, and more.

Features

• Real-time agent display - Shows which AI agent (Claude, Prometheus, etc.) you're currently using
• Model information - Displays the active model (Claude Sonnet, GPT-4, etc.)
• Discord elapsed timer - Presence includes a Discord start timestamp so elapsed coding time appears in the client timer UI
• Korean language support - Proper Korean particle handling (을/를, 은/는)
• Idle detection - Automatically shows when you're taking a break
• Live File Spotlight - Shows the file currently being edited, read, or diagnosed by the agent, with language-specific Discord icons
• Task Mission Board - Displays active todo progress with task labels and completion counts (e.g., "Implementing dark mode (2/5)")
• Diagnostics placeholder support - Keeps the diagnostics display surface reserved for future/external integrations; current OpenCode plugin API v1 logs diagnostics events but does not expose counts (see limitations)
• Smart rotation - Critical states (errors, idle, all-done) pin; informational cards (file spotlight, mission board, session stats) rotate every 20 seconds by default
• Session recap - When a session ends, a recap card shows total prompts and files touched for 30 seconds

Installation

# Using bun
bun add opencode-discord-presence

# Using npm
npm install opencode-discord-presence

# Using pnpm
pnpm add opencode-discord-presence

Quick Start

Register the plugin in your opencode.json:

{
  "plugin": ["opencode-discord-presence"]
}

That's it! The plugin will automatically connect to Discord and display your session status.

opencode.json only registers the plugin. All plugin settings live in .discord-presence.json or environment variables — see Configuration below.

Configuration

Create a .discord-presence.json file in your project root (preferred) or home directory:

{
  "enabled": true,
  "applicationId": "YOUR_DISCORD_APP_ID",
  "language": "ko",
  "richPresence": {
    "enableFileSpotlight": false,
    "enableMissionBoard": true,
    "rotationIntervalSeconds": 20,
    "mainAgentOnly": false,
    "diagnostics": {
      "errorsOnly": true
    }
  }
}

⚠️ enableFileSpotlight is off by default: turning it on broadcasts the path of the file you're currently editing to anyone viewing your Discord profile. Only enable it if you're working on a public repo or don't mind that exposure.

Or use environment variables:

OPENCODE_DISCORD_ENABLED=true
OPENCODE_DISCORD_CLIENT_ID=YOUR_APP_ID
OPENCODE_DISCORD_LANGUAGE=ko
OPENCODE_DISCORD_DEBUG=true

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable or disable the plugin | | applicationId | string | (built-in) | Custom Discord Application ID for your own branding | | language | string | "en" | Display language ("en" or "ko") | | debug | boolean | false | Emit [discord-presence] lifecycle logs (connect / disconnect / failures). Off by default so nothing prints in your OpenCode console. | | richPresence.enableFileSpotlight | boolean | false | Show the path of the file currently being edited/read. Off by default for privacy — Discord broadcasts your activity to anyone viewing your profile, so leaking working file paths can expose private repo internals. Enable explicitly if you're OK with that. | | richPresence.enableMissionBoard | boolean | true | Show task mission board card | | richPresence.rotationIntervalSeconds | number | 20 | How often informational cards rotate (10–60 seconds) | | richPresence.mainAgentOnly | boolean | false | When true, only chat.message events from the main session (root, no parentID) update Discord presence; sub-agent / task sessions are filtered out so a background planner or explore agent does not flicker the user's profile. When false, every chat.message overwrites presence — last writer wins, but the orchestrator still tracks busy/idle across all sessions so the "idle" text appears only when every tracked session reports idle. | | richPresence.diagnostics.errorsOnly | boolean | true | Reserved for future/external diagnostics integrations; inactive with current OpenCode plugin API v1 |

For backward compatibility, the parser also accepts discordPresence.applicationId, but new configs should use the top-level applicationId shown above.

Where the plugin reads from

Each setting is resolved in this order — the first defined value wins:

1. <projectRoot>/.discord-presence.json — per-project config, lives next to your opencode.json. Recommended for project-specific tweaks (e.g. a Korean idle string for a Korean codebase).
2. ~/.discord-presence.json — your global default, used by every OpenCode project.
3. Environment variables — OPENCODE_DISCORD_ENABLED, OPENCODE_DISCORD_CLIENT_ID, OPENCODE_DISCORD_LANGUAGE, OPENCODE_DISCORD_DEBUG. Convenient for one-off overrides (OPENCODE_DISCORD_DEBUG=true opencode …).
4. Built-in defaults — silent (debug: false), English, shared Discord App ID.

opencode.json itself is not a config source for this plugin. Putting discordPresence: { … } inside opencode.json will not be picked up; use .discord-presence.json instead. (The shared OpenCode schema does not allow plugin-specific fields, so this keeps your opencode.json valid.)

Per-project example

# In any OpenCode project, alongside opencode.json:
cat > .discord-presence.json <<'JSON'
{
  "language": "ko",
  "debug": false,
  "richPresence": {
    "rotationIntervalSeconds": 15
  }
}
JSON

Restart OpenCode and the new settings take effect on the next chat message.

Custom Discord Application

For custom branding (your own images and app name):

1. Go to Discord Developer Portal
2. Click "New Application" and give it a name
3. Go to "Rich Presence" → "Art Assets"
4. Upload your images (at least one named opencode-logo)
5. Copy the Application ID from "General Information"
6. Add it to your config:

{
  "applicationId": "YOUR_APPLICATION_ID"
}

How It Works

The plugin hooks into OpenCode's event system:

• chat.message - Updates presence when you send/receive messages, tracking the current agent and model
• tool.execute.before / tool.execute.after - Captures file context and tool operation labels (edit, read, search, build, test, etc.)
• file.edited - Updates the live file spotlight with the edited file path and language icon
• todo.updated - Drives mission board progress with active task labels and completion counts
• session.idle - Triggers idle state with the last active task shown in the state line
• session.deleted - Triggers session recap showing total prompts and files touched for 30 seconds

Limitations

• lsp.client.diagnostics is listened for, but error/warning counts are not available through the OpenCode plugin API v1. Diagnostic counts shown in presence require external LSP configuration. The plugin logs diagnostics events but does not fabricate counts.

Presence States

| State | English | Korean | Description | |-------|---------|--------|-------------| | Active editing | Working with {agent} | {agent}을/를 작업중 | File being edited | | Active reading | Working with {agent} | {agent}을/를 작업중 | File being read | | Task active | Working with {agent} | {agent}을/를 작업중 | With mission progress | | Diagnostics error | Working with {agent} | {agent}을/를 작업중 | Errors detected | | Idle | {agent} is idle | {agent}은/는 휴식중 | No activity | | Session complete | Session Complete! | 세션 완료! | Session ended (30s) | | All tasks done | All tasks complete! | 모든 작업 완료! | No pending tasks |

Korean particles (을/를, 은/는) are automatically selected based on whether the agent name ends with a consonant (받침).

Visual Sample Matrix

The following states are fully supported in v1 (runtime-backed):

| Condition | Headline | State line | Large image | |-----------|----------|------------|-------------| | Editing file | Working with Claude | src/plugin.ts | language icon | | Reading file | Working with Claude | src/services/discord-rpc.ts | action-reading | | Task active | Working with Claude | Implementing dark mode (2/5) | task | | Diagnostics error | Working with Claude | 5 errors, 2 warnings / 오류 5개, 경고 2개 | state-error | | Idle | Claude is idle | Last task: Add theme toggle / 마지막 작업: Add theme toggle | state-idle | | Session recap | Session Complete! / 세션 완료! | 27 prompts • 3 files / 27개 프롬프트 • 3개 파일 | state-recap | | All tasks complete | All tasks complete! / 모든 작업 완료! | 5/5 finished / 5/5 완료 | state-complete |

Illustrative-only states (not implemented in v1):

| Condition | Headline | State line | Notes | |-----------|----------|------------|-------| | Night mode | Burning the midnight oil | src/index.ts | Not in v1 unless time-based config added |

Development

# Install dependencies
bun install

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Type check
bun run typecheck

# Lint
bun run lint

# Format
bun run format

# Build
bun run build

Architecture

src/
├── index.ts              # Main entry point & exports
├── plugin.ts             # OpenCode hook registration + presence engine
├── config.ts             # Configuration management
├── types/
│   └── index.ts          # TypeScript type definitions
├── services/
│   └── discord-rpc.ts    # Discord RPC service (hardened lifecycle)
├── state/
│   └── presence-state.ts # Instance-scoped presence snapshot + reducer
└── utils/
    ├── activity-rotation.ts # Precedence + rotation engine
    ├── file-label.ts        # Path sanitization + truncation
    ├── file-icons.ts        # Language → icon mapping
    ├── session-metrics.ts   # Session counters + recap
    ├── tool-label.ts        # Tool → operation label mapping
    └── particle.ts          # Korean particle handling (을/를, 은/는)

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Quick Contribution Guide

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (bun test)
4. Commit your changes (git commit -m 'feat: add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

MIT License - see LICENSE for details.

Related Projects

• OpenCode - The AI coding assistant this plugin extends
• @xhayper/discord-rpc - Discord RPC library used by this plugin

Changelog

See CHANGELOG.md for release history.