Chat Harness 开源：为 ChatGPT、Claude 等通用助手加项目级工程层

Harness engineering for AI assistants.

Bring harness-level discipline to long-running work with ChatGPT, Claude and other AI assistants.

Chat Harness is an open-source architecture and toolkit for applying harness engineering around general-purpose AI assistants. It combines context engineering, explicit durable project state, source-of-truth rules, resumable Workstreams, validation, guardrails, and bounded capability extension so substantial multi-session work is easier to resume, verify, and maintain.

It is not another agent runtime. The assistant still supplies its models, conversation loop, interfaces, files, connectors, tools, and native execution. Chat Harness adds the project-level engineering layer around those capabilities.

Why it exists

Coding harnesses made a useful pattern obvious: model quality is only part of reliable long-running work. Instructions, explicit state, context selection, source ownership, verification, checkpoints, recovery, and authority boundaries matter too.

General knowledge work has the same failure modes, but moving research, travel, household administration, career work, or scientific investigation into a coding harness is often the wrong abstraction. Chat Harness applies the useful harness disciplines around the assistant people already use.

The design principle is simple: use the host before building more framework. ChatGPT, Claude, and similar assistants already provide the models, interfaces, native tools, files, connectors, and execution. Chat Harness focuses on the project-level discipline around them.

Mental model

flowchart LR
    U["User"] --> H["AI assistant host<br/>models + conversations + native tools"]
    H --> A["AGENTS.md<br/>generic harness behavior"]
    A --> W["WORKSPACE.md<br/>Workspace-specific behavior"]
    W --> S["Workstreams / Procedures<br/>selective durable context"]
    S --> C["Domain corpus / external canon<br/>user-owned"]
    H --> N["Native capabilities<br/>web / files / apps / MCP"]
    N --> X{"Material gap?"}
    X -- "no" --> V["Verify + persist"]
    X -- "yes" --> E["Bounded Chat Harness capability"]
    E --> V

Loading

A Workspace is an ownership and durable-state boundary, not the complete context universe. Relevant context may live in other Workspaces, repositories, connected apps, assistant context systems, or current public sources. Retrieve it when it materially matters; keep canon in its owning source.

Installation

Release binaries are self-contained; the primary install does not require Bun or Node.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/carlosboeing/chat-harness/main/install.sh | sh

PowerShell:

irm https://raw.githubusercontent.com/carlosboeing/chat-harness/main/install.ps1 | iex

Both installers verify the matching SHA-256 sidecar. Set CHAT_HARNESS_VERSION to pin a release or CHAT_HARNESS_INSTALL_DIR to choose the destination.

The secondary npm channel requires Node 22.12+:

npm install -g chat-harness

Verify the CLI you are actually running:

chat-harness --version

After installation, lifecycle commands are channel-aware:

chat-harness update --check
chat-harness update
chat-harness uninstall

update uses GitHub Releases + SHA-256 verification for standalone binaries and delegates global npm updates to npm. uninstall removes the CLI only; Workspace/project data is never removed. See the CLI reference for provenance, Windows self-replacement, non-interactive confirmation, and safety details.

Quick start

The normal workflow is to run Chat Harness from inside the folder you want to use as a Workspace. For the current ChatGPT reference setup, use a folder stored in Google Drive so ChatGPT can access the Workspace through Project sources and connected Drive tooling:

cd /path/to/your/project
chat-harness setup --specialist tech
chat-harness validate
chat-harness doctor

The path is optional. You can target another existing directory explicitly when needed:

chat-harness setup /path/to/your/project --specialist tech

Chat Harness does not search parent directories for a Workspace.

setup creates the Chat Harness working scaffold without reorganizing your domain content:

<Project>/
├── _inbox/
├── .chat-harness/
│   ├── procedures/
│   ├── temp/
│   ├── workbench/
│   │   ├── 0-ideas/
│   │   ├── 1-research/
│   │   ├── 2-design/
│   │   ├── 3-plans/
│   │   └── 4-reviews/
│   ├── workstreams/
│   ├── source-policy.yaml
│   └── WORKSPACE.md
└── AGENTS.md

It is intentionally brownfield-safe: existing user-owned Workspace and domain content is preserved, a recognizably Chat Harness-managed AGENTS.md can be refreshed, and unknown same-name content is never silently adopted. If setup detects an existing root project-instructions file from an earlier harness, it preserves it and marks host activation as migration-required until its still-needed Workspace-specific behavior has been reviewed.

Creating the files is only the local half of setup. To use the Workspace with ChatGPT Projects:

1. add the Workspace's Google Drive folder to the ChatGPT Project as a source;
2. if setup reported migration_required, first review/migrate the legacy Workspace-specific behavior into .chat-harness/WORKSPACE.md;
3. copy the entire current AGENTS.md into ChatGPT Project Instructions.

The CLI cannot perform those hosted UI steps for you. Follow the beginner-friendly Getting Started guide or the illustrated ChatGPT setup guide.

How a Workspace works

The scaffold separates generic harness behavior from Workspace-specific knowledge and judgement:

• AGENTS.md — generic Chat Harness operating behavior.
• WORKSPACE.md — Workspace-specific role, judgement, evidence standards, boundaries, and approvals.
• Workstreams — compact current resume state for continuing objectives.
• Workbench — durable Markdown working artifacts: brainstorms, discovery, design, plans, and reviews.
• Procedures — reusable methodology for recurring tasks.
• Source Policy — narrow machine-readable privacy/source-handling rules.

