docs: README rewrite — story-first positioning#13
Conversation
Greptile SummaryThis PR rewrites Key issues remaining:
Confidence Score: 3/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant A as Coordinator Agent A
participant API as Delega API
participant B as Researcher Agent B
participant C as Writer Agent C
participant WH as Webhook Consumer
A->>API: POST /api/tasks (create task)
API-->>A: task_id
A->>API: POST /api/tasks/{id}/delegate (assign to B)
API-->>A: child_task_id
B->>API: GET /api/tasks (pick up task)
B->>API: PATCH /api/tasks/{id}/context (attach work-in-progress data)
B->>API: POST /api/tasks/{child_id}/delegate (delegate to C)
API-->>B: grandchild_task_id
C->>API: POST /api/tasks/{grandchild_id}/complete
API->>WH: POST webhook (task.completed event + HMAC signature)
A->>API: GET /api/tasks/{id}/chain
API-->>A: full delegation chain (A→B→C)
Reviews (2): Last reviewed commit: "docs: address Greptile review — fix 4 do..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
@greptile review |
- Lead with Kevin Rose quote and multi-agent coordination problem - 30-second try-it with npx @delega-dev/cli init up front - Add 'Who this is for' section - Collapse API reference tables into <details> - Update MCP tool count to 11 - Update free tier to 5 agents, 1 webhook (PLG changes) - Add ecosystem table with all packages
- Add MCP client config JSON blocks (Claude Code, Cursor, VS Code) - Restore missing API endpoints (webhook CRUD, delivery history, project CRUD) - Add DELEGA_DATABASE_URL to config table (Postgres support) - Fix paperclip-delega install command
ryanmcmillan
force-pushed
the
feature/readme-rewrite
branch
from
cad33d2 to
b383ae8
Compare
| - **Persistent context**: Attach structured context to tasks that survives across agent sessions. | ||
| - **Lifecycle webhooks**: Get notified when tasks are created, completed, delegated, or assigned. | ||
| - **Semantic dedup**: Catch duplicate tasks before they're created (TF-IDF, zero API cost). | ||
| Or just run `npx @delega-dev/mcp` and it works. |
There was a problem hiding this comment.
npx @delega-dev/mcp claim is misleading
"Or just run npx @delega-dev/mcp and it works." — without any environment variables (DELEGA_AGENT_KEY, DELEGA_API_URL), this command won't result in a working MCP connection. At minimum, users need their agent key. Running it bare will either throw an error or prompt interactively, neither of which is obvious from this sentence.
This line appeared in the old README too, but the context there was "install the package", not "run it in place of a config block". In the current placement it reads as a fallback to the three config snippets above, implying it's a complete solution on its own.
Consider replacing with a note that clarifies what's required:
| Or just run `npx @delega-dev/mcp` and it works. | |
| Or use `npx @delega-dev/mcp` directly with `DELEGA_AGENT_KEY` set in your shell environment. |
| <details> | ||
| <summary><strong>Claude Code</strong></summary> | ||
|
|
||
| **Self-hosted** (free, forever) or **hosted** at [api.delega.dev](https://delega.dev). | ||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "delega": { | ||
| "command": "npx", | ||
| "args": ["-y", "@delega-dev/mcp"], | ||
| "env": { | ||
| "DELEGA_AGENT_KEY": "dlg_your_key_here" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| </details> | ||
|
|
||
| ## Why Delega? | ||
| <details> | ||
| <summary><strong>Cursor / Windsurf</strong></summary> | ||
|
|
||
| AI agents can write code, draft emails, and analyze data. But they can't coordinate. | ||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "delega": { | ||
| "command": "npx", | ||
| "args": ["-y", "@delega-dev/mcp"], | ||
| "env": { | ||
| "DELEGA_AGENT_KEY": "dlg_your_key_here" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| </details> | ||
|
|
||
| When Agent A needs Agent B to do something, there's no standard way to hand off that task, track whether it got done, or pass context along. Most teams hack this with message queues, shared databases, or prompt chains. Delega makes it a first-class primitive. | ||
| <details> | ||
| <summary><strong>VS Code / Copilot</strong></summary> | ||
|
|
||
| This is the same pattern playing out across agent infrastructure. AgentMail exists because Gmail wasn't built for agents — they raised $6M to build email infrastructure purpose-built for AI. Ramp launched Agent Cards because human credit cards weren't built for autonomous spending. Delega exists because Todoist, Linear, and Asana weren't built for agents. The tools agents need look different from the tools humans need. | ||
| ```json | ||
| { | ||
| "servers": { | ||
| "delega": { | ||
| "type": "stdio", | ||
| "command": "npx", | ||
| "args": ["-y", "@delega-dev/mcp"], | ||
| "env": { | ||
| "DELEGA_AGENT_KEY": "dlg_your_key_here" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| </details> |
There was a problem hiding this comment.
DELEGA_API_URL
All three MCP config blocks (Claude Code, Cursor / Windsurf, VS Code / Copilot) only include DELEGA_AGENT_KEY. For users on the hosted api.delega.dev tier, that's sufficient — but for self-hosters, the MCP server also needs DELEGA_API_URL to know where to connect. Without it, the MCP package will either error out or silently hit the hosted endpoint instead of the local instance.
The old README's config block explicitly set "DELEGA_API_URL": "http://127.0.0.1:18890". The new blocks have dropped this entirely, meaning any self-hosted user following the "Already have an account?" path will get a non-functional config.
Consider adding DELEGA_API_URL (pointing to localhost:18890) as a second env entry in each config block, with a note that it can be omitted when using the hosted tier. Alternatively, add a short sentence below the collapsed blocks: "Self-hosted? Also set DELEGA_API_URL=http://localhost:18890 in the env block."
1 participant
What changed
Complete README rewrite. Same information, different energy.
Before: 337 lines of docs-first reference material. Feature tables, API endpoints, configuration vars.
After: Story-first positioning that answers "why should I care" before "how does it work."
Key changes:
npx @delega-dev/cli init) before any docs<details>so it doesn't overwhelmWhy
GStack hit 38K stars in 2 weeks. The product is markdown files. The README reads like a manifesto. Our product is real infrastructure and our README read like a man page. Fixing that.