@zhijiewang/openharness 2.16.0 → 2.18.0

package/README.md

@@ -23,6 +23,8 @@ AI coding agent in your terminal. Works with any LLM -- free local models or clo
 
 [![npm version](https://img.shields.io/npm/v/@zhijiewang/openharness)](https://www.npmjs.com/package/@zhijiewang/openharness) [![npm downloads](https://img.shields.io/npm/dm/@zhijiewang/openharness)](https://www.npmjs.com/package/@zhijiewang/openharness) [![license](https://img.shields.io/npm/l/@zhijiewang/openharness)](LICENSE) ![tests](https://img.shields.io/badge/tests-890-brightgreen) ![tools](https://img.shields.io/badge/tools-42-blue) ![Node.js 18+](https://img.shields.io/badge/node-18%2B-green) ![TypeScript](https://img.shields.io/badge/typescript-strict-blue) [![GitHub stars](https://img.shields.io/github/stars/zhijiewong/openharness)](https://github.com/zhijiewong/openharness) [![GitHub issues](https://img.shields.io/github/issues-raw/zhijiewong/openharness)](https://github.com/zhijiewong/openharness/issues) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/zhijiewong/openharness/pulls)
 
+**English** | [简体中文](README.zh-CN.md)
+
 ---
 
 ## Table of Contents
@@ -30,7 +32,7 @@ AI coding agent in your terminal. Works with any LLM -- free local models or clo
 - [Quick Start](#quick-start)
 - [Why OpenHarness?](#why-openharness)
 - [Terminal UI](#terminal-ui)
-- [Tools (35)](#tools-35)
+- [Tools (37)](#tools-37)
 - [Slash Commands (33)](#slash-commands-33)
 - [Permission Modes](#permission-modes)
 - [Hooks](#hooks)
@@ -57,7 +59,7 @@ oh
 
 That's it. OpenHarness auto-detects Ollama and starts chatting. No API key needed.
 
-**Python SDK:** there's also an official Python SDK for driving `oh` from Python programs (notebooks, batch scripts, ML pipelines). Install with `pip install openharness` after the npm install, then `from openharness import query`. See [`python/README.md`](python/README.md).
+**Python SDK:** there's also an official Python SDK for driving `oh` from Python programs (notebooks, batch scripts, ML pipelines). Install with `pip install openharness-sdk` after the npm install (the PyPI distribution is `openharness-sdk` because the unqualified name is taken), then `from openharness import query`. See [`python/README.md`](python/README.md).
 
 ```bash
 oh init                               # interactive setup wizard (provider + cybergotchi)
@@ -82,26 +84,6 @@ Ctrl+O                                # flush transcript to scrollback for revie
 
 Most AI coding agents are locked to one provider or cost $20+/month. OpenHarness works with any LLM -- run it free with Ollama on your own machine, or connect to any cloud API. Every AI edit is git-committed and reversible with `/undo`.
 
-|  | OpenHarness | Claude Code | Aider | OpenCode |
-|---|---|---|---|---|
-| Any LLM | Yes (Ollama, OpenAI, Anthropic, OpenRouter, any OpenAI-compatible) | Anthropic only | Yes | Yes |
-| Free local models | Ollama native | No | Yes | Yes |
-| Tools | 41 with permission gates | 43+ | File-focused | 20+ |
-| Permission modes | 7 (ask, trust, deny, acceptEdits, plan, auto, bypass) | 7 | Basic | Basic |
-| Git integration | Auto-commit + /undo + /rewind checkpoints | Yes | Deep git | Basic |
-| Slash commands | 42+ built-in | 80+ | Some | Some |
-| Headless/CI mode | `oh -p "prompt"` or `oh run --json` | Yes | Yes | Yes |
-| GitHub Action | Built-in PR review action | Yes | No | No |
-| Agent roles | 6 specializations (reviewer, tester, debugger...) | Yes | No | No |
-| Vim mode | hjkl, w/b/e, 0/$, x, d, i/a/I/A/o | Full vim | No | No |
-| Prompt caching | Anthropic cache_control | Yes | No | No |
-| Bash security | AST-based command analysis | AST analysis | No | No |
-| Companion | Cybergotchi virtual pet | Basic | No | No |
-| Terminal UI | Sequential renderer (Ink pattern) | React + Ink | Basic | BubbleTea |
-| Language | TypeScript | TypeScript | Python | Go |
-| License | MIT | Proprietary | Apache 2.0 | MIT |
-| Price | Free (BYOK) | $20+/month | Free (BYOK) | Free (BYOK) |
-
 ## Terminal UI
 
 OpenHarness features a sequential terminal renderer inspired by Ink/Claude Code's default mode. Completed messages flush to native scrollback (scrollable), while the live area (streaming, spinner, input) rewrites in-place using relative cursor movement.
@@ -160,7 +142,7 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 
 Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XXXX), `{ctx}` (context usage bar). Empty sections are automatically collapsed.
 
-## Tools (35)
+## Tools (37)
 
 | Tool | Risk | Description |
 |------|------|-------------|
@@ -204,6 +186,9 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | Memory | low | Save/list/search persistent memories |
 | Skill | low | Invoke a skill from .oh/skills/ |
 | ToolSearch | low | Find tools by description |
+| **MCP** | | |
+| ListMcpResources | low | List resources from connected MCP servers |
+| ReadMcpResource | low | Read a specific MCP resource by URI |
 | **Git Worktrees** | | |
 | EnterWorktree | medium | Create isolated git worktree |
 | ExitWorktree | medium | Remove a git worktree |
@@ -245,6 +230,8 @@ Type these during a chat session. Aliases: `/q` exit, `/h` help, `/c` commit, `/
 | `/files` | List files in context |
 | `/model <name>` | Switch model mid-session |
 | `/memory` | View and search memories |
+| `/doctor` | Run diagnostic health checks |
+| `/hooks` | List loaded hooks grouped by event |
 
 **Settings:**
 | Command | Description |
@@ -517,6 +504,24 @@ cat error.log | oh run "what's wrong here?"
 git diff | oh run "review these changes"
 ```
 
+### Structured output with `--json-schema`
+
+Constrain the model's output to a JSON Schema. Useful for CI scripts that
+parse model output programmatically without regex heuristics:
+
+```bash
+oh -p "output {\"ok\": true, \"count\": 3} as JSON" \
+  --trust \
+  --json-schema '{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"integer"}},"required":["ok","count"]}'
+```
+
+Behavior:
+- stdout: the validated JSON (single line), only when it passes the schema.
+- stderr: structured errors on failure, plus the raw model output for debugging.
+- Exit codes: **0** valid, **2** malformed schema, **3** model output was not JSON, **4** JSON didn't match the schema.
+
+Supported keywords: `type`, `properties`, `required`, `items`, `enum`. For richer validation, pipe the output through a dedicated validator.
+
 ### GitHub Action for PR Review
 
 OpenHarness includes a built-in GitHub Action for automated code review:
@@ -608,6 +613,8 @@ provider: ollama
 model: llama3
 permissionMode: ask
 theme: dark
+language: zh-CN        # optional — respond in this language (code stays as-is)
+outputStyle: default   # optional — "default", "explanatory", "learning", or a custom name
 ```
 
 Then per-project configs only need what's different:
@@ -617,6 +624,27 @@ Then per-project configs only need what's different:
 model: codellama   # override just the model
 ```
 
+### Output Styles
+
+Swap the agent's personality without touching its core instructions. Built-ins:
+
+- **`default`** — standard software engineering assistant (no preface)
+- **`explanatory`** — adds an `## Insights` section after each task explaining *why* the agent made its choices
+- **`learning`** — leaves 1–3 `TODO(human)` markers at strategic points so you write the instructive parts yourself
+
+Create your own styles as markdown files with YAML frontmatter. Save to `.oh/output-styles/<name>.md` (project) or `~/.oh/output-styles/<name>.md` (user). Project shadows user shadows built-in.
+
+````markdown
+---
+name: code-review
+description: Focused code review mode
+---
+
+Review rigorously. For every function, ask: is the logic correct, is error handling complete, are there edge cases ignored?
+````
+
+Activate with `outputStyle: code-review` in `.oh/config.yaml`.
+
 ## Project Rules
 
 Create `.oh/RULES.md` in any repo (or run `oh init`):
@@ -706,7 +734,7 @@ Yes. Use `oh -p "prompt" --auto` for headless execution, or the built-in GitHub
 Yes. OpenHarness is language-agnostic — it reads, writes, and executes code in any language. Syntax highlighting covers 20+ languages.
 
 **How does it compare to Claude Code?**
-~95% feature parity for CLI use cases. Main advantage: works with ANY LLM (not just Anthropic). See the [comparison table](#why-openharness) above.
+~95% feature parity for CLI use cases. Main advantage: works with ANY LLM (not just Anthropic) and is MIT-licensed. See [Why OpenHarness?](#why-openharness) above.
 
 ## Install