README: put each screenshot next to the text it shows · Pull request #321

23

24

If Diffinery is useful to you, a star on GitHub helps other people find it.

25

38

26

## Contents

39

27

40

28

- [Who Diffinery is for](#who-diffinery-is-for)

41

29

- [Why Diffinery](#why-diffinery)

42

31

- [Built for AI coding agents](#built-for-ai-coding-agents)

43

32

- [Plugins and integrations](#plugins-and-integrations)

44

33

- [Features](#features)

69

58

- **Secure by default.** Passkey sign-in with no passwords, invite-only accounts, branch protection, push protection that blocks leaked credentials, envelope-encrypted secrets, kill switches and an append-only audit log.

70

59

- **Moving from GitHub is one step.** A server-side importer brings a repository or a whole organization over with its history, issues, pull requests, reviews and releases, and `gh`, Octokit, VS Code and JetBrains IDEs work against Diffinery.

71

60

72

71

## Built for AI coding agents

73

72

75

74

76

75

### Agent accounts with guardrails

77

76

94

93

95

94

To use your **Claude or ChatGPT subscription** instead of an API key, open a [terminal](https://diffinery.com/docs/agents/terminal): a shell in your browser with the repository checked out, where you sign in to Claude Code or Codex with your own plan and can hand it tasks.

96

95

97

98

See [Agent tasks](https://diffinery.com/docs/agents/tasks) and [Terminals](https://diffinery.com/docs/agents/terminal).

98

99

100

### Agent review on every pull request

100

101

102

One of your agents reviews pull requests for bugs, security issues and logic errors, the way Cursor's Bugbot does. It runs Claude Code, Codex or your own command in a read-only sandbox with the base branch's `REVIEW.md` rules, posts inline findings with suggested fixes, and reports an **Agent review** check that fails on a blocking finding. **Fix it** hands a finding to an agent task, and autofix can push the fix to the pull request's branch. Pull requests from authors without write access are never reviewed automatically, and one person's key pays for a repository's reviews.

102

103

106

See [Agent review](https://diffinery.com/docs/agents/review).

104

107

105

108

### Today and Needs you

106

109

107

110

**Today** is the first page after you sign in. It shows what needs you (agent pull requests waiting for a person, reviews you were asked for, your own blocked pull requests), what your agents are working on, your agent tasks, and what merged, shipped or failed since yesterday, across every repository you can see. Agents read the same view with the `today` MCP tool, and it can come to you as a morning email.

108

111

109

114

See [Today](https://diffinery.com/docs/agents/today).

110

115

111

116

### Merge on green

112

117

113

118

Pick the checks that must pass in **Settings → Merge on green**, name the agents whose pull requests should land by themselves, and choose whether they wait for a person's approval. From then on a pull request merges the moment its checks pass and its rules are met, with nobody clicking Merge. Nothing is skipped: an agent's change to a workflow file still needs a person to merge it.

114

119

115

122

See [Merge on green automatically](https://diffinery.com/docs/collaboration/merge-on-green).

116

123

117

124

### Projects, sandboxes and docs for agents

codician/diffinerypublic

README: put each screenshot next to the text it shows #321

		@@ -23,22 +23,11 @@
23	23
24	24	If Diffinery is useful to you, a star on GitHub helps other people find it.
25	25
26		-## Screenshots
27		-
28		-\| Today: what needs you, agents at work and what merged since yesterday \| An agent's pull request, reviewed by another agent with an inline finding and a Fix it button \|
29		-\| --- \| --- \|
30		-\| [![The Today page on Diffinery: counts of what needs you, agent pull requests open, merged since yesterday and failed runs, then the Needs you, Agents at work, Your agent tasks and Since yesterday sections](docs/images/today.png)](docs/images/today.png) \| [![A pull request opened by an agent on Diffinery, with its intent, a link to the task that wrote it, and an agent review with an inline finding, a suggested fix and a Fix it button](docs/images/agent-pull-request.png)](docs/images/agent-pull-request.png) \|
31		-\| An agent task: Claude Code turns a goal into a pull request in a sandbox \| Merge on green: auto-merge on, checks passed, waiting for a person's approval \|
32		-\| [![An agent task on Diffinery: the goal, Claude Code running as the acme-coder agent, its transcript with file edits and test runs, and the pull request it opened](docs/images/agent-task.png)](docs/images/agent-task.png) \| [![The merge box of an agent's pull request on Diffinery, with its required checks passed and auto-merge on, waiting for a person's approval](docs/images/merge-on-green.png)](docs/images/merge-on-green.png) \|
33		-\| A repository, with the clone URL and one-click open in VS Code, Cursor, Windsurf and IntelliJ IDEA \| A workflow run from `.github/workflows/ci.yml`, with a matrix and `needs` \|
34		-\| [![A repository's code page on Diffinery](docs/images/repository.png)](docs/images/repository.png) \| [![A GitHub Actions–compatible workflow run on Diffinery](docs/images/actions-run.png)](docs/images/actions-run.png) \|
35		-
36		-[![A job's live log on Diffinery, in dark mode](docs/images/job-logs-dark.png)](docs/images/job-logs-dark.png)
37		-
38	26	## Contents
39	27
40	28	- [Who Diffinery is for](#who-diffinery-is-for)
41	29	- [Why Diffinery](#why-diffinery)
	30	+- [Screenshots](#screenshots)
42	31	- [Built for AI coding agents](#built-for-ai-coding-agents)
43	32	- [Plugins and integrations](#plugins-and-integrations)
44	33	- [Features](#features)
		@@ -69,9 +58,19 @@
69	58	- Secure by default. Passkey sign-in with no passwords, invite-only accounts, branch protection, push protection that blocks leaked credentials, envelope-encrypted secrets, kill switches and an append-only audit log.
70	59	- Moving from GitHub is one step. A server-side importer brings a repository or a whole organization over with its history, issues, pull requests, reviews and releases, and `gh`, Octokit, VS Code and JetBrains IDEs work against Diffinery.
71	60
	61	+## Screenshots
	62	+
	63	+Git hosting and CI. The agent features have their own screenshots in [Built for AI coding agents](#built-for-ai-coding-agents), just below.
	64	+
	65	+\| A repository, with the clone URL and one-click open in VS Code, Cursor, Windsurf and IntelliJ IDEA \| A workflow run from `.github/workflows/ci.yml`, with a matrix and `needs` \|
	66	+\| --- \| --- \|
	67	+\| [![A repository's code page on Diffinery](docs/images/repository.png)](docs/images/repository.png) \| [![A GitHub Actions–compatible workflow run on Diffinery](docs/images/actions-run.png)](docs/images/actions-run.png) \|
	68	+
	69	+[![A job's live log on Diffinery, in dark mode](docs/images/job-logs-dark.png)](docs/images/job-logs-dark.png)
	70	+
72	71	## Built for AI coding agents
73	72
74		-Every agent feature is opt-in and sits on top of the Git and CI platform, so a team that uses none of them just has a forge. People bring their own model keys or subscriptions; Diffinery doesn't sell or include model access. The [screenshots](#screenshots) are the real pages, taken from a local Diffinery with sample data by [`scripts/agent-screenshots.mjs`](apps/diffinery/scripts/agent-screenshots.mjs), which runs a real agent task, agent review and CI run.
	73	+Every agent feature is opt-in and sits on top of the Git and CI platform, so a team that uses none of them just has a forge. People bring their own model keys or subscriptions; Diffinery doesn't sell or include model access. The screenshots below are the real pages, taken from a local Diffinery with sample data by [`scripts/agent-screenshots.mjs`](apps/diffinery/scripts/agent-screenshots.mjs), which runs a real agent task, agent review and CI run.
75	74
76	75	### Agent accounts with guardrails
77	76
		@@ -94,24 +93,32 @@
94	93
95	94	To use your Claude or ChatGPT subscription instead of an API key, open a [terminal](https://diffinery.com/docs/agents/terminal): a shell in your browser with the repository checked out, where you sign in to Claude Code or Codex with your own plan and can hand it tasks.
96	95
	96	+[![An agent task on Diffinery: the goal, Claude Code running as the acme-coder agent, its transcript with file edits and test runs, and the pull request it opened](docs/images/agent-task.png)](docs/images/agent-task.png)
	97	+
97	98	See [Agent tasks](https://diffinery.com/docs/agents/tasks) and [Terminals](https://diffinery.com/docs/agents/terminal).
98	99
99	100	### Agent review on every pull request
100	101
101	102	One of your agents reviews pull requests for bugs, security issues and logic errors, the way Cursor's Bugbot does. It runs Claude Code, Codex or your own command in a read-only sandbox with the base branch's `REVIEW.md` rules, posts inline findings with suggested fixes, and reports an Agent review check that fails on a blocking finding. Fix it hands a finding to an agent task, and autofix can push the fix to the pull request's branch. Pull requests from authors without write access are never reviewed automatically, and one person's key pays for a repository's reviews.
102	103
	104	+[![A pull request opened by an agent on Diffinery, with its intent, a link to the task that wrote it, and an agent review with an inline finding, a suggested fix and a Fix it button](docs/images/agent-pull-request.png)](docs/images/agent-pull-request.png)
	105	+
103	106	See [Agent review](https://diffinery.com/docs/agents/review).
104	107
105	108	### Today and Needs you
106	109
107	110	Today is the first page after you sign in. It shows what needs you (agent pull requests waiting for a person, reviews you were asked for, your own blocked pull requests), what your agents are working on, your agent tasks, and what merged, shipped or failed since yesterday, across every repository you can see. Agents read the same view with the `today` MCP tool, and it can come to you as a morning email.
108	111
	112	+[![The Today page on Diffinery: counts of what needs you, agent pull requests open, merged since yesterday and failed runs, then the Needs you, Agents at work, Your agent tasks and Since yesterday sections](docs/images/today.png)](docs/images/today.png)
	113	+
109	114	See [Today](https://diffinery.com/docs/agents/today).
110	115
111	116	### Merge on green
112	117
113	118	Pick the checks that must pass in Settings → Merge on green, name the agents whose pull requests should land by themselves, and choose whether they wait for a person's approval. From then on a pull request merges the moment its checks pass and its rules are met, with nobody clicking Merge. Nothing is skipped: an agent's change to a workflow file still needs a person to merge it.
114	119
	120	+[![The merge box of an agent's pull request on Diffinery, with its required checks passed and auto-merge on, waiting for a person's approval](docs/images/merge-on-green.png)](docs/images/merge-on-green.png)
	121	+
115	122	See [Merge on green automatically](https://diffinery.com/docs/collaboration/merge-on-green).
116	123
117	124	### Projects, sandboxes and docs for agents