From 7fa62c98c3515c9afef59a6818310ef82879cb0b Mon Sep 17 00:00:00 2001 From: Jay Yu Date: Sat, 24 Oct 2026 19:24:05 -0400 Subject: [PATCH 1/2] docs(coding-agent): refresh README and contributor guidance --- CONTRIBUTING.md | 2 +- README.md | 126 ++++++++++++++++++------------------------------ 2 files changed, 47 insertions(+), 81 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d846f80e..c464a5c3d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ Using AI-assisted tools is acceptable, but contributors remain responsible for c 2. Reproduce bugs through the user-facing workflow before narrowing the problem to focused tests. 3. Add or update tests for changed public behavior and bug fixes. 4. Run the required validation and resolve every error, warning, and informational diagnostic. -5. Open a pull request that explains the summary, reasoning, changes, user impact, and testing performed. +5. Open a pull request using the provided [GitHub pull request template](.github/pull_request_template.md). Complete every section with the summary, reasoning, changes, and testing performed, including relevant user impact. 6. Address review feedback with focused follow-up commits. 7. Merge only after approval and all required checks pass. diff --git a/README.md b/README.md index bbb288e4a..49d7c5d71 100644 --- a/README.md +++ b/README.md @@ -14,68 +14,60 @@

Website - Node.js 22.19 or newer + Latest npm version + Node.js 22.19 or newer License: Apache 2.0 CI

