cross-platform-ai-harness - GitLite

KO | EN

gitlite — search

#javascript #security #redis #nlp #awesome-list #agents #list #automation #nodejs #cli

cross-platform-ai-harness

(★ 9)

Use AI across different devices and tools — Claude, Codex, OpenCode, Pi, Antigravity, and more — with the same workflow and mindset.

File Explorer

ZIP Download

- commit-msg
- pre-commit
- - AGENTS.md
  - history.md
  - TODO.md
- - AGENTS.md
  - history.md
  - TODO.md
- - AGENTS.md
  - history.md
  - TODO.md
- ssh-aliases.conf
- - AGENTS.md
  - history.md
- - AGENTS.md
  - history.md
- audit.sh
- behavior-check.sh
- check.ps1
- check.sh
- commit.sh
- dashboard.sh
- install-ssh.ps1
- install-ssh.sh
- inventory.sh
- lib.sh
- new-leaf.sh
- preflight.sh
- selftest.sh
- verify.sh
- - AGENTS.md
- - AGENTS.md
- - AGENTS.md
- - AGENTS.md
- - AGENTS.md
.gitignore
AGENTS.md
CONSTANTS.md
HARNESS.md
INDEX.md
ONBOARDING.md
README.md
setup.sh

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> **Two editions.** This is the **detailed** edition — worked examples, an onboarding
> generator, and more sensors/actuators. Want the minimal, read-it-in-5-minutes
> version? See the [**`basic` branch**](https://github.com/muzafferkadir/cross-platform-ai-harness/tree/basic).

A small, **working** agent harness: the files, rules, and checks that make a raw AI
CLI (Claude Code, Codex, Gemini, …) behave the same way on every machine — and catch
its own mistakes.

> **Agent = Model + Harness.** The model is the engine; the harness is everything
> that makes it useful and safe. *A decent model with a great harness beats a great
> model with a bad one.*

It's not a framework you install. It's a small set of plain files you own and grow.
Read it in 5 minutes, copy it, delete what you don't need.

## The idea: four kinds of files

| Role | Lives in | When | Does |
|---|---|---|---|
| **Guide** | `.md` | before the agent acts | pushes it in the right direction (rules, routing, how-tos) |
| **Sensor** | `.sh` | after the agent acts | catches mistakes early (syntax, secrets, tests, hooks) |
| **State** | `.md` | across sessions | remembers tasks (`TODO.md`) and decisions (`history.md`) |
| **Actuator** | `.sh` | on demand | actually does / repairs things (setup, commit, self-heal) |

Guides push work forward; sensors catch it when it slips. You need both — a car
with a steering wheel but no brakes is not safer for going faster.

One **git repo** holds all of it, so every machine and every tool shares one brain.

## Structure

```
AGENTS.md            guide     — injected into every AI tool (rules + routing)
HARNESS.md           guide     — bootstrap protocol + the four roles + credits
ONBOARDING.md        guide     — generator: interview + fill leaves for your setup
CONSTANTS.md         guide     — non-secret @key values (IPs, ports)
INDEX.md             guide     — navigation map
setup.sh             actuator  — install on this machine (symlinks + hooks)
.githooks/
  pre-commit         sensor    — runs preflight inside this repo, passes through elsewhere
  commit-msg         sensor    — blocks AI attribution in the message (any repo, fail-open)
scripts/
  lib.sh             —         shared helpers (machine, python, links, patterns)
  check.sh           sensor+actuator — self-heal symlinks, hook perms, ssh aliases
  check.ps1          sensor+actuator — Windows: verify + self-heal ssh aliases & tools
  preflight.sh       sensor    — block AI attribution + staged secrets, then run verify
  verify.sh          sensor    — shell syntax + JSON parse + symlink targets
  behavior-check.sh  sensor    — run each TODO's done-condition (+ --mutate self-test)
  audit.sh           sensor    — periodic content scan (structure/attribution/secrets/stale)
  selftest.sh        sensor    — proves the sensors themselves work, in a sandbox HOME
  commit.sh          actuator  — preflight → append history → commit (push is opt-in: --push)
  new-leaf.sh        actuator  — scaffold a machine/tool/skill/project leaf from its _template
  install-ssh.sh/.ps1 actuator — sync ssh aliases from machines/ssh-aliases.conf
  inventory.sh       read-only — print evidence-backed inventory rows for a machine leaf
  dashboard.sh       read-only — open tasks across all machines
machines/<host>/     AGENTS.md (inventory) · TODO.md (tasks) · history.md (decisions)
machines/ssh-aliases.conf  source of truth for managed ssh aliases
tools/<tool>/        AGENTS.md            (worked example: tools/claude-code)
skills/<skill>/      AGENTS.md            (examples: skills/deploy, skills/ssh-tunnel)
projects/<project>/  AGENTS.md · history.md  (worked example: projects/example-webapp)
_template/ dirs      copied by setup.sh / onboarding when you add a new leaf
```

Every directory ships a filled-in **worked example** (`example-*`) next to its bare
`_template`. The example shows a leaf at full richness so an agent can copy the
pattern; delete the examples once you have your own.

## Quickstart

```bash
# 1. get it (or `git init` in a fresh folder and copy these files in)
git clone <your-fork-url> harness && cd harness

# 2. install on this machine (idempotent: symlinks + LOCAL git hooks + self-heal).
#    setup.sh auto-detects your installed AI tools (Claude, Codex, opencode, Cursor,
#    Gemini, Aider) — no manual list to edit for the common cases.
bash setup.sh

# 3. see a sensor work (acceptance test):
git commit -m "hello" --allow-empty                       # ✓ passes
printf 'x\n\nCo-Authored-By: bot <b@x>\n' | git commit -F - --allow-empty
                                                          # ✗ BLOCKED by commit-msg
```

### Make it yours (the fast way)

The templates are generic on purpose — your machines, tools, and projects aren't
mine. Instead of editing every file by hand, hand the repo to an AI agent:

```
Read ONBOARDING.md and onboard me.
```

It interviews you, fills the leaves from the templates (running real commands for
inventory — no guesses), wires up routing, and verifies its work. `ONBOARDING.md`
also works as a plain checklist if you'd rather do it yourself.

> **Keep your copy private.** Once onboarded, the repo holds your hostnames,
> addresses, and project notes — personal data. This starter is public; *your* copy
> shouldn't be. Use a private fork or a local-only repo. See `ONBOARDING.md` →
> Privacy boundary.

> **Tool detection.** `bootstrap_links()` in `scripts/lib.sh` auto-detects installed
> tools (Claude, Codex, opencode, Cursor, Gemini, Aider) by their config dir, so the
> common cases need no edit. For a tool it doesn't know, either add a one-line probe
> in that function or export extra paths: `HARNESS_TOOL_LINKS="$HOME/.mytool/AGENTS.md"
> bash setup.sh`. `check.sh`/`verify.sh` report exactly which links are wired, so
> nothing is injected silently.

`setup.sh` uses **`--local`** `core.hooksPath` on purpose: it only guards *this*
repo. A global `core.hooksPath` guards every repo you own, which is powerful but
means each hook must early-exit when it isn't the intended repo (both hooks here do).

The **"pull first"** rule in `AGENTS.md` applies once you have a shared remote and
more than one machine; on a brand-new local repo you can ignore it.

## Grow it with the ratchet

Start with just `AGENTS.md` and one hook. Each time the agent makes a mistake you
care about, add **one** guide or sensor so it can't happen again — and drop rules
that stop earning their keep. The harness tightens itself over time; every line in a
good `AGENTS.md` should trace back to something that once went wrong.

## Credits

- **Agent = Model + Harness** — Viv Trivedy
- **Guides & sensors**, computational vs inferential — Birgitta Böckeler ([martinfowler.com](https://martinfowler.com/articles/exploring-gen-ai.html))
- **Ratchet principle** and the term *harness engineering* popularized by **Addy Osmani** ([addyosmani.com](https://addyosmani.com/blog/agent-harness-engineering/))