opencode-baseline-hooks

opencode-baseline-hooks

Security validation, logging, context monitoring, and Kokoro TTS voice notifications for OpenCode and Claude Code.

Features

• Security: Block dangerous commands and sensitive file access
• Logging: Track tool usage, file changes, errors, sessions
• Context Monitoring: Track token usage, backup before context overflow
• Pre-Compact Backup: Automatically backup state before context compaction
• Prompt Logging: Log all user prompts for session recovery
• Voice: Kokoro TTS announcements for task completion and alerts

Troubleshooting

If OpenCode Won't Start After Plugin Update

If the plugin crashes OpenCode on startup, you can fix it without launching OpenCode:

Option 1: Revert to previous version

npm install -g opencode-baseline-hooks@0.8.0

Option 2: Disable the plugin entirely

Edit your config file directly with any text editor:

# Global config
nano ~/.config/opencode/opencode.json

# Or project config  
nano .opencode/opencode.json

Remove or comment out the plugin:

{
  "plugin": [
    // "opencode-baseline-hooks"
  ]
}

Then restart OpenCode - it will start without the plugin.

Option 3: Check logs

Plugin errors are logged to .opencode/logs/errors.json in your project directory.

What's new in v0.9.0

• Smart Notification Queue: Priority-based queue with configurable channels and personas
• Quiet Hours: Suppress non-critical notifications during specified hours (e.g., NOTIFY_QUIET_HOURS=22:00-07:00)
• Message Coalescing: Duplicate messages in same category are automatically coalesced
• Retry Logic: Critical/blocked notifications retry on delivery failure
• Persona System: Different voices/prefixes for ops_sentry, concierge, and default personas
• Channel Fallback: Notifications can route through local-speaker or visual-only channels

v0.8.0

• Hardened Bash command detection so the plugin no longer crashes when output.args is missing
• Published a rebuilt npm package so both global installations and per-project dependencies can consume the fix immediately

Installation

npm install -g opencode-baseline-hooks

Usage

IMPORTANT: OpenCode and Claude Code use DIFFERENT configuration systems!

For OpenCode (Plugin System)

OpenCode uses a plugin system. Add to your ~/.config/opencode/opencode.json:

{
  "plugin": [
    "opencode-baseline-hooks"
  ]
}

Or for project-level config in .opencode/opencode.json:

{
  "plugin": [
    "opencode-baseline-hooks"
  ]
}

That's it! The plugin handles all hook events automatically.

For Claude Code (Hooks Config)

Claude Code uses a hooks config with CLI commands. Add to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "opencode-pre-tool"
      }]
    }],
    "PostToolUse": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "opencode-post-tool"
      }]
    }],
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "opencode-session-start"
      }]
    }],
    "PreCompact": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "opencode-pre-compact --backup --verbose"
      }]
    }],
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "opencode-user-prompt --log-only --store-last-prompt"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "opencode-context-monitor"
      }]
    }]
  }
}

Platform Comparison

Feature	OpenCode	Claude Code
Config file	opencode.json	~/.claude/settings.json
Hook system	"plugin": [...]	"hooks": { ... }
Hook format	TypeScript plugin	CLI commands

CLI Commands

These CLI commands are available after global installation (used by Claude Code):

Command	Description
opencode-pre-tool	Pre-tool validation (security checks)
opencode-post-tool	Post-tool logging (errors, stats)
opencode-session-start	Session initialization
opencode-pre-compact	Pre-compaction backup
opencode-user-prompt	User prompt logging
opencode-context-monitor	Context/token monitoring

Configuration

Variable	Default	Description
KOKORO_URL	http://localhost:8880	Kokoro TTS API endpoint
KOKORO_VOICE	bf_emma	Voice to use
OPENCODE_VOICE	(enabled)	Set to off to disable voice
PROJECT_DIR	(current dir)	Project root directory
NOTIFICATION_MODE	verbose	verbose, smart, or quiet
NOTIFICATION_SPEAK	completion,error	Categories to speak in smart mode
NOTIFY_MAX_QUEUE	20	Maximum notifications in queue
NOTIFY_MIN_GAP_MS	750	Minimum ms between notifications
NOTIFY_QUIET_HOURS	(none)	Quiet hours ranges (e.g., 22:00-07:00,12:00-13:00)
NOTIFY_COALESCE_CATEGORIES	info,warning	Categories to coalesce duplicates
NOTIFY_RETRY_CATEGORIES	critical,blocked	Categories to retry on failure
NOTIFY_MAX_RETRIES	2	Max retry attempts per notification
NOTIFY_PERSONA_OPS_VOICE	(default)	Voice for ops_sentry persona
NOTIFY_PERSONA_CONCIERGE_VOICE	(default)	Voice for concierge persona

Smart Notifications (v0.7.0)

Control notification behavior to reduce voice spam while staying informed.

Notification Modes

Mode	Behavior
verbose	Speak every notification (original behavior)
smart	Aggregate blocked commands, speak summary on completion
quiet	Visual notifications only (macOS notification center)

Smart Mode Categories

Set NOTIFICATION_SPEAK to customize which events trigger voice (comma-separated):

• completion - Task completion summaries
• error - Errors requiring attention
• blocked - Blocked commands (aggregated in smart mode)
• build - Build success/failure
• test - Test results
• warning - Warnings

Example: Reduced Noise Setup

export NOTIFICATION_MODE=smart
export NOTIFICATION_SPEAK=completion,error

Before (verbose mode):

"Blocked writing secrets to file"
"Blocked writing secrets to file"
"Access to sensitive file blocked"
"Build completed successfully"
"Task complete"

After (smart mode):

"MyProject: completed after 5 minutes. 3 commands blocked. Build success."

Security Patterns Blocked

Dangerous Commands

• rm -rf /, recursive delete with dangerous paths
• sudo, su commands
• chmod 777, world-writable permissions
• Piping curl/wget to shell
• Docker system prune
• Disk formatting commands

Sensitive Files

• .env (allows .env.example)
• credentials.json, secrets.json
• .ssh/ directory, SSH keys
• .aws/credentials, .kube/config

Secret Detection (in writes)

• AWS access keys
• GitHub/GitLab tokens
• Stripe keys
• Private keys, JWTs
• Database URLs with passwords

Context Monitoring

The context monitor tracks cumulative token usage and creates backups at thresholds:

• 70%: Warning backup created
• 85%: Critical backup created

Backups include:

• Current todos
• Recent prompts
• Session state
• Recovery instructions

Backups are stored in .opencode/backup/.

Log Files

All logs are stored in .opencode/logs/:

File	Contents
pre_tool_use.json	Tool calls with arguments
post_tool_use.json	Tool outputs
blocked.json	Blocked dangerous commands
errors.json	Detected errors
sessions.json	Session lifecycle
daily_stats.json	Daily usage statistics
user_prompts.json	User prompt history
context_state.json	Current context state
messages.jsonl	Message log for token tracking

Kokoro TTS Setup

Run Kokoro TTS locally with Docker:

docker run -d -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

Plugin API (Programmatic)

The package exports a plugin for direct use:

import plugin from "opencode-baseline-hooks"

// OpenCode plugin system calls this automatically
const hooks = await plugin({ directory: "/path/to/project" })

// Returns event handlers:
// - hooks["tool.execute.before"] - Pre-tool security validation
// - hooks["tool.execute.after"] - Post-tool logging
// - hooks.event - Session events (created, idle, error)

License

MIT

Repository

github.com/48Nauts-Operator/opencode-baseline