obs-agent-connector Command Reference¶

This document summarizes the Agents, common commands, and command-line parameters supported by obs-agent-connector for quick reference.

Supported Agents¶

Run obs-agent-connector agents to view the types and operating systems supported by the current connector. This list serves a different purpose from the type list on the Agent Monitoring page; for frameworks manually instrumented with OpenTelemetry, see Create Agent Monitoring Application.

Agent ID	Product Name	Integration Method	macOS	Linux	Windows	Description
`claude`	Claude Code	Built into `obs-agent-connector`	✅	✅	✅	Uses the Stop / SessionEnd Hook adapter
`codebuddy`	CodeBuddy	Built into `obs-agent-connector`	✅	✅	✅	Supports Stop / SessionEnd Hooks and native `index.json` replay; Linux x64 is product-verified
`codex`	Codex	Built into `obs-agent-connector`	✅	✅	✅	Uses the Stop Hook adapter and includes built-in Codex trust and configuration handling
`cursor`	Cursor	Built into `obs-agent-connector`	✅	✅	✅	Detects `~/.cursor`, prefers `cursor-agent`, and manages user-level Cursor Hooks
`dsh`	DeepSeek Harness	`dsh-otel-plugin`	✅	✅	✅	Uses the DeepSeek Harness configuration package
`hermes`	Hermes	`hermes-otel-plugin`	✅	✅	❌	Uses the Hermes plugin
`mimo`	mimo	`opencode-otel-plugin`	✅	✅	✅	Uses the OpenCode-compatible plugin in the mimo configuration directory
`opencode`	OpenCode	`opencode-otel-plugin`	✅	✅	✅	Uses the OpenCode configuration directory under `~/.config/opencode`
`openclaw`	OpenClaw	`openclaw-otel-plugin`	✅	✅	✅	Uses the OpenClaw plugin
`qoder`	Qoder	`qoder-otel-plugin`	✅	✅	✅	Automatically identifies the China or international edition directory and passes the corresponding `--variant` parameter
`workbuddy`	WorkBuddy	`workbuddy-otel-plugin`	✅	❌	✅	Uses the detected WorkBuddy configuration directory and writes `gtrace.json` to it

Agent Descriptions¶

Agent ID	Description
`claude`	Uses the built-in adapter and writes the managed runtime configuration to `~/.obs-agent-connector/claude/`.
`codebuddy`	Uses the built-in adapter. The connector manages the Hook configuration in `~/.codebuddy/settings.json`.
`cursor`	Uses the built-in adapter, detects the local Cursor CLI, and prefers `cursor-agent` when available.
`dsh`	Discoverable when a `dsh` executable exists in `PATH` or a `~/.dsh` directory exists. The default configuration is `web`, and the runtime configuration is generated by `dsh-otel-plugin`.
`mimo`	Uses the configuration under `~/.config/mimocode`; the plugin is located in `plugins/opencode-otel-plugin` in that directory. After integration, check the plugin status with `obs-agent-connector status mimo`.
`qoder`	Automatically detects the international or China edition directory and uses the corresponding variant.
`qoder-cn`	A legacy-compatible Agent ID that always uses the China edition directory.
`hermes`	Hermes uses YAML configuration, which is not part of the currently supported JSON configuration structure, so the CLI does not manage its runtime enabled or disabled state.
`openclaw`	Supports enabling or disabling the runtime through `~/.openclaw/openclaw.json`; `config <agent>` is not currently supported because the plugin manages its own private configuration structure.
`workbuddy`	Supports macOS and Windows; Linux is not currently supported.

Common Commands¶

obs-agent-connector list
obs-agent-connector status <agent>
obs-agent-connector discover
obs-agent-connector discover -u
obs-agent-connector install <agent>
obs-agent-connector config <agent> list
obs-agent-connector config <agent> edit --enabled=false --endpoint=<Endpoint>
obs-agent-connector update <agent>
obs-agent-connector enable <agent>
obs-agent-connector disable <agent>
obs-agent-connector remove <agent>
obs-agent-connector uninstall
obs-agent-connector version
obs-agent-connector version -u

Common Parameters¶

Common Installation Parameters¶

When running install <agent>, the common parameters are as follows:

Parameter	Description
`--endpoint`	OBS / GTrace data receiving endpoint, for example `<Endpoint>`
`--x-token`	Authentication token used for data reporting
`--agent-id`	Overrides the auto-generated `agent_id`
`--agent-name`	Overrides the auto-generated `agent_name`
`--static-base`	Overrides the base address used for this installation; external open-source plugins are fetched from `<static-base>/agent_plugins`
`--yes`	Skips the confirmation steps
`--dry-run`	Only outputs the execution plan and command preview without making actual changes

Default identity generation rules:

