Built-in slash discovery (CC 2.1.108+):
Built-in slash commands like /init are also discovered.
Use /harness-setup init only when Harness-specific bootstrap is needed.
Claude Code setup guidance (CC 2.1.120+):
MCP alwaysLoad, ${CLAUDE_EFFORT}, claude plugin prune, claude project purge,
ANTHROPIC_BEDROCK_SERVICE_TIER, claude_code.skill_activated.invocation_trigger,
Windows PowerShell primary shell, and deferred tools for forked skills/subagents are
handled with docs/claude-code-setup-mcp-telemetry-provider.md as the source of truth.
Codex plugin workflows:
Do not dual-manage Codex /goal and Plans.md.
Plugin-bundled hooks are opt-in; external agent imports require explicit ownership declaration;
MultiAgentV2 / agents.max_threads = 8 is treated as an upper limit;
sticky environments / app-server artifacts prioritize safe defaults.
For Codex stable: , large thread pagination,
selected-environment , live app-server config refresh,
accurate turn diffs, plugin details bundled hooks, sharing discoverability controls —
use as the source of truth.
Note: Harness v4.0 itself (harness command) is a Node.js-free Go binary.
Codex CLI (codex command) is a separate tool and still requires Node.js.
Codex provider / model metadata policy (0.123.0+ / 0.130.0)
For Codex 0.123.0+ provider/model guidance and Codex 0.130.0 stable Bedrock aws login guidance,
use docs/codex-provider-setup-policy.md as the source of truth.
Key points:
For Bedrock, use Codex built-in provider amazon-bedrock.
Place AWS profile in user/project Codex config under [model_providers.amazon-bedrock.aws].
Treat AWS console-login credentials from aws login profiles as AWS-side profile material.
Harness does not write AWS credentials, console-login cache, or provider endpoints.
Do not fix model = "gpt-5.4" as the setup default in Harness distribution Codex config.
Do not fix model_provider = "amazon-bedrock" as the setup default in Harness distribution Codex config.
Treat gpt-5.4 as Codex's current model metadata; do not leave old gpt-5.2-codex etc. as recommended samples.
Do not mix Claude Code's CLAUDE_CODE_USE_BEDROCK / ANTHROPIC_DEFAULT_* / modelOverrides guidance with Codex's model_provider = "amazon-bedrock".
Only users/projects using Bedrock add the following as needed:
For Claude Code provider/MCP/telemetry guidance, refer to docs/claude-code-setup-mcp-telemetry-provider.md.
In particular, ANTHROPIC_BEDROCK_SERVICE_TIER is only for Bedrock users' provider environments and must not be included in Harness plugin defaults/templates/shared project settings.
For Codex 0.130.0 stable app-server/plugin workflow guidance,
use docs/codex-plugin-workflows-policy.md as the source of truth.
Key points:
codex remote-control is the explicit launch entrypoint for headless remotely controllable app-server. Harness setup does not write remote-control defaults to config.
App-server clients can page large threads. Check the required page range for long loop/Breezing transcripts.
view_image can resolve files via selected environments in multi-environment sessions. Include environment/workdir in artifact reports.
Live app-server threads pick up config changes without restart. Handle secret/provider/hook policy changes with diff and verification.
Turn diffs stay accurate across apply_patch including partial failures. Confirm with git diff and tests.
Plugin details now show bundled hooks. Check bundled hooks before install/share; keep Harness bundled hooks opt-in.
Plugin sharing exposes link metadata and discoverability controls. Confirm scope and metadata as release surface.
Configurable OpenTelemetry trace metadata is limited to debugging/triage assistance; do not include personal info, customer info, or secrets.
Built-in MCPs are first-class runtime servers. Treat as Codex runtime-owned surface; do not mix owners with plugin-provided MCPs.
CODEX_HOME environments TOML provider is a user-level environment source. Report selected environment; fix write turns to one primary environment.
Do not rely on "remove skills list extra roots"; explicitly use Harness mirror install or [[skills.config]] path-based loading.
Codex MCP diagnostics / plugin loading (0.123.0+)
For Codex 0.123.0+ MCP diagnostics/plugin MCP loading guidance,
use docs/codex-mcp-diagnostics.md as the source of truth.
Key points:
In the Codex TUI, normally check only server status lightly with /mcp.
Use /mcp verbose only when an MCP server is not visible, resources are not showing, or resource templates cannot be read.
With /mcp verbose, check diagnostics/resources/resource templates.
Guide on the assumption that plugin .mcp.json accepts both mcpServers format and top-level server map format.
For new plugins, prefer the more shareable mcpServers format.
For existing plugins in top-level server map format, use Codex's improved loading and avoid unnecessary rewrites.
Do not mix with Claude Code's claude mcp ..., .claude/mcp.json, hook type: "mcp_tool" guidance.
For Codex 0.123.0+ remote_sandbox_config and codex exec shared flags guidance,
use docs/codex-sandbox-execution-policy.md as the source of truth.
Key points:
Guide remote_sandbox_config as host-specific sandbox policy in requirements.toml.
Decide by comparing allowed_sandbox_modes per remote environment, such as remote devbox / ephemeral CI runner / shared host.
Host matching is a convenient classification but not strong device authentication. Avoid broad wildcards in high-risk environments.
Do not write organization-specific remote_sandbox_config in Harness distribution codex/.codex/config.toml.
Since Codex 0.123.0, codex exec inherits root-level shared flags, so do not add duplicate --approval-policy / --sandbox pairs on the wrapper side.
scripts/codex-companion.sh task --write adding --sandbox workspace-write is translating Harness's "write task" intent to exec-local, not duplicating root shared flags.
scripts/codex/codex-exec-wrapper.sh's --full-auto is maintained in 53.2.4. If changed, add regression tests for approval/sandbox behavior in a separate task.
On Windows with core.symlinks=false, repository symlinks become regular files and harness-* skills may not appear in the command list. Public bundles are synced as real directory mirrors.
Marketplace stability was significantly improved in v2.1.71.
For plugin/managed settings policy since Claude Code 2.1.117-2.1.118,
use docs/plugin-managed-settings-policy.md as the source of truth.
Recommended install method
# Pin version with @ref format (recommended)
claude plugin install owner/repo@v4.0.0
# Latest version
claude plugin install owner/repo
The owner/repo@vX.X.X format is recommended. With the @ref parser fix, tags, branches, and commit hashes all resolve accurately.
Updates
claude plugin update owner/repo
Update merge conflicts were fixed in v2.1.71, enabling stable updates.
Other improvements
MCP server deduplication: Automatically prevents duplicate registration of the same MCP server
/plugin uninstall uses settings.local.json: Accurately reflected in user-local settings
For controlling plugin marketplace in enterprise use, use Claude Code's own managed settings.
Harness does not layer its own marketplace resolver or dependency resolver on top.
Item
Purpose
Harness handling
extraKnownMarketplaces
Guide/register recommended marketplace for team
Prioritize this for normal onboarding
blockedMarketplaces
Block specific marketplace sources
Managed settings only; do not include in normal user defaults
strictKnownMarketplaces
Allow only permitted marketplace sources
Managed settings only; do not include in normal user defaults
Delegate to Claude Code itself; do not add Harness-specific resolver
Plugin themes/ directory
Plugin distributes themes
P: Future task for now; Harness does not bundle themes
DISABLE_AUTOUPDATER stops auto-updates.
DISABLE_UPDATES stops even manual claude update, so it's for enterprises running fixed versions.
Neither is included in Harness project defaults; organizations that need them configure via managed settings or device management.
When dependencies are missing, first check Claude Code's /plugin Errors, /doctor, claude plugin list --json.
If an unregistered marketplace is the cause, register with /plugin marketplace add or claude plugin marketplace add and let the built-in auto-resolve handle it.
