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¶

Agent Identifier	Product Name	Integration Method	macOS	Linux	Windows	Description
`claude`	Claude Code	Built into `obs-agent-connector`	✅	✅	✅	Uses Stop / SessionEnd Hook adapters
`codebuddy`	CodeBuddy	Built into `obs-agent-connector`	✅	✅	✅	Supports Stop / SessionEnd Hooks and native `index.json` replay; Linux x64 verified by product
`codex`	Codex	Built into `obs-agent-connector`	✅	✅	✅	Uses 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 DeepSeek Harness configuration package
`hermes`	Hermes	`hermes-otel-plugin`	✅	✅	❌	Uses Hermes plugin
`opencode`	OpenCode	`opencode-otel-plugin`	✅	✅	✅	Uses the OpenCode configuration directory at `~/.config/opencode`
`openclaw`	OpenClaw	`openclaw-otel-plugin`	✅	✅	✅	Uses OpenClaw plugin
`qoder`	Qoder	`qoder-otel-plugin`	✅	✅	✅	Auto-detects 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` into it

Agent Descriptions¶

Agent Identifier	Description
`claude`	Uses built-in adapter and writes managed runtime configuration to `~/.obs-agent-connector/claude/`.
`codebuddy`	Uses built-in adapter. The connector manages Hook configuration in `~/.codebuddy/settings.json`.
`cursor`	Uses built-in adapter, detects the local Cursor CLI, and prefers `cursor-agent` when available.
`dsh`	Discoverable when `dsh` executable is in `PATH` or `~/.dsh` directory exists. Default configuration is `web`, runtime configuration is generated by `dsh-otel-plugin`.
`qoder`	Auto-detects International or China edition directory and uses the corresponding variant.
`qoder-cn`	Legacy Agent identifier, always uses the China edition directory.
`hermes`	Hermes uses YAML configuration, which does not belong to the currently supported JSON configuration structure, so the CLI does not manage its runtime enable or disable state.
`openclaw`	Supports runtime enable/disable via `~/.openclaw/openclaw.json`; `config <agent>` is not supported because the plugin manages its own private configuration structure.
`workbuddy`	Supports macOS and Windows, but not Linux yet.

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 executing install <agent>, common parameters are as follows:

Parameter	Description
`--endpoint`	OBS / GTrace data ingestion endpoint, e.g., `<Endpoint>`
`--x-token`	Authentication token for data reporting
`--agent-id`	Overrides the auto-generated `agent_id`
`--agent-name`	Overrides the auto-generated `agent_name`
`--static-base`	Overrides the base URL used for this installation; external open-source plugins are fetched from `<static-base>/agent_plugins`
`--yes`	Skips 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 auto-generates agid_<uuidv4 without hyphens>;
When --agent-name is not specified, the CLI auto-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 is responsible for downloading the archive, checksum verification, plugin registration, and private runtime configuration;
The connector does not pass --source and does not read or write the 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 repeated
`--tag`	Adds a resource attribute; can be repeated
`--capture-content`	Content capture mode; valid values are `none`, `preview` or `full`
`--max-chars`	Maximum number of characters for captured content
`--enable`	Sets runtime configuration to `enabled=true`
`--disable`	Sets runtime configuration to `enabled=false`

CodeBuddy's configuration is merged into the existing ~/.codebuddy/gtrace.json; unrecognized fields are not deleted.

`discover` Parameters¶

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

`update` Parameters¶

Parameter	Description
`--static-base`	Overrides the plugin download base URL
`--yes`	Skips 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 recalibrate 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 the configuration file

Agents currently supporting runtime enable/disable via JSON configuration:

claude
codebuddy
codex
cursor
dsh
opencode
openclaw
qoder
workbuddy

`remove` Parameters¶

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

`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 version of the connector; defaults to `latest`
`--install-dir`	Installation directory for the connector binary
`--config-dir`	Configuration directory for the connector
`--download-base-url`	Download base URL for the connector package and metadata
`--endpoint`	OBS / GTrace data ingestion endpoint
`--x-token`	Authentication token
`--plugin-source`	Plugin source; currently supports `oss` or `github`
`--plugin-base-url`	Download base URL for external plugins
`--binary-only`	Only updates the connector binary without writing `config.json`

`install.ps1`¶

Parameter	Description
`-Version`	Installs the specified version of the connector; defaults to `latest`
`-InstallDir`	Installation directory for the connector binary
`-ConfigDir`	Configuration directory for the connector
`-DownloadBaseUrl`	Download base URL for the connector package and metadata
`-Endpoint`	OBS / GTrace data ingestion endpoint
`-XToken`	Authentication token
`-PluginSource`	Plugin source; currently supports `oss` or `github`
`-PluginBaseUrl`	Download base URL for external plugins
`-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 synchronize 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¶