Help us improve
Share bugs, ideas, or general feedback.
From claudecode-research-harness-workflow
Initializes and repairs Harness project configuration: CLAUDE.md, Plans.md, hooks, sync, CI/CD, Codex CLI, memory setup, agent config, and mirror sync.
npx claudepluginhub maxwell2732/claudecode-research-harness-workflow --plugin claudecode-research-harness-workflowHow this skill is triggered — by the user, by Claude, or both
Slash command
/claudecode-research-harness-workflow:harness-setup [init|ci|codex|harness-mem|mirrors|agents|localize][init|ci|codex|harness-mem|mirrors|agents|localize]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Integrated Harness setup skill.
Initializes and repairs Harness project configuration: project init, CI/CD setup, Codex CLI config, memory setup, skill mirror sync, agent config, and localization.
Provides Codex CLI conventions for writing and scoring artifacts: SKILL.md layout, config.toml schema, plugin.json, hooks, AGENTS.md hierarchy, marketplace.json, and OpenAI YAML sidecars.
Expert in using Claude Code CLI for advanced configuration, hooks, MCPs, CLAUDE.md, workflows, sub-agents, and permissions to maximize productivity.
Share bugs, ideas, or general feedback.
Integrated Harness setup skill. Consolidates the following legacy skills:
setup — Integrated setup hubharness-init — Project initializationharness-update — Harness updatesmaintenance — File organization and cleanup| Subcommand | Action |
|---|---|
/harness-setup init | New project initialization (CLAUDE.md + Plans.md + hooks + sync + doctor) |
/harness-setup ci | CI/CD pipeline configuration |
/harness-setup codex | Codex CLI install and configuration |
/harness-setup harness-mem | harness-mem integration and memory setup |
/harness-setup mirrors | Update skills/ → public mirror bundle |
/harness-setup agents | agents/ agent configuration |
/harness-setup localize | Localize CLAUDE.md rules |
Built-in slash discovery (CC 2.1.108+): Built-in slash commands like
/initare also discovered. Use/harness-setup initonly 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 withdocs/claude-code-setup-mcp-telemetry-provider.mdas the source of truth.
Codex plugin workflows: Do not dual-manage Codex
/goalandPlans.md. Plugin-bundled hooks are opt-in; external agent imports require explicit ownership declaration; MultiAgentV2 /agents.max_threads = 8is treated as an upper limit; sticky environments / app-server artifacts prioritize safe defaults. For Codex0.130.0stable:codex remote-control, large thread pagination, selected-environmentview_image, live app-server config refresh, accurate turn diffs, plugin details bundled hooks, sharing discoverability controls — usedocs/codex-plugin-workflows-policy.mdas the source of truth.
Introduces Harness to a new project.
Generated files:
project/
├── CLAUDE.md # Project configuration
├── Plans.md # Task management (empty template)
├── .claude/
│ ├── settings.json # Claude Code settings
│ └── hooks.json # Hook configuration (Go binary)
└── hooks/
├── pre-tool.sh # Thin shim (→ core/src/index.ts)
└── post-tool.sh # Thin shim (→ core/src/index.ts)
Flow:
harness version (Node.js not required since v4.0).claude-plugin/ to latest with harness syncharness doctor; present fix suggestions if issues found# Confirm binary exists and works
harness version
# Example: harness v4.0.0 (go1.22.0, darwin/arm64)
Since v4.0, the Harness core engine has migrated to a Go binary.
Node.js is not required. The binary uses bin/harness (or harness on PATH).
# Sync files under .claude-plugin/ to latest
harness sync
# Check sync contents only (no changes)
harness sync --dry-run
harness sync propagates changes from the skills/ SSOT to each mirror (codex/.codex/skills/, opencode/skills/).
Always run after init.
# Run all check items
harness doctor
harness doctor verifies:
| Check item | Content |
|---|---|
| Binary | Does harness version return normally? |
| Plugin config | Is .claude-plugin/plugin.json format correct? |
| Hooks placement | Do hooks exist at the correct paths? |
| Mirror sync | Do skills/ and mirror contents match? |
| CLAUDE.md | Do required sections exist? |
If issues are detected, fix commands are presented.
Configures GitHub Actions workflows.
# Example .github/workflows/ci.yml generation
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm test
# Confirm installation (Codex CLI is Node.js based; separate from Harness itself)
which codex || npm install -g @openai/codex
# Check timeout command (macOS)
TIMEOUT=$(command -v timeout || command -v gtimeout || echo "")
# macOS: brew install coreutils
Note: Harness v4.0 itself (
harnesscommand) is a Node.js-free Go binary. Codex CLI (codexcommand) is a separate tool and still requires Node.js.
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:
amazon-bedrock.[model_providers.amazon-bedrock.aws].aws login profiles as AWS-side profile material.model = "gpt-5.4" as the setup default in Harness distribution Codex config.model_provider = "amazon-bedrock" as the setup default in Harness distribution Codex config.gpt-5.4 as Codex's current model metadata; do not leave old gpt-5.2-codex etc. as recommended samples.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:
model_provider = "amazon-bedrock"
[model_providers.amazon-bedrock.aws]
profile = "codex-bedrock"
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.view_image can resolve files via selected environments in multi-environment sessions. Include environment/workdir in artifact reports.apply_patch including partial failures. Confirm with git diff and tests.CODEX_HOME environments TOML provider is a user-level environment source. Report selected environment; fix write turns to one primary environment.[[skills.config]] path-based loading.For Codex 0.123.0+ MCP diagnostics/plugin MCP loading guidance,
use docs/codex-mcp-diagnostics.md as the source of truth.
Key points:
/mcp./mcp verbose only when an MCP server is not visible, resources are not showing, or resource templates cannot be read./mcp verbose, check diagnostics/resources/resource templates..mcp.json accepts both mcpServers format and top-level server map format.mcpServers format.claude mcp ..., .claude/mcp.json, hook type: "mcp_tool" guidance.mcpServers format:
{
"mcpServers": {
"docs": {
"command": "node",
"args": ["server.js"]
}
}
}
Top-level server map format:
{
"docs": {
"command": "node",
"args": ["server.js"]
}
}
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:
remote_sandbox_config as host-specific sandbox policy in requirements.toml.allowed_sandbox_modes per remote environment, such as remote devbox / ephemeral CI runner / shared host.remote_sandbox_config in Harness distribution codex/.codex/config.toml.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.Requirements example:
allowed_sandbox_modes = ["read-only"]
[[remote_sandbox_config]]
hostname_patterns = ["devbox-*.corp.example.com"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
Usage patterns (via official plugin):
bash scripts/codex-companion.sh task --write "task description"
# Or via stdin
cat /tmp/prompt.md | bash scripts/codex-companion.sh task --write
Configure Unified Harness Memory.
# Create memory directories
mkdir -p .claude/agent-memory/claude-code-harness-worker
mkdir -p .claude/agent-memory/claude-code-harness-reviewer
# Place MEMORY.md template
cat > .claude/agent-memory/claude-code-harness-worker/MEMORY.md << 'EOF'
# Worker Agent Memory
## Project Context
[Project overview]
## Patterns
[Learned patterns]
EOF
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.
./scripts/sync-skill-mirrors.sh
./scripts/sync-skill-mirrors.sh --check
Update targets:
skills/codex/.codex/skills/opencode/skills/Configure the 3-agent setup in agents/.
agents/
├── worker.md # Implementation agent (task-worker + codex-implementer + error-recovery)
├── reviewer.md # Review agent (code-reviewer + plan-critic)
└── scaffolder.md # Scaffolding agent (project-analyzer + scaffolder)
Adapt rules in .claude/rules/ to the current project.
# Check rule list
ls .claude/rules/
# Add project-specific rules
cat >> .claude/rules/project-rules.md << 'EOF'
# Project-Specific Rules
[Project-specific rules]
EOF
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.
# 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.
claude plugin update owner/repo
Update merge conflicts were fixed in v2.1.71, enabling stable updates.
/plugin uninstall uses settings.local.json: Accurately reflected in user-local settingsFor 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 |
| Plugin dependency auto-resolve | Auto-install dependencies / missing dependency hints | 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.
Regular maintenance tasks:
| Task | Command |
|---|---|
| Delete old logs | find .claude/logs -mtime +30 -delete |
| Compress Plans.md | Move completed tasks to archive section |
| Delete old traces | tail -1000 .claude/state/agent-trace.jsonl > /tmp/trace && mv /tmp/trace .claude/state/agent-trace.jsonl |
harness-plan — Create project plan after setupharness-work — Execute tasks after setupharness-review — Review setup configuration