harness-kit
Tổng quanOverview Bắt đầuGet Started Cài SkillInstall Skill Use CasesUse Cases Học HarnessLearn Harness GitHub
Chỉ dùng thư viện chuẩn · Python 3.8+ Standard Library Only · Python 3.8+

Governance layer cho mọi
AI coding agent Governance layer for any
AI coding agent

Harness Kit cung cấp quy tắc rõ ràng, state có thể restart, và verification gate — cho mọi ngôn ngữ và stack. Tích hợp với Claude Code, Cursor, Codex, Windsurf. Harness Kit gives your AI agents clear rules, tracked state, and a verification gate — for any language and stack. Works with Claude Code, Cursor, Codex, Windsurf.

Bắt đầu ngay Get Started Tìm hiểu các thành phần Explore Subsystems
bash — harness-kit-demo
PS> irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex
Khởi tạo governance files... Đã tạo: AGENTS.md, feature_list.json, progress.md Đã tạo: session-handoff.md, init.ps1, hk.pyScaffolding governance files... Created: AGENTS.md, feature_list.json, progress.md Created: session-handoff.md, init.ps1, hk.py Hoàn thành. 6 tệp đã được tạo.Done. 6 files written.
PS> py hk.py feature "User authentication"
[+] F-001: User authentication
PS> py hk.py start F-001
[→] Active: F-001 — User authentication Nói với AI: "Đọc AGENTS.md và implement feature đang active."[→] Active: F-001 — User authentication Tell your AI: "Read AGENTS.md and implement the active feature."
Kiến trúc Cốt lõi Core Architecture

5 Phân Hệ và 9 Thành phần 5 Subsystems and 9 Components

Instructions (Chỉ dẫnGuidelines)

Lắp ráp prompt động thân thiện với prompt cache. Tự động quét tìm file chỉ dẫn (CLAUDE.md, AGENTS.md) từ thư mục dự án và cha để nạp luật cho AI. Caching-friendly dynamic guidelines aggregator. Walks ancestor directories to find instruction files (CLAUDE.md, AGENTS.md) and injects them under the static prompt.

prompt_assembly.py

State (Trạng tháiState Preservation)

Ghi log trạng thái append-only JSONL bền bỉ và tự động nén token thông minh (Context Compaction) khi đạt 80% ngưỡng nhằm chống bùng nổ ngữ cảnh. Manages token budget with reactive context compaction when exceeding 80% limit. Preserves durability via append-only JSONL event logs flushed instantly.

persistence.py & context_manager.py

Verification (Xác minhVerification)

Tích hợp sẵn các primitives để chạy tự động kiểm tra biên dịch cú pháp hoặc các suite thử nghiệm (init.sh / init.bat) để bảo đảm an toàn. Standard primitives to execute syntax compilation checks (py_compile) and auto-test commands (init.sh, init.bat) to verify code health before exit.

built-in primitives

Scope (Phạm vi & An toànScope & Security)

Bộ quản trị quyền lực: phân quyền đọc/ghi, phân loại câu lệnh shell động để cảnh báo trước mã nguy hại, cô lập và quản lý tác nhân con. Enforces permission boundaries (read-only, write, full), dynamically classifies shell commands to prevent dangerous execution, and runs isolated sub-agents.

tool_registry.py & subagent.py

Lifecycle (Vòng đờiLifecycle)

Điều phối vòng lặp execution loop chính, hỗ trợ đăng ký pre-tool hook (để chặn/sửa đổi đối số) và post-tool hook (để audit telemetry) an toàn. Orchestrates the outer while execution loop, triggering customizable pre-tool hooks (for security filtering) and post-tool hooks (for auditing).

harness.py & hooks.py
Bắt đầu Getting Started

Hai cách làm việc Two ways to work

Chọn nền tảng của bạn Pick your platform