For substantial work, the assistant follows a selective retrieval path:

AGENTS / Project Instructions
        ↓
WORKSPACE.md
        ↓
matching Workstream
        ↓
relevant Procedure / authoritative sources

The goal is not to load everything. It is to recover the right state and the minimum authoritative context needed for the task.

Specialists

A specialist gives a new Workspace domain-specific starting guidance by seeding WORKSPACE.md. It is not a separate agent or runtime mode; after setup, the file is yours to adapt.

Built-in specialists are general, research, tech, tax, finance, career, shopping, and travel.

chat-harness setup --specialist research

Specialists capture durable domain judgement and evidence standards. Procedures remain separate: a specialist describes how the Workspace generally works; a Procedure describes how a recurring task is performed.

See Specialists for the built-in seeds and setup behavior.

The operating loop

The assistant first classifies each request as Answer-only or Work. Direct, disposable lookups stay Answer-only. Planning, building, research, comparison, decisions, reviews, troubleshooting, implementation, and other resumable objectives are Work; ambiguity biases toward Work.

For every Work objective, the assistant proactively resumes or creates the Workstream before extended execution, creates each Workbench artifact when its trigger occurs, retrieves only the relevant authoritative context, verifies results, and leaves durable resumable state. It never waits for the user to ask it to save progress.

A Workstream records where the work is now, not every conversation that led there.

Workstreams and Workbench

Workstreams and Workbench are parallel outputs from work.

A Workstream is compact, continuously maintained resume state: objective, current direction, material rationale, blockers/open questions, relevant sources/artifacts, and an explicit Next action.

The Workbench holds raw Markdown artifacts under five purpose-driven categories: ideas (frame an open-ended objective), research (establish evidence), design (turn evidence into direction), plans (make direction executable), and reviews (evaluate an existing thing). These are trigger-based artifact classes, not a required waterfall.

Source ownership and Source Policy

Chat Harness treats source ownership as part of reliability. Search results, assistant memory, summaries, and derived reports do not become authoritative merely because they are convenient.

.chat-harness/source-policy.yaml adds narrow machine-readable privacy/source-handling rules. Source Policy is not IAM or a general configuration system. Chat Harness can mechanically enforce it only on access paths it controls; host-native retrieval may be instruction-governed where no enforcement hook exists.

See Security.

Usage

Workspace commands (setup, validate, and doctor) accept an optional [path]; when omitted, they use the current directory. Lifecycle commands operate on the detected CLI installation and never take a Workspace path.

Interactive setup explains choices before asking for consent, shows the complete resulting Workspace tree with human-readable status labels, and asks for approval before writing.

Common setup options:

Examples:

chat-harness setup
chat-harness setup --specialist travel
chat-harness setup --specialist tech --scaffold-domain
chat-harness setup --dry-run
chat-harness validate --json
chat-harness doctor
chat-harness update --check
chat-harness update
chat-harness uninstall

Run chat-harness --help or chat-harness <command> --help for terminal help. See the complete CLI reference for behavior, safety rules, automation, and exit codes.

Bounded capability extension

Native assistant capabilities come first. When a real gap remains, Chat Harness can expose a specific typed external capability rather than generic remote execution.

The repository includes one concrete reference path under extensions/github/: an owner-gated GitHub Issue → Actions transport for public-data, no-credential, read-only capabilities. Its current durable capability is linkedin.job.lookup.

The GitHub transport is persistent repository data, so its security profile is deliberately narrow. The shared Playwright helper is bounded but is not claimed to be a complete network-egress sandbox.

See Capability lifecycle.

Compatibility

Support is tracked as documented, verified, or unverified; architectural similarity alone is not a support claim.

ChatGPT Projects are the reference hosted binding. Other assistants can use the architecture where equivalent instruction, context, and capability primitives exist, but support remains evidence-based.

See Compatibility.

What Chat Harness does not build

Chat Harness deliberately does not include a replacement agent loop, model-provider abstraction, chat UI, daemon, scheduler, workflow engine, global memory database, universal domain taxonomy, runtime specialist hierarchy, generic unrestricted browser/HTTP/shell capability, or automatic hosted Project configuration.

These are not missing abstractions waiting to be filled by default. They require real implementation pressure.

Documentation

Start with the Getting Started guide or the documentation guide.

• CLI reference
• Architecture
• Concepts
• Specialists
• Security
• Compatibility
• ChatGPT host binding
• Alternatives and fit
• Capability lifecycle

The repository also includes worked examples and behavioural evals. Historical release and design records are kept separately from current user documentation.

Development

Development uses Bun and strict TypeScript.

bun install --frozen-lockfile
bun run typecheck
bun run validate
bun run validate:docs
bun run validate:evals
bun run test

To test unreleased changes through the real standalone chat-harness command without cutting a release:

git pull
bun run install:local
chat-harness --version

The local installer builds the current checkout for your platform and installs it to ~/.local/bin/chat-harness by default. Development builds report <package-version>-<short-git-sha> (plus -dirty when the checkout has uncommitted changes), so they are easy to distinguish from published releases. Override the destination with CHAT_HARNESS_BIN_DIR.

The installer also checks which chat-harness executable wins on PATH and warns if the new local build is not the active command.

See CONTRIBUTING.md for development and release guidance.