{"id":51835308,"url":"https://github.com/penguinliao/loopharness","last_synced_at":"2026-07-22T20:32:58.887Z","repository":{"id":353900848,"uuid":"1221323719","full_name":"penguinliao/loopharness","owner":"penguinliao","description":"LoopHarness — evidence-first delivery for non-technical PMs and solo builders using Claude, Codex, Kimi or GLM.","archived":false,"fork":false,"pushed_at":"2026-07-14T08:00:13.000Z","size":336,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-14T10:04:15.463Z","etag":null,"topics":["agent-memory","ai-coding","claude-code","codex","developer-tools","glm","kimi","llm","solo-builders","spec-first","vibe-coding"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/penguinliao.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T03:36:39.000Z","updated_at":"2026-07-14T08:00:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/penguinliao/loopharness","commit_stats":null,"previous_names":["penguinliao/claude-hh-v1","penguinliao/loopharness"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/penguinliao/loopharness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penguinliao%2Floopharness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penguinliao%2Floopharness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penguinliao%2Floopharness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penguinliao%2Floopharness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/penguinliao","download_url":"https://codeload.github.com/penguinliao/loopharness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penguinliao%2Floopharness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35777195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-22T02:00:06.236Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-coding","claude-code","codex","developer-tools","glm","kimi","llm","solo-builders","spec-first","vibe-coding"],"created_at":"2026-07-22T20:32:58.153Z","updated_at":"2026-07-22T20:32:58.876Z","avatar_url":"https://github.com/penguinliao.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LoopHarness\n\n\u003e **Switch coding agents without losing project memory — and stop accepting “done” without evidence.**\n\n[中文](README.zh-CN.md)（非技术 PM / 超级个体 · 3 分钟上手） · Built for non-technical PMs, vibe coders, and solo builders using Claude, Codex, Kimi, or GLM.\n\n[![CI](https://github.com/penguinliao/loopharness/actions/workflows/ci.yml/badge.svg)](https://github.com/penguinliao/loopharness/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/penguinliao/loopharness)](https://github.com/penguinliao/loopharness/releases/latest)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-0b7285.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-f4b942.svg)](LICENSE)\n\n![LoopHarness delivery flight recorder](assets/loopharness-demo.svg)\n\nAI coding agents are good at producing code. The hard part is carrying your intent from one agent to another — and knowing whether “done” means *a file exists* or *the result was actually checked*.\n\n**Before LoopHarness**\n\n- Your project context lives inside one chat.\n- Switching from Claude to Codex or Kimi means explaining yourself again.\n- The agent says “tests passed”; you may not know what evidence still exists.\n\n**After LoopHarness**\n\n- Project memory, decisions, and delivery criteria live in project-owned files.\n- Every supported agent receives the same contract-bound context bundle.\n- Artifact receipts are re-checked against the current file hash.\n- A self-declared pass stays `Contract-only`; it cannot certify itself as production-ready.\n\n## The four-part loop\n\n1. **Remember** — keep explicit preferences, project notes, and decisions in `.agent-memory/`.\n2. **Delivery Contract** — lock the goal, acceptance criteria, risk, and allowed context.\n3. **Handoff** — compile the same minimal Markdown bundle for Claude, Codex, Kimi, or GLM.\n4. **Prove** — register artifacts, re-check their identity, and report what is still unverified.\n\nLoopHarness is a local, standard-library Python CLI. It does not require a cloud account or send project files to a LoopHarness server.\n\n## Install\n\n```bash\ngit clone https://github.com/penguinliao/loopharness.git \u0026\u0026 cd loopharness \u0026\u0026 bash install.sh\nexport PATH=\"$HOME/.local/bin:$PATH\"\nharness -h\n```\n\nThe installer copies the local implementation to `~/.loopharness` and creates `~/.local/bin/harness`. Re-running it is idempotent and does not duplicate shell PATH entries.\n\n## A three-minute honest demo\n\nThis demo connects to no model and no external service.\n\n```bash\nmkdir -p /tmp/loopharness-demo/docs \u0026\u0026 cd /tmp/loopharness-demo\nprintf 'Public release notes only.\\n' \u003e docs/brief.md\n\nharness memory-init\nharness contract \"Ship a reliable demo\" \\\n  --ac \"Help command runs\" \\\n  --ac \"Artifact receipt remains current\" \\\n  --allow docs/brief.md\n\nharness context \"Prepare the release\" --agent codex --include docs/brief.md\nprintf '1 passed\\n' \u003e functional.txt\nharness evidence functional functional.txt --outcome passed\nharness readiness\n```\n\nExpected output includes:\n\n```text\nartifact 声明回执已登记 ✓（functional / passed）\n  边界：只证明该文件登记时的身份与当前 hash，不证明内容真实或生产就绪。\n当前交付等级：Contract-only\n  当前声明回执（未独立验证）：functional\n  尚缺已验证证据：deployment、functional、preview、production_health、rollback、security\n```\n\nIn plain English: **Current delivery level: Contract-only.** The artifact has a current declaration, but no independent verification.\n\nThat `1 passed` file was written by the demo itself, so LoopHarness records it as **declared**, not independently verified. Now change the artifact and re-check:\n\n```bash\nprintf 'changed\\n' \u003e\u003e functional.txt\nharness readiness\n```\n\nThe current declaration disappears because the artifact hash no longer matches. LoopHarness did not prove the test result; it proved whether the registered artifact is still the same artifact.\n\n## Use it with Claude, Codex, Kimi, or GLM\n\nFirst create one contract. Then choose the adapter for the coding agent you are about to use:\n\n```bash\nharness context \"Implement the accepted contract\" --agent claude --include docs/brief.md\nharness context \"Implement the accepted contract\" --agent codex  --include docs/brief.md\nharness context \"Implement the accepted contract\" --agent kimi   --include docs/brief.md\nharness context \"Implement the accepted contract\" --agent glm    --include docs/brief.md\n```\n\nUse **one** of those commands, then:\n\n1. Tell that agent: `Read .delivery/context_bundle.md and implement only that contract.`\n2. Let the agent produce a real artifact such as a test report, screenshot, or rollback log.\n3. Register what exists: `harness evidence functional path/to/report.txt --outcome passed`.\n4. Re-check current state: `harness readiness`.\n\nThe adapter is a file protocol. LoopHarness **does not log in** to any model, control its session, import your full chat history, or make all four agents share the same native hooks. Claude retains the original project-hook journey; Codex, Kimi, and GLM consume the same contract and context bundle through their own host workflow.\n\n## Project memory, not chat-history scraping\n\n`harness memory-init` creates:\n\n```text\n.agent-memory/\n├── profile.md       # explicit working and communication preferences\n├── projects/        # project-owned notes\n├── decisions/       # durable decisions\n├── receipts/        # retained evidence pointers\n├── inbox.md         # learning candidates waiting for confirmation\n└── audit.jsonl      # local activity trail\n```\n\nThese files are portable because they live with your project. LoopHarness does **not** import your full Claude, Codex, Kimi, or GLM chat history. You decide what becomes durable memory.\n\n## Declared vs. verified evidence\n\n- **declared** — the CLI records the artifact path, size, SHA-256, outcome, and whether that artifact is still current. It does not prove the content is true.\n- **verified** — available only through the Python library API for a trusted host that has actually performed an independent check. The CLI cannot upgrade its own declaration.\n\nLoopHarness does not authenticate library callers and is not a sandbox against code that already has arbitrary write access to the project. Production decisions still require real tests, access control, backup/restore checks, and environment-specific acceptance.\n\n## The original spec-first pipeline\n\nThe existing workflow remains available:\n\n```bash\ncd your-project\nharness init\nharness start \"Build user search\"\nharness status\n# The agent follows SPEC → IMPLEMENT → REVIEW → TEST and runs harness advance.\n```\n\nREVIEW runs self-review, `ruff`/`mypy` when available, a fresh-context review, and a cross-family review. Unavailable external reviewers are shown as skipped rather than silently reported as passed.\n\n\u003cdetails\u003e\n\u003csummary\u003e中文兼容说明：无人值守、二审与 Hermes 晨报\u003c/summary\u003e\n\n- **无人值守**：可由支持 `/loop` 的宿主持续调用 `harness advance`；`/loop` 不是 LoopHarness CLI，也不是内置 scheduler。运行只会得到三类诚实结果：完成、重复失败后 `stuck`，或仅黑盒预算耗尽时生成 `delivery_report.md` 的带病交付。\n- **二审**：REVIEW 会尝试干净上下文和跨家族审查；CLI/API 不可用时明确显示 skipped，不冒充已审查。\n- **Hermes 晨报**：宿主定时读取 `.harness/inbox.md`，由 PM 在早晨确认候选。LoopHarness 提供文件与 `harness hermes-show`，不自带 cron、launchd 或定时云服务。\n\n\u003c/details\u003e\n\n## What LoopHarness is not\n\n- Not a hosted multi-agent control plane.\n- Not automatic full-history migration between model vendors.\n- Not proof that a declared artifact is correct.\n- Not a replacement for security review, human product acceptance, deployment controls, or monitoring.\n- Not a promise of a Star count, universal accuracy, or automatic production readiness.\n\n## Development\n\n```bash\npython3 -m pytest -q\nruff check .\npython3 -m compileall -q claude_hh\n```\n\nIssues with a reproducible delivery failure are especially useful. See the [issue tracker](https://github.com/penguinliao/loopharness/issues), [changelog](CHANGELOG.md), and [v1.4 release notes](RELEASE_NOTES.md).\n\nMIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpenguinliao%2Floopharness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpenguinliao%2Floopharness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpenguinliao%2Floopharness/lists"}