Skip to content
Skills Library
AI & agents · Automation

harness-setup

/harness-setup

Initializes and configures Harness in a project — CI, memory, duo workflow, Codex. Use when setting up a new project or adding Harness configuration.

Licence
MIT
Last repository change
05.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
3
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 05.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/merge-gitignore.sh, scripts/setup-codex.sh, scripts/setup-opencode.sh

What it does and when to use it

Initializes and configures Harness in a project — CI, memory, duo workflow, Codex. Use when setting up a new project or adding Harness configuration.

Arguments

/harness-setup [init|codex|opencode|duo|cleanup|gitignore]
Original author description

Initializes and configures Harness in a project — CI, memory, duo workflow, Codex. Use when setting up a new project or adding Harness configuration.

How it works

  1. Quick Reference
  2. Subcommand Details
  3. Related Skills
Original SKILL.md headings · 133 lines, 728 words
SKILL.md preview
---
name: harness-setup
description: "Initializes and configures Harness in a project — CI, memory, duo workflow, Codex. Use when setting up a new project or adding Harness configuration."
when_to_use: "initialize project, setup harness, configure CI, setup memory, duo workflow, gitignore"
allowed-tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"]
argument-hint: "[init|codex|opencode|duo|cleanup|gitignore]"
effort: medium
model: sonnet
---

# Harness Setup

## Quick Reference

| User Input | Subcommand | Behavior |
|------------|------------|----------|
| `harness-setup` (no args) | `init` | Runs `gitignore` → project initialization (CLAUDE.md + plans.json + settings.json) |
| `harness-setup init` | `init` | New project initialization: gitignore → CLAUDE.md + plans.json + settings.json |
| `harness-setup gitignore` | `gitignore` | Merge harness-managed block into .gitignore (runs `scripts/merge-gitignore.sh`) |
| `harness-setup cleanup` | `cleanup` | Periodic maintenance: delete old logs, archive completed phases (`harness plan-cli archive`), trim traces |
| `harness-setup codex` | `codex` | Set up Codex CLI: copy config, rules, and skills to project `.codex/` |
| `harness-setup opencode` | `opencode` | Set up OpenCode: copy config, commands, and skills to project `.opencode/` |
| `harness-setup duo` | `duo` | Set up both Codex and OpenCode in one step |

## Subcommand Details

### init — Project Initialization

Introduce Harness to a new project.

