Context
The platform's core value proposition is: any developer can create any agent with little code against a wide array of integrations.
The true pain point being solved:
Building an agent that talks to 5 SaaS tools requires wiring 5 OAuth flows, 5 webhook handlers, and 5 auth-refresh cycles — before writing a single line of business logic. The VFS mount model collapses all of that.
The agents repo is a showcase of that platform. This issue captures friction points where the showcase works against the pitch.
What's working
linear agent — ~30 lines, listens to a label event, opens a PR. Hard to argue with the surface area. Best single example of the platform's promise.review agent — multiple triggers, complex behavior, still readable. Shows the ceiling without losing clarity.
What's working against the pitch
1. 20 agents of uneven complexity obscure the "little code" claim.
A visitor has to do work to find the simple ones. The monitoring agents involve threshold logic, dedup, and alert formatting that makes agent authoring look harder than it is.
2. Telegram/Slack variants as separate agents signal the multi-channel story isn't clean.
If the platform handled multi-channel natively, you'd have one agent with two delivery targets — not hn-monitor and hn-monitor-telegram as separate personas. This subtly implies more code than there should be.
3. No contrast to make the abstraction visible.
The VFS/integration abstraction is the 10x differentiator, but no README or example shows what you'd write without it. The value is invisible if you don't already know what OAuth plumbing looks like.
Suggested fix
Add a single "before/after" comparison — either in the root README or a dedicated docs/why-this-platform.md:
- Without platform: ~200 lines (OAuth setup, token refresh, webhook handler, pagination, error handling)
- With platform: the
linear agent's 30 lines of actual logic
That contrast is the pitch. Everything else in the repo is evidence for it.
Context
The platform's core value proposition is: any developer can create any agent with little code against a wide array of integrations.
The true pain point being solved:
The agents repo is a showcase of that platform. This issue captures friction points where the showcase works against the pitch.
What's working
linearagent — ~30 lines, listens to a label event, opens a PR. Hard to argue with the surface area. Best single example of the platform's promise.reviewagent — multiple triggers, complex behavior, still readable. Shows the ceiling without losing clarity.What's working against the pitch
1. 20 agents of uneven complexity obscure the "little code" claim.
A visitor has to do work to find the simple ones. The monitoring agents involve threshold logic, dedup, and alert formatting that makes agent authoring look harder than it is.
2. Telegram/Slack variants as separate agents signal the multi-channel story isn't clean.
If the platform handled multi-channel natively, you'd have one agent with two delivery targets — not
hn-monitorandhn-monitor-telegramas separate personas. This subtly implies more code than there should be.3. No contrast to make the abstraction visible.
The VFS/integration abstraction is the 10x differentiator, but no README or example shows what you'd write without it. The value is invisible if you don't already know what OAuth plumbing looks like.
Suggested fix
Add a single "before/after" comparison — either in the root README or a dedicated
docs/why-this-platform.md:linearagent's 30 lines of actual logicThat contrast is the pitch. Everything else in the repo is evidence for it.