opencode-logger

This small package is intended to be used as Opencode plugin.

See plugins documentation.

This plugin handles logging of all supported events.

Events are logged as jsonl to the

<project-root>/logs/opencode/log.jsonl

Usage

In your project open (or set) your opencode.json or opencode.jsonc file and add:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-logger"],
}

Configuration

You can customize the log directory, filename, and logging scope using environment variables.

| Variable | Description | Default | | ------------------------------- | ----------------------------------------------------------------------------------------- | -------------------- | | OPENCODE_LOGGER_DIR | The directory where logs are stored. Can be absolute or relative to project root. | logs/opencode | | OPENCODE_LOGGER_FILENAME | The filename for the log file. | log.jsonl | | OPENCODE_LOGGER_SCOPE | Comma-separated list of event types to log. Supports wildcards (e.g., session.*). | * (Log all events) | | OPENCODE_LOGGER_MAX_FILE_SIZE | Maximum log file size in bytes before automatic rotation. Set to 0 to disable rotation. | 104857600 (100 MB) | | OPENCODE_LOGGER_MAX_FILES | Maximum number of rotated log files to keep. Set to 0 to keep all. | 0 (unlimited) |

Setting via CLI

You can set them when starting the Opencode client:

OPENCODE_LOGGER_DIR=/tmp/my-logs opencode

Setting by exporting ENV variables

Or export them, for example in your ~/.bashrc

export OPENCODE_LOGGER_DIR=/tmp/my-logs
export OPENCODE_LOGGER_FILENAME=custom-name.jsonl

Logging Scope

You can filter which events are logged using the OPENCODE_LOGGER_SCOPE environment variable. It accepts a comma-separated string of event types or patterns.

• * (Default): Logs all events.
• session.*: Logs all events starting with session. (e.g., session.created, session.updated).
• command.executed,file.edited: Logs only these specific events.

Example:

export OPENCODE_LOGGER_SCOPE="session.*,command.executed"

Log Rotation

You can control when log files are rotated and how many archived files are retained.

• OPENCODE_LOGGER_MAX_FILE_SIZE: Once the active log file reaches this size (in bytes), it is rotated. Set to 0 to disable rotation entirely.
• OPENCODE_LOGGER_MAX_FILES: After rotation, only this many archived files are kept (oldest deleted first). Set to 0 to keep all rotated files indefinitely.

Example:

# Rotate at 10 MB, keep last 5 archived files
export OPENCODE_LOGGER_MAX_FILE_SIZE=10485760
export OPENCODE_LOGGER_MAX_FILES=5