Sau khi cài, có hai cách làm việc: prompt AI bằng ngôn ngữ tự nhiên — agent tự đọc AGENTS.md — hoặc dùng hk.py từ terminal bất kỳ. Không cần plugin hay extension. After install, two ways to work: prompt your AI in natural language — the agent reads AGENTS.md automatically — or use hk.py from any terminal. No plugin or extension needed.

1 Cài vào thư mục gốc dự án (chạy 1 lần) Install into your project root (once)
2 Prompt AI bằng ngôn ngữ tự nhiên — agent tự đọc AGENTS.md Prompt your AI in plain language — agent reads AGENTS.md automatically
3 Hoặc dùng hk.py từ terminal, CI, hay script Or use hk.py from any terminal, CI, or script
4 Kiểm tra điểm harness bất kỳ lúc nào Audit the harness score anytime 
Loading...
Loading...
1. LLM API Output Loop Stateful Loop
2. Hook Gating & Shell Classifier tool_registry.py
3. Execution & Compactor persistence.py

Luồng Chạy Tự Động Bền Bỉ Robust, Durable Execution Flow

Mỗi lượt hành động của AI Agent được kiểm soát thông qua một cơ chế gá lái chặt chẽ: Every action in the execution loop is controlled by a secure gating harness:

  • All-or-Nothing Hook: Nếu không tin cậy thư mục làm việc, toàn bộ hook mở rộng của bên thứ ba sẽ bị ngắt tự động để tránh chạy code lén lút. All-or-Nothing Hook: If the workspace is marked as untrusted, all dynamic third-party hooks are automatically skipped to guarantee zero arbitrary code execution.
  • Dynamic Classification: Phân loại động lệnh shell thời gian thực. Bắt buộc dừng xin xác nhận người dùng đối với các lệnh nguy hại. Dynamic Classification: Classifies shell commands at runtime. Halts execution and triggers interactive prompts for dangerous commands like `rm` and `sudo`.
  • JSONL Durability: Ghi trạng thái lập tức xuống đĩa đệm. Trong trường hợp sập tiến trình, chỉ cần replay logs để dựng lại 100% ngữ cảnh cũ. JSONL Durability: Flushes session logs to disk immediately. Replays event logs sequentially to reconstruct 100% of the conversation context after a crash.
Cài Đặt Install

Một lệnh — mọi dự án One command — any project

Chạy từ thư mục gốc dự án của bạn. Tương thích với Claude Code, Cursor, Codex, Windsurf — mọi AI đọc instruction file. Run from your project root. Works with Claude Code, Cursor, Codex, Windsurf — any AI that reads an instruction file.

Mặc định — Governance only (mọi ngôn ngữ, mọi stack) Default — Governance only (any language, any stack)

macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh
Windows (PowerShell)
irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex

Full harness — Thêm Python runtime (vòng lặp agent, subagent, hooks) Full harness — adds Python runtime (agent loop, subagents, hooks)

macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh -s -- --full
Windows (PowerShell)
& ([ScriptBlock]::Create((irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1))) --full

Yêu cầu: Python 3.8+, git Requirements: Python 3.8+, git

Những file được tạo trong dự án của bạn What gets created in your project

File Mục đíchPurpose
AGENTS.md Quy tắc AI đọc khi bắt đầu mỗi phiên làm việcRules your AI reads on every session start
feature_list.json Tính năng đang thực hiện, trạng thái, phụ thuộcActive feature, status, dependencies
progress.md AI ghi tiến độ vào đây sau mỗi phiênAI writes progress here after each session
init.sh / init.ps1 Script kiểm tra xác thực (tests, lint, build)Verification script (tests, lint, build)
session-handoff.md Ngữ cảnh bàn giao cho phiên AI tiếp theoContext for the next session
harness/ (--full) 7 Python module: vòng lặp agent, tool registry, subagent, hooks, context, persistence, prompt7 Python modules: agent loop, tool registry, subagent, hooks, context, persistence, prompt