When --agent-id is not specified, the CLI automatically generates agid_<uuidv4 without hyphens>.
When --agent-name is not specified, the CLI automatically generates <hostname>_<agent>_<YYYYMMDD>.

External plugin invocation conventions:

The connector only passes the public version, --type gtrace, Endpoint, Token, tags, and configuration or variant parameters to the plugin.
The plugin installer handles archive download, checksum verification, plugin registration, and private runtime configuration on its own.
The connector does not pass --source and does not read or write the external plugin's private gtrace.json.

Built-in Adapter Installation Parameters¶

The following parameters apply to the built-in claude, codebuddy, codex, and cursor adapters:

Parameter	Description
`--trace-path`	Overrides the Trace data reporting path
`--metrics-path`	Overrides the Metrics data reporting path
`--header`	Adds an HTTP request header; can be used multiple times
`--tag`	Adds a resource attribute; can be used multiple times
`--capture-content`	Content capture mode; valid values are `none`, `preview`, or `full`
`--max-chars`	Maximum number of characters for captured content
`--enable`	Sets the runtime configuration to `enabled=true`
`--disable`	Sets the runtime configuration to `enabled=false`

CodeBuddy's configuration is merged into the existing ~/.codebuddy/gtrace.json without deleting unrecognized fields.

`discover` Parameters¶

Parameter	Description
`-u`	Updates installed plugins and installs discovered plugins that are not yet installed
`--endpoint`	Overrides the saved Endpoint used for this run
`--x-token`	Overrides the saved Token used for this run
`--yes`	Skips the confirmation steps
`--dry-run`	Only outputs the discovery, installation, and update plan

`update` Parameters¶

Parameter	Description
`--static-base`	Overrides the plugin download base address
`--yes`	Skips the confirmation steps
`--dry-run`	Only outputs the update plan

Usage notes:

update accepts only one Agent at a time.
update claude, update codebuddy, update codex, and update cursor re-calibrate the built-in Hooks.
Updating an external plugin preserves the current runtime configuration.

`enable` and `disable` Parameters¶

Parameter	Description
`--dry-run`	Only outputs configuration changes without writing to the configuration file

Agents that currently support enabling or disabling the runtime through JSON configuration:

claude
codebuddy
codex
cursor
dsh
opencode
openclaw
qoder
workbuddy

`remove` Parameters¶

Parameter	Description
`--yes`	Skips the confirmation steps
`--dry-run`	Only outputs the removal plan
`--purge-config`	Also deletes the runtime configuration; for CodeBuddy, also deletes the data reporting state

`version` Parameters¶

Parameter	Description
`-u`	Updates the connector to the latest version
`--offline`	Only displays the local version without checking the remote version

Installation Script Parameters¶

`install.sh`¶

Parameter	Description
`--version`	Installs the specified connector version; defaults to `latest`
`--install-dir`	Installation directory for the connector binary
`--config-dir`	Connector configuration directory
`--download-base-url`	Download base address for the connector installation package and metadata
`--endpoint`	OBS / GTrace data receiving endpoint
`--x-token`	Authentication token
`--plugin-source`	Plugin source; currently supports `oss` or `github`
`--plugin-base-url`	External plugin download base address
`--binary-only`	Only updates the connector binary without writing `config.json`

`install.ps1`¶

Parameter	Description
`-Version`	Installs the specified connector version; defaults to `latest`
`-InstallDir`	Installation directory for the connector binary
`-ConfigDir`	Connector configuration directory
`-DownloadBaseUrl`	Download base address for the connector installation package and metadata
`-Endpoint`	OBS / GTrace data receiving endpoint
`-XToken`	Authentication token
`-PluginSource`	Plugin source; currently supports `oss` or `github`
`-PluginBaseUrl`	External plugin download base address
`-BinaryOnly`	Only updates the connector binary without writing `config.json`
`-NoPathUpdate`	Does not update the user's `PATH` environment variable

Usage Examples¶

Install the built-in CodeBuddy adapter:

obs-agent-connector install codebuddy --yes

Install an external plugin with a specified Endpoint and Token:

obs-agent-connector install dsh \
  --endpoint <Endpoint> \
  --x-token <X-Token> \
  --yes

Discover all Agents and sync installed plugins:

obs-agent-connector discover -u --yes

Remove a plugin but keep its configuration:

obs-agent-connector remove codex --yes

Update the connector:

obs-agent-connector version -u

obs-agent-connector Command Reference¶

Supported Agents¶

Agent Descriptions¶

Common Commands¶

Common Parameters¶

Common Installation Parameters¶

Built-in Adapter Installation Parameters¶

discover Parameters¶

update Parameters¶

enable and disable Parameters¶

remove Parameters¶

version Parameters¶

Installation Script Parameters¶

install.sh¶

install.ps1¶