{"id":49881731,"url":"https://github.com/majiayu000/harness","last_synced_at":"2026-05-30T05:01:01.031Z","repository":{"id":342721205,"uuid":"1170625768","full_name":"majiayu000/harness","owner":"majiayu000","description":"Rust AI agent orchestration platform with App Server, rules, skills, GC, and observability.","archived":false,"fork":false,"pushed_at":"2026-05-28T22:05:23.000Z","size":7238,"stargazers_count":27,"open_issues_count":29,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T23:21:35.102Z","etag":null,"topics":["ai-agent","ai-tools","cli","developer-tools","llm","observability","orchestration","rules-engine","rust","skills"],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/majiayu000.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-02T10:34:21.000Z","updated_at":"2026-05-27T20:57:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/majiayu000/harness","commit_stats":null,"previous_names":["majiayu000/harness"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/majiayu000/harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fharness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fharness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fharness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fharness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/majiayu000","download_url":"https://codeload.github.com/majiayu000/harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majiayu000%2Fharness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33680527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"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":["ai-agent","ai-tools","cli","developer-tools","llm","observability","orchestration","rules-engine","rust","skills"],"created_at":"2026-05-15T15:00:32.202Z","updated_at":"2026-05-30T05:01:01.020Z","avatar_url":"https://github.com/majiayu000.png","language":"Rust","funding_links":[],"categories":["\u003ca name=\"Rust\"\u003e\u003c/a\u003eRust"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Harness\n\n**An orchestration layer for AI coding agents — govern, observe, and improve agent workflows at scale.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![MSRV](https://img.shields.io/badge/MSRV-1.88-orange.svg)](Cargo.toml)\n[![CI](https://img.shields.io/github/actions/workflow/status/majiayu000/harness/ci.yml?branch=main\u0026label=CI)](https://github.com/majiayu000/harness/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/majiayu000/harness?include_prereleases\u0026label=release)](https://github.com/majiayu000/harness/releases)\n[![Issues](https://img.shields.io/github/issues/majiayu000/harness?label=issues)](https://github.com/majiayu000/harness/issues)\n[![Pull Requests](https://img.shields.io/github/issues-pr/majiayu000/harness?label=PRs)](https://github.com/majiayu000/harness/pulls)\n[![Security Policy](https://img.shields.io/badge/security-policy-brightgreen.svg)](SECURITY.md)\n\n![AI Agents](https://img.shields.io/badge/AI_Agents-222222.svg)\n![Multi-Agent Orchestration](https://img.shields.io/badge/Multi--Agent-Orchestration-4c6fff.svg)\n![Policy Engine](https://img.shields.io/badge/Policy-Engine-0f766e.svg)\n![Observability](https://img.shields.io/badge/Observability-OTLP-7c3aed.svg)\n![MCP Server](https://img.shields.io/badge/MCP-Server-2563eb.svg)\n\n[Documentation](docs/) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)\n\n\u003cimg src=\"docs/images/harness-card.png\" alt=\"Harness repository card\" width=\"920\" /\u003e\n\n\u003c/div\u003e\n\n---\n\nHarness is a Rust-native platform that wraps AI coding agents (Claude Code, Codex, Anthropic API) with structured lifecycle management, policy enforcement, and continuous feedback loops. Instead of replacing agents, it standardizes how they run, what they're allowed to do, and how their output is reviewed.\n\n## Key Features\n\n- **Multi-agent orchestration** — Pluggable adapters for Claude Code CLI, Codex CLI, and Anthropic API with unified task/thread/turn lifecycle\n- **Independent agent review** — Automatic cross-agent code review between implementation and GitHub review, preventing self-review by architecture\n- **Policy engine** — Starlark-based execution policies with hardened parser dialect (no `load`/`def`/`lambda`) for sandboxed rule evaluation\n- **Signal-driven GC** — Detects repeated warnings, chronic blockers, and hot files; generates and adopts remediation drafts within configurable budgets\n- **GitHub webhook automation** — HMAC-SHA256 verified webhooks parse `@harness` mentions to trigger tasks from issue comments and PR reviews\n- **OpenTelemetry export** — Native OTLP/HTTP/gRPC traces and metrics with async-safe transport for signal-handler contexts\n- **MCP server mode** — JSON-RPC stdio interface exposing harness tools as an MCP-compatible server\n- **CI/CD GitHub Action** — Workspace-bound execution with path traversal protection and privilege enforcement\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        Harness CLI                          │\n│              serve · exec · gc · rule · skill               │\n├──────────┬──────────┬───────────────────────────────────────┤\n│  stdio   │   HTTP   │  WebSocket   │  MCP Server  │ Webhook│\n├──────────┴──────────┴──────────┴───┴──────────────┴────────┤\n│                    JSON-RPC Router (30 methods)             │\n├────────────┬─────────────┬────────────┬────────────────────┤\n│   Threads  │    Tasks    │   Turns    │    ExecPlans       │\n├────────────┴─────────────┴────────────┴────────────────────┤\n│  harness-agents    │  harness-rules   │  harness-skills    │\n│  (Claude/Codex/API)│  (Starlark exec) │  (discovery/dedup) │\n├────────────────────┼──────────────────┼────────────────────┤\n│  harness-gc        │  harness-observe │  harness-exec      │\n│  (signal/drafts)   │  (events/OTLP)  │  (plan lifecycle)  │\n├────────────────────┴──────────────────┴────────────────────┤\n│                    harness-core                             │\n│          config · prompts · domain types · traits           │\n├────────────────────────────────────────────────────────────┤\n│                    harness-protocol                         │\n│       JSON-RPC envelopes · method definitions · codecs      │\n└────────────────────────────────────────────────────────────┘\n        ▼               ▼                ▼\n   Claude Code CLI   Codex CLI    Anthropic API\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Rust 1.88+\n- Bun 1.1+ for release builds that embed the web dashboard. If `web/dist` is\n  already built, release builds can reuse it.\n- At least one agent runtime:\n  - [`codex`](https://github.com/openai/codex) CLI\n  - [`claude`](https://docs.anthropic.com/en/docs/claude-code) CLI\n  - Anthropic API key (for direct API adapter)\n\n### Build\n\n```bash\ngit clone https://github.com/majiayu000/harness.git\ncd harness\ncargo build\n```\n\n### Rust API Facade\n\nFor Rust consumers inside the repository or embedded integrations, `harness-api`\nprovides a curated stable import surface over the lower-level crates:\n\n```rust\nuse std::path::Path;\n\nuse harness_api::core::SessionId;\nuse harness_api::exec::ExecPlan;\nuse harness_api::protocol::INTERNAL_ERROR;\nuse harness_api::sandbox::{SandboxMode, SandboxSpec};\n\nlet _session = SessionId::new();\nlet _plan = ExecPlan::from_spec(\"# Demo\", Path::new(\".\")).expect(\"plan\");\nlet _sandbox = SandboxSpec::new(SandboxMode::ReadOnly, \".\");\nlet _code = INTERNAL_ERROR;\n```\n\nThe facade groups the stable parts of `harness-core`, `harness-protocol`,\n`harness-sandbox`, and `harness-exec` under one crate without forcing callers to\ntrack internal crate layout changes.\n\n### Database Setup\n\nHarness requires Postgres 14+ (SQLite was removed in v0.x). Configure\n`server.database_url` in your TOML config before starting the server —\nmigrations run automatically on first connect.\n\n**Option A — Docker Compose (recommended for local dev):**\n\n```bash\n# Start Postgres container (idempotent — safe to re-run)\nbash scripts/dev-db.sh\n\n# Then set `server.database_url = \"postgres://harness:harness@localhost:5432/harness\"`\n# in your config file (for example `config/default.toml`).\n```\n\n**Option B — docker compose directly:**\n\n```bash\ndocker compose up -d postgres\n# Then set `server.database_url = \"postgres://harness:harness@localhost:5432/harness\"`\n# in your config file.\n```\n\n**Option C — existing Postgres instance:**\n\nSet `server.database_url` to any existing Postgres 14+ instance:\n\n```toml\n[server]\ndatabase_url = \"postgres://user:password@host:5432/dbname\"\n```\n\n**Running tests against a real database:**\n\n```bash\nHARNESS_DATABASE_URL=postgres://harness:harness@localhost:5432/harness cargo test --workspace\n```\n\nIntegration tests that require a database (e.g. `runtime_state_store`,\n`thread_db`, `q_value_store`) skip automatically when no Harness database URL\nis configured.\n\n### Run\n\n**HTTP server:**\n\n```bash\ncargo run -p harness-cli -- serve --transport http --port 9800\ncurl http://127.0.0.1:9800/health\n```\n\n`harness serve` persists its runtime log under `server.data_dir/logs/` as\n`harness-serve-\u003cstartup-timestamp\u003e-pid\u003cPID\u003e.log`. `/health` exposes a redacted\n`runtime_logs.path_hint`, while `/api/operator-snapshot` includes the full\nactive path for operators.\n\n**Stdio (for MCP integration):**\n\n```bash\ncargo run -p harness-cli -- serve --transport stdio\n```\n\n**One-shot execution:**\n\n```bash\ncargo run -p harness-cli -- exec \"Fix the failing test in src/lib.rs\"\n```\n\n### Common Workflows\n\n```bash\n# Task management\ncurl -X POST http://127.0.0.1:9800/tasks \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\": \"Add input validation to the API handler\"}'\n\n# Rule engine\ncargo run -p harness-cli -- rule load .\ncargo run -p harness-cli -- rule check .\n\n# GC cycle — detect signals and generate remediation drafts\ncargo run -p harness-cli -- gc run .\n\n# Skill discovery\ncargo run -p harness-cli -- skill list\n\n# ExecPlan lifecycle\ncargo run -p harness-cli -- plan init ./spec.md\ncargo run -p harness-cli -- plan status ./exec-plan-\u003cid\u003e.md\n```\n\n## Configuration\n\nAll settings are declarative TOML. Pass `--config \u003cpath\u003e` or use the defaults in [`config/default.toml`](config/default.toml).\n\n```toml\n[server]\ntransport = \"stdio\"\nhttp_addr = \"127.0.0.1:9800\"\ndata_dir = \"~/.local/share/harness\"\nproject_root = \".\"\n\n[agents]\ndefault_agent = \"auto\"\n# complexity_preferred_agents = [\"codex\", \"claude\"]\nsandbox_mode = \"danger-full-access\"\n\n[agents.claude]\ncli_path = \"claude\"\ndefault_model = \"sonnet\"\n\n[agents.codex]\ncli_path = \"codex\"\n\n[agents.anthropic_api]\nbase_url = \"https://api.anthropic.com\"\ndefault_model = \"claude-sonnet-4-20250514\"\nmax_tokens = 4096\n\n[agents.review]\nenabled = true\nreviewer_agent = \"codex\"   # local review agent\nmax_rounds = 3\nreview_bot_auto_trigger = false\n\n[gc]\nmax_drafts_per_run = 5\nbudget_per_signal_usd = 0.50\ntotal_budget_usd = 5.0\ndraft_ttl_hours = 72\n\n[observe]\nlog_retention_days = 90\n\n[otel]\nenvironment = \"production\"\nexporter = \"otlp-http\"\n# endpoint = \"http://127.0.0.1:4318\"\n```\n\n### Multi-Project Configuration\n\nRegister multiple projects in the config file. Each project gets its own worktree isolation, concurrency limits, and agent overrides.\n\n```toml\n[[projects]]\nname = \"harness\"\nroot = \"/path/to/harness\"\ndefault = true              # default project for API calls without project field\nmax_concurrent = 2          # max parallel tasks for this project\n\n[[projects]]\nname = \"litellm-rs\"\nroot = \"/path/to/litellm-rs\"\nmax_concurrent = 2\n# default_agent = \"auto\"    # optional override; or set a registered agent name\n\n[[projects]]\nname = \"vibeguard\"\nroot = \"/path/to/vibeguard\"\nmax_concurrent = 1\n```\n\nCLI `--project name=path` flags merge with config entries (CLI overrides on conflict).\n\n### Per-Project Overrides\n\nEach project can have a `.harness/config.toml` in its root to override server defaults:\n\n```toml\n# /path/to/project/.harness/config.toml\n[git]\nbase_branch = \"develop\"\nremote = \"upstream\"\nbranch_prefix = \"fix/\"\n\n[validation]\npre_commit = [\"cargo fmt --all -- --check\", \"cargo check\"]\ntimeout_secs = 120\n\n[agent]\ndefault = \"auto\"            # or set a registered agent name\n\n[review]\nenabled = true\n\n[concurrency]\nmax_concurrent_tasks = 3\n```\n\n## HTTP REST API\n\n### Task Management\n\n```bash\n# Submit a task by prompt\ncurl -X POST http://127.0.0.1:9800/tasks \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"Add input validation to the API handler\",\n    \"project\": \"/path/to/project\"\n  }'\n\n# Submit a task by GitHub issue number\ncurl -X POST http://127.0.0.1:9800/tasks \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"project\": \"/path/to/project\",\n    \"issue\": 42,\n    \"prompt\": \"fix: handle edge case in parser\"\n  }'\n\n# Submit an issue task but bypass triage/plan and go straight to implementation\ncurl -X POST http://127.0.0.1:9800/tasks \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"project\": \"/path/to/project\",\n    \"issue\": 42,\n    \"skip_triage\": true\n  }'\n\n# Submit a task by PR number (for review/fix)\ncurl -X POST http://127.0.0.1:9800/tasks \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"project\": \"/path/to/project\",\n    \"pr\": 100\n  }'\n\n# Batch submit multiple tasks\ncurl -X POST http://127.0.0.1:9800/tasks/batch \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"project\": \"/path/to/project\",\n    \"issues\": [10, 11, 12]\n  }'\n\n# Get task status\ncurl http://127.0.0.1:9800/tasks/{task_id}\n\n# List all tasks\ncurl http://127.0.0.1:9800/tasks\n\n# Stream task output (SSE)\ncurl http://127.0.0.1:9800/tasks/{task_id}/stream\n```\n\n### Project Management\n\n```bash\n# List registered projects\ncurl http://127.0.0.1:9800/projects\n\n# Register a new project at runtime\ncurl -X POST http://127.0.0.1:9800/projects \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"id\": \"my-project\",\n    \"root\": \"/path/to/project\",\n    \"max_concurrent\": 2\n  }'\n\n# Remove a project\ncurl -X DELETE http://127.0.0.1:9800/projects/my-project\n```\n\n### Dashboard\n\n```bash\n# Get aggregated status across all projects\ncurl http://127.0.0.1:9800/api/dashboard\n\n# Response:\n# {\n#   \"global\": { \"running\": 3, \"queued\": 1, \"done\": 42, \"failed\": 2, \"grade\": \"A\" },\n#   \"projects\": [\n#     { \"id\": \"harness\", \"root\": \"...\", \"tasks\": { \"running\": 1, \"queued\": 0 } },\n#     { \"id\": \"litellm-rs\", \"root\": \"...\", \"tasks\": { \"running\": 2, \"queued\": 1 } }\n#   ]\n# }\n```\n\n### Health\n\n```bash\ncurl http://127.0.0.1:9800/health\n```\n\nThe response includes a `runtime_logs` block with the logging state, retention\nwindow, and a redacted `logs/\u003cfilename\u003e` hint instead of the full absolute\npath.\n\n## Server Startup\n\n**Important:** Always start the server from a standalone terminal, not from within Claude Code or other agent sessions. Agent environment variables (`CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`) propagate to spawned subprocesses and cause SIGTRAP.\n\n```bash\n# Single project (backward compatible)\n./target/release/harness serve --transport http --port 9800 --project-root /path/to/project\n\n# Multi-project via config file (recommended)\n./target/release/harness serve --transport http --port 9800 --config config/default.toml\n\n# Multi-project via CLI flags\n./target/release/harness serve --transport http --port 9800 \\\n  --project harness=/path/to/harness \\\n  --project litellm=/path/to/litellm\n\n# With GitHub token for auto-review\nGITHUB_TOKEN=ghp_xxx ./target/release/harness serve --transport http --port 9800 --config config/default.toml\n```\n\n## Task Execution Flow\n\n```\nPOST /tasks → TaskQueue → acquire semaphore (project + global)\n    → create git worktree → agent executes in isolation\n    → post-validator runs (cargo fmt, cargo check)\n    → agent creates PR → Codex review (up to 3 rounds)\n    → quality score → cleanup worktree → done\n```\n\nEach task runs in an isolated git worktree, so multiple agents can work on the same repo in parallel without conflicts.\n\n## Workspace Crates\n\n| Crate | Purpose |\n|---|---|\n| `harness-core` | Shared domain types, config, prompts, agent/interceptor traits |\n| `harness-protocol` | JSON-RPC method definitions, envelopes, notifications, codecs |\n| `harness-server` | App Server runtime (HTTP + stdio + WebSocket), routing, handlers, task/thread stores |\n| `harness-agents` | Agent adapters (Claude CLI, Codex CLI, Anthropic API) and registry |\n| `harness-gc` | Signal detection and draft remediation generation/adoption |\n| `harness-rules` | Rule loading/parsing, Starlark execution policy engine |\n| `harness-skills` | Skill discovery, deduplication, search, and persistence |\n| `harness-exec` | ExecPlan model plus Markdown serialization/deserialization |\n| `harness-observe` | Event storage, quality grading, health/stat aggregation, OTLP export |\n| `harness-cli` | `harness` binary with serve/exec/gc/rule/skill/plan commands |\n\n## JSON-RPC API\n\nHarness exposes 42 methods over JSON-RPC 2.0 (stdio, HTTP, or WebSocket):\n\n| Category | Methods |\n|---|---|\n| Lifecycle | `initialize`, `initialized` |\n| Threads | `thread/start`, `thread/resume`, `thread/fork`, `thread/list`, `thread/delete`, `thread/compact` |\n| Turns | `turn/start`, `turn/steer`, `turn/cancel`, `turn/status`, `turn/respond_approval` |\n| GC | `gc/run`, `gc/status`, `gc/drafts`, `gc/adopt`, `gc/reject` |\n| Skills | `skill/create`, `skill/list`, `skill/get`, `skill/delete`, `skill/governance/view`, `skill/governance/history`, `skill/stale` |\n| Rules | `rule/load`, `rule/check` |\n| ExecPlan | `exec_plan/init`, `exec_plan/update`, `exec_plan/status` |\n| Observability | `event/log`, `event/query`, `metrics/collect`, `metrics/query` |\n| Classification | `task/classify`, `learn/rules`, `learn/skills` |\n| Health | `health/check`, `stats/query`, `agent/list` |\n| VibeGuard | `preflight`, `cross_review` |\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup and PR guidelines.\n\n## Security\n\nSee [`SECURITY.md`](SECURITY.md) for vulnerability reporting.\n\n## License\n\nLicensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajiayu000%2Fharness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmajiayu000%2Fharness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajiayu000%2Fharness/lists"}