Dùng --agent-file CLAUDE.md nếu tool đọc CLAUDE.md thay vì AGENTS.md. Dùng --full để thêm Python runtime. Use --agent-file CLAUDE.md if your tool reads CLAUDE.md instead of AGENTS.md. Use --full to add the Python runtime.

Phát triển & Đóng góp Develop & Contribute

Clone và chạy cục bộ Clone and run locally

Nếu bạn muốn chỉnh sửa, đóng góp hoặc kiểm tra harness-kit: To edit, contribute, or test harness-kit locally: 

git clone https://github.com/nguyenanh92/harness-kit.git
cd harness-kit
py skills/scripts/scaffold_harness.py --target test_run
py skills/scripts/validate_harness.py --target test_run
Tích Hợp Với IDE IDE Integration

Làm việc với Claude Code, Cursor, Antigravity, OpenAI Codex Work with Claude Code, Cursor, Antigravity, OpenAI Codex

Chạy lệnh cài một lần để tạo governance files, rồi mở AI tool và bắt đầu. Muốn cài harness-kit như một skill tích hợp sâu, xem trang Cài Skill → Run the one-liner to create governance files, then open your AI tool and start. For deep skill integration see the Install Skill guide →

Yêu cầu:Prerequisite: Claude Code đã cài (npm install -g @anthropic-ai/claude-code) và đã đăng nhập bằng claude. Xem docs.claude.com. Claude Code installed (npm install -g @anthropic-ai/claude-code) and authenticated via claude. See docs.claude.com.
Step 1

Cài governance files vào project Install governance files into your project

Chạy lệnh này ở thư mục gốc dự án — tạo AGENTS.md, feature_list.json, progress.md, hk.py, và init scripts: Run this at your project root — creates AGENTS.md, feature_list.json, progress.md, hk.py, and the init scripts: 

# Windows (PowerShell)
irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh
Step 2

Kích hoạt skill trong chat Activate the skill from chat

Claude Code tự phát hiện skill ngay trong phiên hiện tại — không cần restart. Gõ trigger như "use harness-kit to scaffold a Python agent harness". Claude Code auto-discovers the skill within the current session — no restart needed. Trigger with a prompt like "use harness-kit to scaffold a Python agent harness".

Step 3

Tuỳ chọn: cài harness-kit như một Skill Optional: install harness-kit as a Claude Code Skill

Muốn Claude tự biết dùng harness-kit trong mọi dự án (không cần giải thích mỗi lần), hãy cài như một skill user-level. Xem hướng dẫn đầy đủ tại: To let Claude invoke harness-kit by name across all projects without explaining it each time, install it as a user-level skill. Full instructions at:

→ Hướng dẫn cài Skill → Install Skill guide

Yêu cầu:Prerequisite: Cursor IDE đã cài (cursor.com/download hoặc winget install Cursor.Cursor) và đã đăng nhập. Cursor IDE installed (cursor.com/download, or winget install Cursor.Cursor) and signed in.
Step 1

Cài governance files vào project Install governance files into your project

Chạy lệnh này ở thư mục gốc dự án — Cursor agent sẽ đọc AGENTS.md được tạo ra để biết quy trình làm việc: Run this at your project root — Cursor's agent will pick up the generated AGENTS.md to understand the workflow: 

# Windows (PowerShell)
irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh
Step 2

Mở project trong Cursor và prompt agent Open the project in Cursor and prompt the agent

Cursor tự đọc AGENTS.md ở gốc dự án. Gõ vào Composer/Chat: Cursor picks up AGENTS.md from the project root automatically. Type in Composer/Chat: 

> "Read AGENTS.md and implement the active feature in feature_list.json."
> "Add a new feature for the Settings screen and start working on it."
> "Run hk.py status and tell me what to do next."
Step 3

Tuỳ chọn: cài harness-kit như Cursor Rule Optional: install harness-kit as a Cursor Rule

