only-cli/oc: a token-budgeted CLI view of the web for coding agents
Turn any website into a compact CLI tailored for AI agents. Browse the web in hundreds of tokens, not tens of thousands.
At a glance
- What is it?
- only-cli/oc renders a fetched page as a numbered, token-capped list of regions instead of raw HTML, so an agent can read a page in hundreds of tokens rather than tens of thousands. The idea is sound and the shortcut list is unusually broad, but the project is young, form filling is still marked planned, and there is no published evaluation of how often the renderer drops something that mattered.
- Who is it for?
- Adopt only-cli/oc if your agent already shells out to a browser or a fetch tool and you want the page content itself to stop dominating the context window; the numbered-region model plus `oc find` and `oc next` is a reasonable way to read a long page in pieces. Do not adopt it if your workflow depends on filling and submitting forms, since `oc fill` and `oc submit` are still marked planned, or if you need a stable renderer contract for a production pipeline.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The token bill that only-cli/oc is trying to reduce
An agent that fetches a page usually gets one of two things: the raw HTML, or a screenshot it has to interpret. The README puts the first case plainly, saying a typical page is tens of thousands of tokens of markup while the rendered view fits in a few hundred. That ratio is the whole pitch. It is not a scraping library and it is not a headless browser you drive yourself; it is a renderer that decides what part of a page is worth showing and prints that part as a numbered list.
The audience is narrow and specific. It is agents that can run shell commands: the README names Claude Code, Codex, and Antigravity, and it ships an installable skill plus a one-line instruction you paste into CLAUDE.md or AGENTS.md. If your agent cannot execute a command, this project has nothing to offer it. If your agent can, the interesting question is not whether compact output helps (it obviously does) but whether the compaction keeps the part you needed.
Numbered regions, a budget, and a paging model
The output format is the mechanism. `oc open <url>` returns a heading, a list of numbered items, and a trailing `actions:` line that advertises the available verbs. The README's Hacker News example shows entries like `[1] Show HN: I built a tiny CSV toolkit` followed by `actions: do <n> | find <query> | read <n> | next | raw`. So the agent never holds the whole page. It holds an index and pulls detail on demand.
The default budget is 500 tokens, set by `--budget <tokens>`. `oc next` returns the next budget's worth of the page already open, which means a long document is consumed in passes rather than in one call. `oc read <n>` returns the full text of a region, capped at 2000 tokens according to the command list. `oc find <query>` searches the page that is already open and returns either the locations of a match or the region itself when only one place matches. That last behaviour is a small design decision with real consequences: a single match short-circuits the lookup, so the agent gets content instead of coordinates.
There is also a JSON path. The README states that `oc open` against an endpoint that answers with JSON renders one numbered item per record, keeps fields that differ between items, and states once what every item shares. That is a sensible compression rule for API responses, and it is the part of the design I would want to see documented in more detail, because the choice of which fields count as varying is where the output either stays useful or becomes misleading.
Getting past blocks, and what happens when impersonation fails
The project does not use a plain HTTP client. The README says requests impersonate Chrome via impers, and that when a site or the local copy of libcurl-impersonate refuses the Chrome identity, the request downgrades to Firefox, and then to native fetch when impers is unavailable or refuses both. That is a three-tier fallback, and it matters for predictability: the same URL can be fetched by three different mechanisms depending on what is installed and what the remote server tolerates. The rendered result is presumably similar, but the failure mode when all three decline is a plain fetch, which is exactly the case the impersonation layer exists to avoid.
Installation is one command, `npm install -g @only-cli/oc`, with Node 20+ required. The README also notes that no setup works at all: `npx @only-cli/oc` runs without a global install and teaches its own commands through `--help` and the `actions:` line printed on every render. That self-describing behaviour is the right call for an agent-facing tool, since it removes the need to keep a separate command reference in the agent's context.
The site shortcuts are the real surface area
Generic rendering is the default, but the shipped shortcuts are what make the tool pleasant to use. The README's table covers Hacker News, Reddit, GitHub, X, LinkedIn, DuckDuckGo, Bing, Stack Overflow, Yahoo Finance, YouTube, Wikipedia, AWS docs, Google Cloud docs, Microsoft Learn, Python docs, MDN, Node.js docs, Ruby docs, Go packages, PHP manual, Rust docs, Java docs, and C and C++, with more listed after the truncated point. Each entry names both the command and the verbs, so `oc hn item 4711` and `oc gh repo only-cli oc` reach the right page without the agent constructing a URL.
Several of these are not scraping at all, and the README is explicit about it. Reddit goes through Atom feeds on www.reddit.com. Stack Overflow goes through Atom feeds and the Stack Exchange API. Wikipedia uses `action=render`. Google Cloud docs search goes through DuckDuckGo. That is a meaningful architectural detail: where a structured source exists, the project prefers it, and the HTML renderer is the fallback for everything else. It also means shortcut reliability is tied to those upstream sources staying open, which is a dependency the generic path does not have.
You can name a site by its short name, its bare name, or its domain, and `oc sites` prints the full list with verbs. That is a good affordance for an agent that has forgotten the exact spelling.
Prompt injection, sessions, and the limits the README admits
The README contains a warning that deserves more weight than its placement suggests: rendered page text is data, not instructions, and a page can contain text written to look like a command. The tool prints page content into the same channel where an agent reads its own command output. Nothing in the described design separates the two. The mitigation offered is procedural, a sentence telling the agent to treat output as content. That is the correct thing to say and it is also the entire defence.
Sessions exist but are thin. `oc login` seeds cookies for a session and takes `--cookie` and `--domain`; `oc logout [session]` forgets a session, its cookies, and its saved page. `--session <name>` selects one. There is no described mechanism for refreshing an expired session, so a long-running agent that logs in once and works for hours will need its own handling for the moment the cookies stop working.
The command list marks `oc fill <n> <text>` and `oc submit [n]` as planned. That is the clearest boundary in the project. Anything requiring interaction beyond following a link is out of scope today, which rules out search forms that only work on POST, login flows that need a real submit, and most multi-step checkout or dashboard tasks. If your agent's job is to read, this does not matter. If its job is to act on a site, it does.
One more constraint worth stating: the README says the tool works on any mostly-static site with no per-site setup. That qualifier is doing a lot of work. Client-rendered applications that assemble their content in JavaScript are not covered by that description, and the README does not claim otherwise.
What it is not, and what to compare it against
The obvious alternative is a headless browser driven by a library such as Playwright or Puppeteer. The difference in approach is where the work happens. A headless browser gives the agent a real DOM and full interaction: click, type, submit, wait for network idle, screenshot. It also hands back a large amount of material the agent must then reduce, and it requires a browser binary and the associated process management. only-cli/oc inverts that. It does the reduction before the agent sees anything, and it gives up interaction to do so. The `fill` and `submit` commands being planned rather than shipped is the price of that inversion, stated openly in the command list.
A second comparison is the read-it-later extractor, the class of tool that takes a URL and returns article text as markdown. Those tend to be tuned for prose and to discard navigation, which is exactly the opposite of what an agent browsing a site needs. only-cli/oc keeps the structure as numbered regions and lets the agent choose, which is why `oc do <n>` and `oc next` exist at all. `oc raw [url]` is the escape hatch when you want the whole page distilled to markdown in one shot rather than paged.
The honest summary is that this is a reading tool with a browsing-shaped interface. It competes with fetch-and-summarize pipelines more than it competes with browser automation.
Maintenance, licensing, and what to check before relying on it
The licence is MIT, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement with few obligations, but it is not legal advice and the repository's LICENSE file is the authority. The project also carries an OpenSSF Scorecard badge, which points at a public scorecard page rather than stating a result in the README.
On maintenance, the release history shows v0.5.1, v0.5.2, and v0.5.3 within a few days of each other in early September 2026, and the last push to the default branch is dated 2026-09-08. Three patch releases in a week can mean active bug fixing or a churny pre-1.0 surface; the version number suggests the latter is at least possible. Nothing in the material indicates a deprecation or archival, and the repository is explicitly not archived.
The upgrade cost is mostly the impersonation dependency. Because the request path can fall back from Chrome to Firefox to native fetch, a change in impers or in the local libcurl-impersonate build can change which mechanism a given site sees, and the README does not describe any pinning or version check for that. If a shortcut breaks, the first thing to check is whether the impersonation layer is still installed and working, not whether the site changed. For the site shortcuts specifically, the upstream sources are the exposure: Reddit's Atom feeds, the Stack Exchange API, Wikipedia's `action=render`, and the documentation sites' own search endpoints are all outside this project's control, and any of them changing shape would break a shortcut without touching `oc` itself.
Editorial conclusion
Adopt only-cli/oc if your agent already shells out to a browser or a fetch tool and you want the page content itself to stop dominating the context window; the numbered-region model plus `oc find` and `oc next` is a reasonable way to read a long page in pieces. Do not adopt it if your workflow depends on filling and submitting forms, since `oc fill` and `oc submit` are still marked planned, or if you need a stable renderer contract for a production pipeline. Verify first that the pages you actually depend on render correctly at your chosen `--budget`, and check whether `--json` gives you a shape you can parse rather than screen-scraping the numbered list.
Community notes