docs: rewrite README as a calling-agent landing page - #46
Merged
Conversation
The old README dumped MCP flags and mailbox internals before a stranger knew why they would install. Identity now matches the product: OpenAdapt compiles programs; this package invokes them over MCP (96 chars, shared with copy.py, server.json, llms.txt, and the skill frontmatter).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This README is the page a calling-agent author hits on GitHub and on PyPI. The previous one was internally true and unreadable as a landing page. MCP flags and mailbox internals showed up before a stranger knew why they would install. Attended-action policy sat in the same first screen.
The rewrite leads with the outcome. Point Claude Code, Cursor, Codex, or Grok CLI at
openadapt-agent serve --allow-runand the calling agent invokes a compiled GUI program on this computer. Hosted ChatGPT.com / Claude.ai getauthoring connector Desktop Connect this computer on/j/{id}. They don't getserve.The identity sentence changed because the old one was product-wrong. "OpenAdapt is a compiled program for GUI writes with no API" treated OpenAdapt as the program. OpenAdapt is the compiler. The sold noun is program. New sentence, 96 chars, MCP registry max 100:
That sentence is still the first README paragraph, the
server.jsondescription, thellms.txtblockquote, and the skill frontmatter.copy.pyremains the source.Check against origin/main of this repo, not against an old computer-use pitch:
serveis stdio,authoring connectis the mailbox, Desktop owns overlay chrome.--allow-runstays an explicit opt-in. Admission stays fail-closed.name: computer-usestays absent.Every remaining README pin is a contract. The comment on
test_identity_sentence_is_sharednow says so, so the next rewrite doesn't treat those strings as ordinary copy.Kept:
mcp-name: io.github.OpenAdaptAI/openadapt-agent(MCP registry namespace via the PyPI readme)IDENTITY_SENTENCEshared and ≤100 charsTHREE_LINE_INSTALLand the findable commands (serve --allow-run,serve --authoring,authoring connect,openadapt connect,openadapt quickstart --break-it)name: computer-useabsentOpened by an agent session, not the founder.