Muốn Cursor tự biết quy trình harness-kit mà không cần nhắc lại — cài SKILL.md thành một .cursor/rules/*.mdc. Xem hướng dẫn đầy đủ tại: To have Cursor understand the harness-kit workflow without prompting each time, install SKILL.md as a .cursor/rules/*.mdc. Full guide at:

→ Hướng dẫn cài Skill → Install Skill guide

Yêu cầu:Prerequisite: Antigravity đã cài (antigravity.google) và đã đăng nhập bằng tài khoản Google. Antigravity installed (antigravity.google) and signed in with a Google account.
Step 1

Scaffold AGENTS.md vào gốc dự án Scaffold AGENTS.md into the project root

Antigravity (Google, convention 2026) đọc AGENTS.md ở gốc dự án (chuẩn cross-tool). Lệnh cài tạo sẵn AGENTS.md, feature_list.json, progress.md, init.sh/init.ps1: Antigravity (Google, 2026 convention) reads AGENTS.md at the project root as the cross-tool standard. The one-liner drops all key governance files: 

# Windows (PowerShell)
irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh
Step 2

Bật skill native qua .agents/skills/ Enable native skills via .agents/skills/

Antigravity còn hỗ trợ thư mục native .agents/skills/. Muốn cài harness-kit như một Antigravity native skill, cần clone repo trước. Xem hướng dẫn đầy đủ: Antigravity also supports a native .agents/skills/ folder. To install harness-kit as a native Antigravity skill (requires cloning the repo), see the full guide:

→ Hướng dẫn cài Skill → Install Skill guide

Step 3

Kiểm chứng quy trình Verify the workflow

Mở project trong Antigravity, yêu cầu agent: "Đọc AGENTS.md và thực thi feature đang in_progress trong feature_list.json". Agent sẽ chạy init.ps1/init.sh để verify trước khi đánh dấu done. Open the project in Antigravity and prompt: "Read AGENTS.md and execute the in_progress feature from feature_list.json". It will run init.ps1/init.sh for verification before flipping the status to done.

Yêu cầu:Prerequisite: Codex chưa có IDE riêng — Step 1 sẽ cài CLI / extension (đây cũng là consumer đọc skill). Codex has no dedicated IDE — Step 1 installs the CLI / extension, which is also the consumer that reads the skill.
Step 1

Cài Codex CLI hoặc IDE Extension Install the Codex CLI or IDE Extension

OpenAI Codex đọc AGENTS.md ở gốc dự án và merge cascade từ các thư mục cha. Extension chính thức hỗ trợ VS Code, Cursor, và Windsurf. OpenAI Codex reads AGENTS.md at the project root (cascading from parent dirs). OpenAI's official IDE extension supports VS Code, Cursor, and Windsurf. 

npm install -g @openai/codex

# Khởi động và đăng nhập bằng ChatGPT Plus / Pro / API key
codex login

Tham khảo thêm tại developers.openai.com/codex/cli. See developers.openai.com/codex/cli for full setup details.

Step 2

Scaffold AGENTS.md vào root Scaffold AGENTS.md into the root

Giống Antigravity, Codex bắt AGENTS.md ở gốc dự án. Lệnh cài tạo luôn governance docs cần cho validator chấm 100/100. Like Antigravity, Codex picks up AGENTS.md from the project root. The one-liner drops all governance docs needed for the validator to score 100/100. 

# Windows (PowerShell)
irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh
Step 3

Chạy Codex tại root Launch Codex from the root

Mở terminal tại root dự án, gọi codex. Agent sẽ đọc AGENTS.md và làm theo Definition of Done. Trong VS Code, mở Codex side panel — extension đọc cùng file. Open a terminal at the project root and run codex. The agent reads AGENTS.md and follows the Definition of Done. In VS Code, open the Codex side panel — the extension reads the same file. 

codex   # CLI mode