**Generated files** (user's project):
```
project/
├── CLAUDE.md            # Project configuration
├── .gitignore           # Standard ignore rules (harness-managed block appended)
└── .claude/
    ├── settings.json    # Claude Code permissions/sandbox/env
    ├── harness/plans.json  # Task tracking (auto-created by harness plan-cli)
    ├── memory/          # Trace archive + schemas (archive/, schemas/)
    ├── output-styles/   # Custom output styles (if any)
    ├── rules/           # Custom rules (if any)
    ├── scripts/         # Custom scripts (if any)
    └── skills/          # Custom skills (if any)
    └── settings.local.json # Local custom settings (gitignored) for user overrides
```

> **Note**: Neither `hooks/` nor `harness.toml` is generated into a user's project.
> - Hooks ship inside the installed plugin (`.claude-plugin/hooks.json`) — Claude Code
>   loads them from there automatically.
> - `harness.toml` + `harness sync` is a *plugin-author* workflow for regenerating
>   `.claude-plugin/*` files from a single TOML SSOT. User projects have no
>   `.claude-plugin/` to regenerate, so the TOML would be an orphaned file. Users who
>   want unified TOML authoring for their own `.claude/settings.json` can opt in later
>   via a dedicated subcommand (future work).

**Flow**:
1. Run the `gitignore` subcommand (idempotent — calls `scripts/merge-gitignore.sh`)
2. Detect project type (Node.js/Python/Go/Rust/Other)
3. Generate minimal CLAUDE.md
4. Create `.claude/harness/` directory (plans.json is auto-created on first `harness plan-cli add-phase` call)
5. Generate `.claude/settings.json` (permissions/sandbox/env — safe defaults)

### gitignore — Harness .gitignore Block

Merges the harness-managed block into the project's `.gitignore`. Safe to run multiple times — skips if the marker is already present.

Implementation: [`scripts/merge-gitignore.sh`](${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh)

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh"
# Or with an explicit target path:
bash "${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh path/to/.gitignore"
```

The block ignores `.claude/sessions/`, `logs/`, `settings.local.json`, and `states/`,
while force-tracking `.claude/memory/`, `.claude/output-styles/`, `.claude/rules/`,
`.claude/scripts/`, `.claude/skills/`, and `.claude/settings.json`.

### codex — Codex CLI Setup

Sets up the project for Codex CLI by copying Harness config templates and skills.
See [Codex CLI Setup Reference](${CLAUDE_SKILL_DIR}/references/codex.md) for full file layout and troubleshooting.

**Prerequisites**: Codex CLI installed (`npm install -g @openai/codex`)

**What it does**:
1. Checks that `codex` is installed; prints install instructions if not
2. Copies `templates/codex/*` → `.codex/` (config.toml, rules/harness.rules, .codexignore)
3. Copies `AGENTS.md` to the project root
4. Copies all skills from plugin `skills/` → `.codex/skills/` with `disable-model-invocation: true` patched into each SKILL.md frontmatter
5. Overlays `templates/codex-skills/` → `.codex/skills/` (codex-native variants of breezing and harness-work override the generic copies)

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/setup-codex.sh"
```

> **Note**: Excluded from the no-args `init` run — requires an external `@openai/codex` install that should be explicit opt-in.

### opencode — OpenCode Setup

Sets up the project for OpenCode by copying Harness config templates, commands, and skills.

**Prerequisites**: OpenCode installed (see https://opencode.ai/)

**What it does**:
1. Checks that `opencode` is installed; prints install instructions if not
2. Copies `templates/opencode/opencode.json` → `.opencode/opencode.json`
3. Copies `templates/opencode/commands/` → `.opencode/commands/`
4. Copies `AGENTS.md` to the project root
5. Copies all skills from plugin `skills/` → `.opencode/skills/` as-is (opencode ignores unknown frontmatter fields)

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/setup-opencode.sh"
```

> **Note**: Excluded from the no-args `init` run — requires OpenCode to be installed explicitly.

### duo — Codex + OpenCode Setup

Runs both `codex` and `opencode` setup subcommands in sequence.

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/setup-codex.sh"
bash "${CLAUDE_SKILL_DIR}/scripts/setup-opencode.sh"
```

### Cleanup

Periodic maintenance tasks:

| Task | Command |
|------|---------|
| Delete old logs | `find .claude/logs -mtime +30 -delete` |
| Archive completed phases | `harness plan-cli archive` |
| Delete old traces | `tail -1000 .claude/state/agent-trace.jsonl > /tmp/trace && mv /tmp/trace .claude/state/agent-trace.jsonl` |

## Related Skills

- `harness-plan` — Create project plans after setup
- `harness-work` — Execute tasks after setup
- `harness-review` — Review setup configuration
Files in this package (5)
  • SKILL.md 6 KB
  • references/codex.md 2 KB
  • scripts/merge-gitignore.sh 1 KB
  • scripts/setup-codex.sh 4 KB
  • scripts/setup-opencode.sh 3 KB

Versions

RepositoryScoreLicence
This page · tim-hub/powerball-harness100MIT
duc01226/EasyPlatform100MIT
duc01226/EasyPlatform100MIT
hoya324/oh-my-harness90MIT

Database snapshot: 13.11.2026 · package version 92d1175eeba7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100setup
    Initialize, upgrade, or migrate the claude-harness plugin in a project. Use for first-time setup, plugin installation, version migration, memory directory configuration, legacy file cleanup, and project harness initialization.
  • 100add-harness-package
    Guide for adding new AI SDK harness packages. Use when creating a new @ai-sdk/harness-<name> package that adapts a coding-agent runtime to HarnessV1.
  • 100harness-install
    将已经可用的 Harness Anything 接入一个尚无台账的目标仓库:检查项目、确认身份、初始化、合并 Agent 入口、建立主控知识位置,并用一个真实任务验证完整流程。缺少源码或 CLI 时先使用 harness-download 完成工具准备,再返回本流程;不重复维护下载步骤。
  • 95harness-docs
    Harness Kit documentation — installation, plugin catalog, creating plugins, cross-harness setup, architecture, and FAQ. Use when working with or configuring harness-kit plugins, understanding the plugin/skill system, installing slash commands, setting up AI coding tool…
  • 100harness
    Drives one change through the harness loop: plan, approval, test-first work, verify gates, review and ship. Use when the user types /90p:harness (Codex: $90p:harness) with a prompt, or with status, approve or abandon, in a repository that has .harness.yaml.
  • 100harness-init
    Initialize a new project with the Long-Running Agent Harness (vv-harness plugin). Sets up feature tracking, git identity capture, context summary, build hooks, quality gate hooks, and an optional workflow size guideline. Use when starting a new multi-session project.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.