# Diffex -Diffex is a self-evolving coding agent. -It provides a multi-provider LLM API, a general-purpose agent runtime, a terminal UI, remote session protocols, and an extensible coding-agent CLI. +Diffex is a lightweight, self-evolving coding agent that lives in your CLI. Ask it to explore a codebase, implement features, fix bugs, and run tests—all from your terminal. -Diffex treats the agent harness as an optimization target. -Diffex evolves through observable behavior, diagnostic signals, and evidence-backed improvements. +- **Work with your code:** read and edit files, run shell commands, and iterate on changes in an interactive session. +- **Choose your models:** connect subscription accounts or API keys, or use local models. +- **Make it yours:** add skills, extensions, and reusable prompts, or integrate Diffex into your own tools. -The archived Rust implementation is available at [diffexai/diffex-legacy](https://github.com/diffexai/diffex-legacy). +## Quick start -Read more at [diffex.ai](https://diffex.ai/) and in the [Diffex white paper](https://diffex.ai/white-paper). - -Diffex builds on the [Pi Agent Harness](https://github.com/earendil-works/pi) to extend its capabilities. -Use `./diffex-test.sh` to run Diffex directly from this repository. - -## Installation - -Diffex is released on npm as [`@diffexai/diffex`](https://www.npmjs.com/package/@diffexai/diffex?activeTab=readme). -Install it globally and launch the CLI: +Requires Node.js 22.19 or newer and npm. ```bash -npm install -g @diffexai/diffex +npm install -g --ignore-scripts @diffexai/diffex +cd your-project diffex ``` -## Workspace Packages - -| Package | Responsibility | -|---------|----------------| -| [`packages/telemetry`](packages/telemetry) | Vendor-neutral telemetry contracts and typed schemas. | -| [`packages/ai`](packages/ai) | Unified LLM API with provider and model discovery. | -| [`packages/agent`](packages/agent) | Agent runtime, tool calling, state management, and attachments. | -| [`packages/harness-state`](packages/harness-state) | Immutable, content-addressed harness revisions and global selection. | -| [`packages/protocol`](packages/protocol) | Transport-neutral CBOR protocol for remote sessions. | -| [`packages/client`](packages/client) | Transport-neutral client for remote sessions. | -| [`packages/server`](packages/server) | Experimental remote session server. | -| [`packages/session-backends/sqlite-node`](packages/session-backends/sqlite-node) | SQLite session persistence for Node.js. | -| [`packages/tui`](packages/tui) | Terminal UI components with differential rendering. | -| [`packages/coding-agent`](packages/coding-agent) | Interactive coding-agent CLI and extension system. | -| [`packages/evals`](packages/evals) | Evaluation utilities and scenarios. | - -## Distribution policy - -The source repository remains private pending an explicit publication review. -Changing visibility requires an audit of retained Actions logs, artifacts, source snapshots, debug maps, and linked session transcripts. -Artifact names such as `private-release-*` do not provide access protection. -The approved release channel is the public npm package `@diffexai/diffex`, which bundles the required runtime workspaces. -Standalone archives, Python, secondary package registries, and interactive CLI containers are deferred. -Public packages include readable JavaScript and declarations, with Apache-2.0 metadata and complete applicable upstream notices. -They exclude source maps, TypeScript examples, and native source build files. -Delivered implementation code remains inspectable; private source hosting and compilation do not guarantee confidentiality. -See the [distribution review](docs/release/distribution-review.md) for exact scope and release prerequisites. -See the [source publication review](docs/release/source-publication.md) for the separate repository visibility transition. - -## Local Setup - -Diffex requires Node.js 22.19 or newer and npm. +Use `/login` to connect a supported subscription provider, or set a provider API key such as `ANTHROPIC_API_KEY` before launching. Then describe what you want to build or change. + +Diffex runs with your user account's permissions. Use a container or sandbox when working with untrusted code. + +## Benchmarks + +Diffex scores are reported mean rewards; Codex's score is published leaderboard accuracy. Trial counts show scored / total attempts. All Diffex runs used `max` reasoning without subagents. + +| Benchmark | Agent | Model | Score | Trials | +|-----------|-------|-------|------:|-------:| +| [Deep SWE 1.1](https://hub.harborframework.com/jobs/c7689ad5-0558-41cc-9b8d-576d71d2b3b0) | Diffex 0.3.2 | GPT-6 Luna | 67.27% | 110 / 113 | +| [Terminal-Bench 2.1](https://hub.harborframework.com/jobs/10462e7b-ec7d-49fa-9103-2060d4f62931) | Diffex 0.3.2 | GPT-6 Luna | 80.19% | 424 / 445 | +| [Terminal-Bench 2.1](https://hub.harborframework.com/jobs/169f8574-9c7f-411c-9fe5-489ea4471016) | Diffex 0.3.1 | GPT-5.6 Luna | 79.85% | 412 / 445 | +| [Terminal-Bench 2.1](https://github.com/harbor-framework/terminal-bench-2-1/pull/112) | Codex | GPT-5.6 Luna | 75.73% | 445 / 445 | + +Deep SWE also reported **95.13% fail-to-pass** and **98.85% pass-to-pass** test scores. + +On Terminal-Bench 2.1, Diffex's reported GPT-5.6 Luna score is **4.12 percentage points above Codex**, also using `max` reasoning. This is not a controlled comparison: execution environments may differ. + +## Documentation + +- [Quickstart](packages/coding-agent/docs/quickstart.md) +- [Usage and commands](packages/coding-agent/docs/usage.md) +- [Providers and authentication](packages/coding-agent/docs/providers.md) +- [Local models](packages/coding-agent/docs/llama-cpp.md) +- [Skills](packages/coding-agent/docs/skills.md) and [extensions](packages/coding-agent/docs/extensions.md) +- [SDK](packages/coding-agent/docs/sdk.md) and [RPC integration](packages/coding-agent/docs/rpc.md) +- [Containerization and sandboxing](packages/coding-agent/docs/containerization.md) + +## Development ```bash git clone https://github.com/diffexai/diffex.git @@ -85,47 +77,21 @@ npm run build:offline ./diffex-test.sh ``` -The source launcher can be run from any directory and preserves the caller's working directory. - -## Local Validation +Validate changes with: ```bash npm run check ./test.sh ``` -`npm run check` runs formatting, linting, dependency policy checks, and TypeScript validation. -`./test.sh` runs the non-E2E test suites without activating tests that require provider credentials. - -## Documentation - -- [Coding-agent documentation](packages/coding-agent/docs/index.md) -- [Containerization and sandboxing](packages/coding-agent/docs/containerization.md) -- [Contributing](CONTRIBUTING.md) -- [Code of Conduct](CODE_OF_CONDUCT.md) -- [Project rules](AGENTS.md) - -## Permissions and Containerization - -Diffex does not impose a built-in security boundary around filesystem, process, network, or credential access. -By default, it runs with the permissions of the user and process that launched it. - -Use a container or sandbox when stronger isolation is required. -See the [containerization guide](packages/coding-agent/docs/containerization.md) for supported patterns. - -## Contributing +The checks cover formatting, linting, dependency policy, and TypeScript. The test command runs non-E2E suites without activating tests that require provider credentials. -Issues and pull requests are welcome. -Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, validation, and review expectations. -Participation in the project is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). +If you find Diffex useful, please [give it a star on GitHub](https://github.com/diffexai/diffex). Help us improve Diffex by [suggesting features or reporting issues](https://github.com/diffexai/diffex/issues/new/choose), or [contributing directly](CONTRIBUTING.md). -## Security +## Acknowledgments -Do not commit credentials, secrets, local machine artifacts, build output, or private deployment state. -Report sensitive issues privately through the repository maintainers or the contact paths on [diffex.ai](https://diffex.ai/). -See [SECURITY.md](SECURITY.md) for reporting guidance and the execution trust boundary. +Thank you to the developers of [Pi](https://github.com/earendil-works/pi) for building the foundation that Diffex builds on. ## License -Diffex contributions are distributed under the [Apache License 2.0](LICENSE). -Portions derived from Pi remain available under the MIT License, with the upstream copyright and permission notice preserved in the license file. +Apache License 2.0 From dd49f47328d10700ff29f3faf5a623006e8fad81 Mon Sep 17 00:00:00 2001 From: Jay Yu Date: Sat, 24 Oct 2026 19:26:58 -0400 Subject: [PATCH 2/2] fix(coding-agent): stop enforcing README identity wording --- scripts/check-runtime-identities.mjs | 1 - scripts/check-runtime-identities.test.mjs | 7 +++++++ scripts/runtime-identity-allowlist.json | 9 --------- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/scripts/check-runtime-identities.mjs b/scripts/check-runtime-identities.mjs index d8228cedb..cddac0c86 100644 --- a/scripts/check-runtime-identities.mjs +++ b/scripts/check-runtime-identities.mjs @@ -43,7 +43,6 @@ export function checkIdentities(root) { "package-lock.json", "tsconfig.json", "SECURITY.md", - "README.md", "LICENSE", ].includes(path)) && !path.includes("/test/") && diff --git a/scripts/check-runtime-identities.test.mjs b/scripts/check-runtime-identities.test.mjs index 67fe72ee7..a66f05a7c 100644 --- a/scripts/check-runtime-identities.test.mjs +++ b/scripts/check-runtime-identities.test.mjs @@ -31,6 +31,13 @@ test("checks path and exact content, and rejects added or stale exceptions", () execFileSync("git", ["init", "-q"], { cwd: root }); execFileSync("git", ["add", path], { cwd: root }); assert.equal(checkIdentities(root).occurrences, 1); + writeFileSync( + join(root, "README.md"), + "Thank you to [Pi](https://github.com/earendil-works/pi).", + ); + assert.equal(checkIdentities(root).occurrences, 1); + writeFileSync(join(root, "README.md"), "# Diffex"); + assert.equal(checkIdentities(root).occurrences, 1); writeFileSync( join(root, path), context + '\nfetch("https://pi.dev/api/report-install");', diff --git a/scripts/runtime-identity-allowlist.json b/scripts/runtime-identity-allowlist.json index ce22be665..1034d0e08 100644 --- a/scripts/runtime-identity-allowlist.json +++ b/scripts/runtime-identity-allowlist.json @@ -1,13 +1,4 @@ [ - { - "path": "README.md", - "context": "Diffex builds on the [Pi Agent Harness](https://github.com/earendil-works/pi) to extend its capabilities.", - "identities": [ - "earendil-works" - ], - "category": "legal notice", - "reason": "Preserves upstream source attribution alongside the unchanged MIT notice in LICENSE." - }, { "path": "packages/ai/src/api/openai-codex-responses.ts", "context": "\theaders.set(\"originator\", \"pi\");",