codex-harness 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +54 -88
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,113 +1,79 @@
1
- # Codex Harness
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/ErzenXz/codex-harness/main/docs/assets/banner.svg" alt="Codex Harness — native Rust, small footprint." width="100%">
3
+ </p>
2
4
 
3
- A small, quiet native Rust backend for coding agents. Your ACP-compatible app
4
- provides the UI; the harness handles streaming, file/search tools, isolated
5
- subagents, background jobs, MCP servers and optional computer use.
5
+ <p align="center">
6
+ A small native Rust backend for coding agents.<br>
7
+ macOS · Linux · Windows &nbsp;/&nbsp; arm64 · x64
8
+ </p>
6
9
 
7
- ## Install
10
+ <p align="center">
11
+ <a href="https://www.npmjs.com/package/codex-harness">npm</a> ·
12
+ <a href="https://github.com/ErzenXz/codex-harness/releases">Downloads</a> ·
13
+ <a href="https://github.com/ErzenXz/codex-harness/blob/main/docs/reference.md">Documentation</a>
14
+ </p>
8
15
 
9
- ```sh
10
- pnpm add -g codex-harness
11
- ```
12
-
13
- Or use `npm install -g codex-harness`. Requires Node.js 22.15+ for the installer
14
- launcher. No Rust, Python, compilation, postinstall script or runtime download.
15
- Only the native package for your OS/CPU is installed. Supports macOS, Linux and
16
- Windows on arm64 and x64. Linux binaries use static musl and work on glibc and
17
- musl distributions. Windows runs natively; WSL is optional.
18
-
19
- Prefer no Node.js at all? Download the matching archive from
20
- [Releases](https://github.com/ErzenXz/codex-harness/releases), verify it against
21
- `SHA256SUMS`, and put the executable on PATH. `ripgrep` is recommended for faster
22
- search; a bounded Rust fallback is built in.
23
-
24
- ## Sign in
16
+ ## Quick start
25
17
 
26
18
  ```sh
19
+ pnpm add -g codex-harness
27
20
  codex-harness login
28
21
  ```
29
22
 
30
- Open the printed link, enter the code and approve access. Enable device-code
31
- login in ChatGPT security settings if requested. Your plan must allow the model;
32
- subscription limits still apply. No API key is needed for subscription sign-in.
33
-
34
- Defaults use `gpt-6-luna`. To choose reasoning, concurrency or another provider,
35
- copy a [starter configuration](examples/) to a trusted user directory and pass
36
- `--config /absolute/path/config.toml` to **both login and the ACP launcher**.
37
- [API key and provider setup](docs/reference.md#authentication-and-providers).
38
- No configuration is read from the project being edited.
39
-
40
- ## Connect your ACP app
23
+ Requires pnpm and Node.js 22.15+. Installs only your platform's native binary, with no
24
+ compilation or install scripts. [Standalone downloads](https://github.com/ErzenXz/codex-harness/releases)
25
+ run without Node.js. Linux uses static musl; Windows runs natively.
41
26
 
42
- Set its agent command to `codex-harness`, with arguments `["--acp"]`. For the
43
- lowest overhead, get the absolute native executable path once:
44
-
45
- ```sh
46
- codex-harness --print-binary-path
47
- ```
48
-
49
- Use that path directly in your app's launcher:
27
+ Set your ACP app's agent command:
50
28
 
51
29
  ```json
52
- {
53
- "command": "/absolute/path/printed/above/codex-harness",
54
- "args": ["--acp"],
55
- "env": {}
56
- }
30
+ { "command": "codex-harness", "args": ["--acp"] }
57
31
  ```
58
32
 
59
- On Windows the path ends in `.exe`. If using a custom config, append
60
- `"--config", "/absolute/path/config.toml"` to `args`. Your ACP app sends prompts
61
- and approvals over stdin/stdout. No files need to be installed in your projects.
33
+ Your app provides the interface; the harness communicates over stdin/stdout.
34
+ Subscription login uses your plan's model access and limits.
35
+ [Other providers and API keys →](https://github.com/ErzenXz/codex-harness/blob/main/docs/reference.md#authentication-and-providers)
62
36
 
63
- A blank terminal is normal if you run the harness yourself: it waits for ACP
64
- messages. There is no terminal chat, web server or status banner. Closed stdin
65
- shuts it down. On macOS/Linux the npm launcher replaces itself with Rust using
66
- Node's `execve` where available; Windows uses a child process. Direct native
67
- launch avoids Node startup on every platform.
37
+ Available models and reasoning levels load automatically. Choose them in your
38
+ ACP app; selections persist per session. [Discovery and picker details →](https://github.com/ErzenXz/codex-harness/blob/main/docs/reference.md#model-discovery-and-reasoning)
68
39
 
69
- ## Small by design
40
+ ## Performance
70
41
 
71
- - One current-thread async runtime, pooled HTTP and lazy shared MCP connections.
72
- - In-place streamed tool arguments and SSE fragments; no repeated whole-buffer
73
- copies. JSON budget checks count bytes without allocating another JSON buffer.
74
- - Whole-turn history eviction, bounded files/streams/tool output, backpressure,
75
- explicit concurrency caps and session unloading.
76
- - No telemetry, background updater, daemon or bundled browser/model/runtime.
77
- - Permission-gated edits/shell/MCP tools, plan mode, subagent roles, cancellation,
78
- persistence and observed provider usage reporting stay available.
42
+ Measured locally on **macOS arm64 · v0.2.0**.
79
43
 
80
- Performance figures and reproducible tests live in
81
- [Performance](docs/performance.md). These measure local overhead; model inference,
82
- provider limits and workload determine end-to-end agent performance.
44
+ | Metric | Result |
45
+ | :--- | ---: |
46
+ | Native binary | **4.48 MB** · 6.8% smaller |
47
+ | Version startup, median | **5.82 ms** |
48
+ | Idle memory, sampled RSS | **4.02 MiB** |
49
+ | Streamed tool arguments, median | **2.02 ms** · ~29× faster |
83
50
 
84
- Native desktop control requires Linux X11 and is disabled by default. For macOS
85
- and Windows desktop/browser control, connect a trusted MCP server. Approved shell,
86
- MCP and desktop tools can access the host; they are **not an OS sandbox**.
87
- Credentials are stored unencrypted in private local state. See
88
- [Security and limits](docs/reference.md#safety-boundaries).
51
+ Size and streaming comparisons use the original `6f55af7` baseline. Streaming
52
+ measures accumulation of 8,000 × 32-byte argument fragments; model latency is
53
+ excluded. Memory and timings vary by workload.
54
+ [Before/after results, methodology and reproduction →](https://github.com/ErzenXz/codex-harness/blob/main/docs/performance.md)
89
55
 
90
- ## Update, remove, build
56
+ ## Built to stay light
91
57
 
92
- ```sh
93
- pnpm add -g codex-harness@latest
94
- codex-harness logout
95
- pnpm remove -g codex-harness
96
- ```
58
+ One async event-loop thread, shared HTTP connections, lazy MCP connections and
59
+ bounded history, files and tool output. No telemetry, daemon, updater or bundled
60
+ browser/model.
97
61
 
98
- Restart your ACP agent after updating. If you launch the printed native path,
99
- refresh that path after updating. Logout removes local login credentials; retained
100
- conversations remain in the state directory. On Unix state defaults to
101
- `$XDG_STATE_HOME/codex-harness` or `~/.local/state/codex-harness`; on Windows it is
102
- `%LOCALAPPDATA%\codex-harness`. `CODEX_HARNESS_STATE_DIR` overrides it.
62
+ Streaming, file/search tools, MCP, subagents, background jobs, persistent sessions,
63
+ cancellation and permission controls are built in.
103
64
 
104
- Source install (Rust 1.88+ and your OS build tools required):
65
+ For the lowest launch overhead, run `codex-harness --print-binary-path` and use
66
+ that executable directly in your ACP app. On macOS/Linux the standard launcher
67
+ replaces Node with Rust where `execve` is available; Windows keeps a forwarding
68
+ process until you use the native path.
105
69
 
106
- ```sh
107
- cargo install --git https://github.com/ErzenXz/codex-harness --tag v0.2.0 --locked
108
- ```
70
+ Approved tools can access your host. Native desktop control is optional and
71
+ requires Linux X11; macOS/Windows computer use works through MCP. See
72
+ [security and limits](https://github.com/ErzenXz/codex-harness/blob/main/docs/reference.md#safety-boundaries).
109
73
 
110
- Missing platform package? Reinstall with optional dependencies enabled; do not
111
- use `--no-optional` or `--omit=optional`. There is no fallback network download.
74
+ ---
112
75
 
113
- [Technical reference](docs/reference.md) · [Development and tests](docs/reference.md#development) · [Release process](docs/releasing.md)
76
+ [Configuration](https://github.com/ErzenXz/codex-harness/tree/main/examples) ·
77
+ [Install, update & remove](https://github.com/ErzenXz/codex-harness/blob/main/docs/reference.md#installation-and-maintenance) ·
78
+ [Development](https://github.com/ErzenXz/codex-harness/blob/main/docs/reference.md#development) ·
79
+ [MIT license](https://github.com/ErzenXz/codex-harness/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-harness",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "description": "Small native Rust coding-agent backend: ACP, streaming, subagents, MCP and ChatGPT sign-in",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -34,11 +34,11 @@
34
34
  "registry": "https://registry.npmjs.org/"
35
35
  },
36
36
  "optionalDependencies": {
37
- "@erzenx/codex-harness-darwin-arm64": "0.2.0",
38
- "@erzenx/codex-harness-darwin-x64": "0.2.0",
39
- "@erzenx/codex-harness-linux-arm64": "0.2.0",
40
- "@erzenx/codex-harness-linux-x64": "0.2.0",
41
- "@erzenx/codex-harness-win32-arm64": "0.2.0",
42
- "@erzenx/codex-harness-win32-x64": "0.2.0"
37
+ "@erzenx/codex-harness-darwin-arm64": "0.3.1",
38
+ "@erzenx/codex-harness-darwin-x64": "0.3.1",
39
+ "@erzenx/codex-harness-linux-arm64": "0.3.1",
40
+ "@erzenx/codex-harness-linux-x64": "0.3.1",
41
+ "@erzenx/codex-harness-win32-arm64": "0.3.1",
42
+ "@erzenx/codex-harness-win32-x64": "0.3.1"
43
43
  }
44
44
  }