mirror of
https://github.com/only-cli/oc.git
synced 2026-09-15 10:40:56 +02:00
only-cli
0f362708f8
Closes #3. An API answer is a page: jsonToHTML turns a JSON body into one article per item, and everything downstream (numbering, budget, do, read, next, raw) treats it as an ordinary document. No per-site logic and no new dependency. The compact view is the hard part, since a search response carries far more fields than fit in 500 tokens. So the renderer scores each field by how much it varies across items against how wide it prints, penalises fields flattened out of a sub-object (owner.reputation describes the asker, not the answer), and spends about 60 characters per item on the winners. What every item shares is stated once at the bottom instead of repeated, empty fields are named rather than printed, and what was cut says so and points at oc raw, which keeps every field. On the Stack Exchange search endpoint that is 30 results in ~960 tokens against ~5,500 for the raw body, with each title a link and question_id visible. Also here: - clis/stackoverflow.com.json gains search <query>, which is what #3 was blocking. Results carry question_id, and the question feed reads one in full, so search now completes without touching the challenged HTML page. - fetch: the native-fetch path rejected anything that was not HTML or XML. It now accepts JSON, which also makes the two transports render one URL the same way, since the impers path never checked the type at all. - raw threads the URL through so its view of an API response can be titled and, unlike the compact view, keeps every field. Deliberately not done, from the notes on the issue: pagination in the actions line, and API metadata on stderr. There is no stderr channel at the distill seam, so response-level fields (has_more, quota_remaining) render as one footer line instead. A columns hint in the clis specs and a --json passthrough both looked like the wrong trade: the first needs per-site tuning for something the scoring already handles, the second would break the machine-stable Page contract.
25 lines
3.0 KiB
Plaintext
25 lines
3.0 KiB
Plaintext
# only-cli
|
|
|
|
> only-cli (command: `oc`) turns websites into a command line interface for AI agents. Instead of fetching raw HTML (tens of thousands of tokens) or driving a headless browser with screenshots, an agent runs `npx @only-cli/oc open <url>` and gets a distilled text view of the page in a few hundred tokens, with numbered links and form fields it can act on. Works with Claude Code, Claude, ChatGPT, Codex, Gemini, Antigravity, and any agent that can run shell commands.
|
|
|
|
Key facts:
|
|
|
|
- Install: `npm install -g @only-cli/oc`, or zero-install with `npx @only-cli/oc`
|
|
- Commands: `oc open <url>` (compact view with numbered actions), `oc do <n>` (follow numbered link [n], or read [n] when it is text rather than a link), `oc find <query>` (where a string appears on the page already open), `oc read <n>` (one region in full), `oc next` (the next screenful), `oc raw [url]` (whole page as markdown, `--html` for cleaned HTML), `oc --help` for the full surface
|
|
- Default output budget is 500 tokens per page; `--budget <n>` adjusts it, and `find`, `read <n>`, or `next` collect what the budget cut without refetching the page
|
|
- The budget is a target rather than a hard cap: a page that would finish within about four times it is printed whole, because a second command costs the agent far more than the lines the cut would have saved
|
|
- The render leads with the page's main content and puts navigation, sidebar, and footer after it, so the budget is spent on what was asked for rather than on menus
|
|
- Benchmarked at roughly 45x fewer tokens than reading raw HTML, with per-task numbers at https://github.com/only-cli/benchmarks
|
|
- Works on any mostly-static website; tuned shortcuts ship for Hacker News, Reddit, GitHub, X, LinkedIn (public guest views), DuckDuckGo, Bing, Stack Overflow (via its Atom feeds and the Stack Exchange API), and Yahoo Finance (quotes, history, markets)
|
|
- JSON APIs render like pages: an endpoint that answers with JSON becomes one numbered item per record, with the fields that differ between items kept and the ones every item shares stated once, so a search endpoint reads like a results page for a few hundred tokens
|
|
- X profiles and individual posts read without a login (about 390 and 260 tokens); X search, explore, and hashtag pages do not, and oc reports the block instead of guessing
|
|
- Requests impersonate Chrome, so pages that block plain scripts often still work
|
|
- Agent skill included: `npx skills add https://github.com/only-cli/oc --skill web-browsing-cli` ([skills.sh](https://www.skills.sh/only-cli/oc/web-browsing-cli))
|
|
- No JavaScript rendering yet and no login sessions yet (both on the roadmap)
|
|
|
|
## Docs
|
|
|
|
- [README](https://github.com/only-cli/oc/blob/main/README.md): install, agent setup, commands, supported websites, benchmarks
|
|
- [CONTRIBUTING](https://github.com/only-cli/oc/blob/main/CONTRIBUTING.md): design principles, adding site definitions
|
|
- [Benchmarks](https://github.com/only-cli/benchmarks): token usage, speed, and success rate against other ways agents read the web
|