# Use Obi's docs from your AI agent Source: https://hireobi.com/docs/ai-agents Connect your coding agent to Obi's documentation: the docs MCP server, Markdown versions of every page, llms.txt, llms-full.txt and the setup skill. These endpoints give an AI agent Obi's public documentation in a form it can read. They answer questions about Obi; they do not reach your account. To work on your business, install the CLI and its Skill with the [quickstart](/docs/quickstart). | Endpoint | What it gives an agent | | - | - | | `https://hireobi.com/docs/mcp` | A Model Context Protocol server that searches these docs | | `https://hireobi.com/docs/.md` | The Markdown version of any page, such as [`/docs/quickstart.md`](https://hireobi.com/docs/quickstart.md) | | [`/docs/llms.txt`](https://hireobi.com/docs/llms.txt) | An index of every page with a one-line description | | [`/docs/llms-full.txt`](https://hireobi.com/docs/llms-full.txt) | The whole documentation in one Markdown file | | [`/docs/skill.md`](https://hireobi.com/docs/skill.md) | A skill that tells an agent how to install and set up Obi | A request for a page with the header `Accept: text/markdown` also returns its Markdown version. ## Connect the docs MCP server The server needs no sign-in and speaks streamable HTTP. > [tab] Claude Code > > ```bash theme={null} > claude mcp add --transport http obi-docs https://hireobi.com/docs/mcp > ``` > [tab] Codex CLI > > ```bash theme={null} > codex mcp add obi-docs --url https://hireobi.com/docs/mcp > ``` > [tab] Cursor and VS Code > > Open any page of these docs, open the page menu next to its title, and choose **Connect to Cursor** or **Connect to VS Code**. For any other client that supports streamable HTTP, add a server with the URL `https://hireobi.com/docs/mcp`. ## Install Obi itself The setup skill and the [quickstart](/docs/quickstart) give the same steps: ```bash theme={null} npm install --global @hireobi/cli obi skill install ``` Then open a new chat and type `/obi` (`$obi` in Codex CLI). The bundled Skill carries everything Obi does in your assistant. # Obi CLI commands Source: https://hireobi.com/docs/cli/commands The obi commands and their options, as the installed CLI accepts them. Commands accept `--json`, and the commands that call your account accept `--timeout-ms <100-30000>` (see [global options](/docs/cli/overview#global-options)). Commands that start paid work or approve your review take an explicit confirmation flag, such as `--confirm-scan` or `--confirm-review`, so they never run by accident. `obi --help` prints the full grammar of your installed version. ## Account and setup ### status ```bash theme={null} obi status ``` Reads your connected account and the next step it is waiting for. `AUTH_REQUIRED` means this machine is not signed in. ### login ```bash theme={null} obi login --expect-email [--storage file] ``` Connects this machine to your account through the browser; see the [quickstart](/docs/quickstart#connect-your-account). `--expect-email` is required when the command does not run in an interactive terminal. `--storage file` keeps the connection in an owner-only file instead of the system credential store, and is required on Windows. ### logout ```bash theme={null} obi logout ``` Signs this machine out. ### credentials ```bash theme={null} obi credentials list obi credentials revoke [--force] ``` `list` shows the live CLI connections of your account that you may see, most recently used first, with each device label, CLI version and dates. `revoke` ends one connection. Revoking the connection this machine uses is refused unless you add `--force`, which also signs this machine out. ### skill ```bash theme={null} obi skill install obi skill path ``` `install` links the bundled Skill into `~/.agents/skills/obi` and `~/.claude/skills/obi`, and never replaces an existing entry. `path` prints where the bundled Skill is. ### doctor ```bash theme={null} obi doctor ``` A local diagnostic that sends no request: your Node.js version, the CLI version, the server origin it is pinned to, where the connection is stored, and whether the video tools `yt-dlp` and `ffmpeg` are installed. ### capabilities ```bash theme={null} obi capabilities --json ``` The commands, actions and options this installed version supports, and the version of the expertise its Skill carries. ## How Obi's work reaches your account Obi researches your business, writes your buyer questions and reasons over your results in your assistant. The Skill reads the work your account expects with `harness show` and saves your assistant's result with `harness submit`, stage by stage: `business`, then `questions`, then `strategies`. See [Harness work](#harness-work). Because your assistant does this work, the server-side commands `business start`, `business discover`, `questions prepare` and `questions edit` are refused with `HARNESS_REQUIRED` or `HARNESS_QUESTIONS_REQUIRED`. ## Business These commands display and correct the business review. All of them except `show` act on the review version you last displayed: pass the `--snapshot ` that `business show` returned, and read `business show` again after each change. ```bash theme={null} obi business show obi business clarify-identity --snapshot --company obi business clarify-fact --snapshot --field-path --text --company --company-wide [--segment-name ] obi business challenge --snapshot --reason obi business correct --snapshot --claim-id --field-path --text --company --company-wide obi business add-competitor --snapshot [--reason ] obi business remove-competitor --snapshot [--reason ] obi business readd-competitor --snapshot [--reason ] obi business remove --snapshot [--reason ] obi business confirm --snapshot --confirm-review ``` | Action | What it does | | - | - | | `show` | Displays the current review: identity, summary, target buyer, competitors, with sources | | `clarify-identity` | Sets the company name | | `clarify-fact` | Answers a missing fact for the whole company; `--segment-name` names a buyer segment you add | | `challenge` | Disputes a sourced claim, with a reason | | `correct` | Replaces a sourced claim with your correction | | `add-competitor`, `remove-competitor`, `readd-competitor`, `remove` | Change the competitor set | | `confirm` | Confirms the review once; it does not start a scan | See [Business review](/docs/how-it-works/business). ## Questions and scans ```bash theme={null} obi questions show obi questions proceed --candidate-version --confirm-scan obi questions results [--run latest|first|] [--from ] ``` | Action | What it does | | - | - | | `show` | The current question set, its version and its preparation state | | `proceed` | Starts the scan of the displayed question version | | `results` | The measured answers, with engines, dates and citations | `proceed` needs both the version you reviewed and `--confirm-scan`. After a timeout, run `questions show` before anything else. `results` reads the latest completed scan and lists your scans, newest first. `--run first` or `--run ` reads another one; a long scan comes in pages, and `--from` reads the same scan from a later question. See [Buyer questions](/docs/how-it-works/questions) and [Scans and engines](/docs/how-it-works/scans). ## Readiness and strategies ```bash theme={null} obi readiness obi strategies ``` `readiness` reads the saved [Readiness report](/docs/how-it-works/readiness); it never starts a new reading. `strategies` reads your saved [priorities](/docs/how-it-works/strategies). ## Memory ```bash theme={null} obi memory list obi memory add --kind --text "" obi memory remove ``` What Obi remembers about how you work, across assistants and sessions: a preference ("answer in French"), a constraint ("never propose rival X") or a decision ("French market first"). Business facts are not memory: they live in the sourced review and its corrections. ## Harness work The Skill runs these for you; you rarely need them yourself. ```bash theme={null} obi harness coverage obi harness activate --free obi harness show --stage [--packs <1-40>] obi harness submit --stage --input obi harness evidence --work-id [--kind claims|sections|measurements] [--cursor ] [--query ] [--url ] [--all --output ] obi harness artifact --work-id [--input ] [--revision ] [--output ] [--cursor ] [--limit <1-100>] obi harness outcomes --task-id [--cursor ] [--limit <1-50>] obi harness observe --input obi harness purchase [--input ] [--confirm-checkout] [--confirm-change] ``` | Action | What it does | | - | - | | `coverage` | Your plan's question and engine coverage, and whether the Free plan can be activated | | `activate --free` | Activates the Free plan on an eligible account; starts no scan | | `show` | The work context of a stage: work ID, version, allowed sources, next batch | | `submit` | Saves your assistant's result for a stage | | `evidence` | Searches the saved facts, page sections or scan measurements of a work; `--all` exports them to a file | | `artifact` | Saves, shows, lists the revisions of, or exports a draft | | `outcomes` | Reads the outcomes recorded for a saved task | | `observe` | Records an implementation you confirmed | | `purchase` | Quotes a first plan for reviewed questions, prepares its checkout, reads its status, resumes it, or changes an existing paid plan | `purchase prepare` requires `--confirm-checkout` and returns a checkout page on `agent.hireobi.com`, which it opens in your browser when it can. `purchase resume` takes the quote ID only and never starts a second checkout. `purchase change` changes the packs or engines of an existing paid plan. Without `--confirm-change` it only previews the change and charges nothing: the amount due now for an increase, or the date a reduction takes effect. The same command with `--confirm-change` applies that previewed change. See [Plans](/docs/plans#changing-your-packs). ## Local research helpers These run on your machine and write local files; they send nothing to your account and take no `--timeout-ms`. ```bash theme={null} obi research crawl --checkpoint --output [--batch-size <1-100>] [--locale ] [--pages priority|all] [--max-pages ] [--retry-failed|--refresh] obi research capture --input --checkpoint --output obi research readiness --input --output obi research video --output [--frames <0-30>] ``` | Action | What it does | | - | - | | `crawl` | Reads a site's pages in resumable batches, keeping its progress in the checkpoint file | | `capture` | Adds a page your assistant's browser observed to the corpus | | `readiness` | Writes a Readiness report from a corpus | | `video` | Saves a video's metadata and one caption track, plus up to 30 still frames, to the directory; needs `yt-dlp`, and `ffmpeg` for frames | Reading through your machine shows what that machine sees; it does not prove what an AI provider's crawler can reach. ## Operator evaluations ```bash theme={null} obi eval start obi eval list ``` Authorized Obi operators can evaluate a public company in an isolated case, then add `--eval-case ` to `status`, `business`, `harness`, `readiness`, `questions`, `strategies` and `memory`. An evaluation does not prove ownership of that company's website. # Obi CLI overview Source: https://hireobi.com/docs/cli/overview Global options, output formats, exit codes, credential storage and environment variables of the obi CLI. The `obi` CLI connects your machine to your Obi account and carries the Skill your assistant runs. In everyday use your assistant runs these commands for you; this reference is for when you want to run or script them yourself. ## Help and version ```bash theme={null} obi --help obi --version obi capabilities --json ``` `--help` prints every command and its options. `capabilities` lists, as JSON, the commands and options this installed version supports. ## Global options | Option | Meaning | | - | - | | `--json` | Print one JSON envelope instead of text; not with `--help` | | `--timeout-ms <100-30000>` | Bound each request to the server, in milliseconds; 5000 by default. Only commands that call the server take it: `research`, `skill`, `capabilities` and a local `doctor` refuse it | ## JSON output With `--json`, every invocation prints exactly one envelope: ```json theme={null} { "schemaVersion": 1, "ok": true, "command": "status", "mode": "product", "data": {} } ``` For example, `obi doctor --json` on a Mac with the video tools installed prints: ```json theme={null} { "schemaVersion": 1, "ok": true, "command": "doctor", "mode": "local", "data": { "node": "v22.22.0", "cliVersion": "0.1.7", "origin": "https://agent.hireobi.com", "credentialStorage": "none", "videoTools": { "ytDlp": true, "ffmpeg": true }, "diagnostic": "completed" } } ``` `credentialStorage` is `keychain`, `secret-service` or `file` once this machine is signed in, and `none` before. A failure has `"ok": false` and an `error` object instead of `data`: ```json theme={null} { "schemaVersion": 1, "command": "status", "mode": "product", "ok": false, "error": { "code": "AUTH_REQUIRED", "message": "This machine is not signed in to Obi.", "retryable": false, "nextAction": "Run obi login --expect-email ." } } ``` `mode` says where the result came from: `local` (this machine only), `product` (your account on Obi's servers) or `test` (a local synthetic server). `nextAction` is always the CLI's own sentence, never text relayed from a server. After a timeout or a conflict on a write, read the current state before retrying. ## Exit codes | Code | Meaning | Examples | | - | - | - | | 0 | Success | | | 1 | Unexpected internal error | `INTERNAL_ERROR` | | 2 | The command, its input or local storage was refused | `INVALID_USAGE`, `CONFIRMATION_REQUIRED`, `STORAGE_UNAVAILABLE` | | 3 | Sign-in needed, pending or refused | `AUTH_REQUIRED`, `AUTHORIZATION_PENDING`, `ACCOUNT_MISMATCH` | | 4 | The account or a feature is not ready | `EMAIL_NOT_VERIFIED`, `ACCOUNT_SETUP_REQUIRED`, `SKILL_INSTALL_FAILED` | | 5 | The server refused the operation in the current state | `OWNER_REQUIRED`, `HARNESS_REQUIRED`, `HARNESS_WORK_CONFLICT`, `SCAN_BUDGET_NOT_AUTHORIZED` | | 6 | The server could not be reached or answered with a refusal this CLI does not know | `NETWORK_UNAVAILABLE`, `REQUEST_TIMED_OUT`, `SERVICE_UNAVAILABLE`, `RATE_LIMITED` (retry later); `REQUEST_FAILED` (update the CLI) | | 7 | The server answered in a form this CLI does not know; update the CLI | `INVALID_RESPONSE`, `DOMAIN_CHANGED` | ## Credentials and local state The CLI keeps your connection in the system credential store: the macOS Keychain, or the freedesktop Secret Service through `secret-tool` on Linux. On Windows, and on any machine without one, sign in with `obi login --expect-email --storage file` to keep it in an owner-only file instead. The CLI never prints tokens. Local state lives in: | System | Directory | | - | - | | macOS | `~/Library/Application Support/obi-cli` | | Linux | `$XDG_STATE_HOME/obi-cli`, or `~/.local/state/obi-cli` | | Windows | `%LOCALAPPDATA%\obi-cli` | Version 0.1.8 moves the folder and the stored connection an earlier version kept under its former name, on its first run. ## Environment variables | Variable | Effect | | - | - | | `OBI_LANGUAGE` | Language of the terminal welcome (`en` or `fr`); otherwise `LC_ALL`, `LC_MESSAGES`, then `LANG` | | `NO_COLOR` | Plain, uncoloured terminal welcome | | `XDG_STATE_HOME` | Base of the local state directory on any system, when set to an absolute path | The Skill follows the language of your conversation, whatever these variables say. # Obi FAQ Source: https://hireobi.com/docs/faq Short answers about setting up and running Obi: assistants, systems, engines, what counts as a measurement, what stays on your machine, updating and removing the CLI. Questions about the product, pricing, data handling and results are answered on [hireobi.com/faq](https://hireobi.com/faq). This page covers setting up and running Obi. ## Which AI assistants does Obi work with? Claude Code, Cursor and Codex, in the CLI or the desktop app. Obi runs as a Skill inside the assistant: type `/obi` in Claude Code or Cursor, `$obi` in Codex CLI, or pick Obi in the Codex desktop skills picker. See the [quickstart](/docs/quickstart#open-obi-in-your-assistant). ## Which systems does the CLI run on? macOS, Linux and Windows, with Node.js 22 or later. On Windows, sign in with `obi login --expect-email --storage file`: the CLI keeps the connection in a file only your user can read, because it uses no system credential store there. ## Which AI engines does Obi measure? ChatGPT and Gemini on every plan; Google AI Overviews in every paid pack; Claude and Perplexity as paid add-ons. See [How Obi measures AI answers](/docs/how-it-works/scans#engines). ## Is my assistant's answer to a buyer question a measurement? No. Only a scan run by Obi's servers is a measurement: it sends the reviewed questions to the engines your plan covers and keeps each answer, its date and its citations. Your assistant's own answer is a suggestion. ## Does Obi publish anything or spend money on its own? No. Obi recommends and drafts. Every command that starts paid work or approves a review needs an explicit flag, such as `--confirm-scan`, `--confirm-checkout` or `--confirm-change`, and Obi asks for your yes before it runs one. ## What does the CLI keep on my machine? Your connection, in the macOS Keychain, the Linux Secret Service, or an owner-only file with `--storage file`, plus a local state directory. The CLI never prints tokens. See [credentials and local state](/docs/cli/overview#credentials-and-local-state). ## How do I check that the CLI is set up correctly? Run `obi doctor`. It sends no request and prints your Node.js version, the CLI version, the server it talks to, where the connection is stored, and whether the video tools `yt-dlp` and `ffmpeg` are installed. ## How do I update the CLI? ```bash theme={null} npm install --global @hireobi/cli obi --version ``` The Skill links point into the installed package, so they follow the update. Open a new chat in your assistant to load the new Skill. The published versions are listed on [npm](https://www.npmjs.com/package/@hireobi/cli?activeTab=versions). ## How do I see or end the connections of my account? `obi credentials list` shows the live CLI connections you may see, with each device label, CLI version and dates. `obi credentials revoke ` ends one. See [credentials](/docs/cli/commands#credentials). ## How do I remove Obi from a machine? 1. Run `obi logout`. It revokes this machine's connection on the server, then deletes it locally. 2. Remove the Skill links `~/.agents/skills/obi` and `~/.claude/skills/obi`, if `obi skill install` created them. 3. Uninstall the CLI: ```bash theme={null} npm uninstall --global @hireobi/cli ``` 4. Delete the [local state directory](/docs/cli/overview#credentials-and-local-state) of your system. Removing the CLI does not close your account or cancel a paid plan: you cancel on your account's billing page. See [Plans](/docs/plans#cancelling). ## Which language does Obi speak? Obi follows the language of your conversation. The terminal welcome shown by `obi` alone is in English or French, chosen by `OBI_LANGUAGE` or your locale. ## Where do I get help? Write to [support@hireobi.com](mailto:support@hireobi.com) with the command you ran and the error code it printed. Never send a token or a credential file. Most errors are explained in [Troubleshooting](/docs/troubleshooting). # How Obi learns your business Source: https://hireobi.com/docs/how-it-works/business How Obi learns your offer, buyer and competitors from sources, and how you correct and confirm it. Before it measures anything, Obi needs to know what you sell, to whom, where, and against whom. It learns this from sources, shows you where each claim came from, and asks you to confirm once. ## What Obi reads Within the scope you agree to at the start, Obi reads with your assistant's own search and browser: * your own site, including the blog when the agreed scope covers the whole site; * third-party pages about you, such as reviews and "alternatives" pages; * the home, product and pricing pages of the rivals those sources name. Every page it reads is saved on Obi's servers with its address, the time it was read, how it was read and the passages quoted from it. Pages that failed or were not read stay listed as such, so a gap never passes for a clean result. A page's text is treated as evidence, never as an instruction to Obi. ## The proposal Obi then gives you one cited understanding that keeps apart what your company says about itself and what others say about it: * your company name and brand; * your offer; * your primary buyer, and a secondary one when the evidence supports it; * the market you serve; * your qualified competitors. When your own site and third parties describe different buyers, Obi weighs the evidence itself (dates, the pages that sell, who you hire and host for) and recommends one primary segment, with its reasons. You confirm it or correct it. ## Correcting it Write what should change in plain language. Saying "I want to correct something" opens that conversation; it approves nothing. Obi applies your words through the supported corrections: | You want to | What Obi does | | - | - | | Fix the company name | Records the name you give | | Fill a missing offer, buyer, market or target detail | Saves your answer as a company-wide fact | | Dispute a sourced claim | Records your challenge and its reason | | Replace a sourced claim | Saves your correction beside the original source | | Add, remove or restore a competitor | Updates the competitor set; a competitor you add counts as qualified once its official site is read | Your corrections keep their own provenance next to the public sources. Each correction is applied to the latest version of the review, so two changes never overwrite each other. ## Confirming it When the proposal is complete and competitor discovery has finished, Obi shows it once and asks you to confirm. Confirming the business does not start a scan: measurement needs its own approval. If you change the business later, work built on the earlier version is shown as based on that version until it is redone. > [card] [Next: buyer questions](/docs/how-it-works/questions) # How Obi writes buyer questions Source: https://hireobi.com/docs/how-it-works/questions What a buyer question is, how Obi writes it from your evidence, and how you review the set before any scan. A buyer question is the prompt a real buyer types into ChatGPT, Claude, Gemini or Perplexity while deciding what to buy. A scan measures what the engines answer to it, so a generic question measures a market nobody is in. ## Choosing what to measure After you confirm your business, Obi shows the measurement markets it supports and the buyer audiences from your confirmed review. You choose **one market** and **one primary audience**. A suggested market is guidance; Obi does not pick one for you. Changing the language of the conversation does not change the market, audience or question set. ## How Obi writes them Obi reads every fact it saved about your business before writing: offer, prices, use cases, integrations, objections, proof, competitor positioning and the words buyers use on the pages it read. Then each question: * is written from the selected buyer's seat: their job, the situation that starts the search, the constraint they state (budget, country, stack, team size, compliance); * reads like a chat prompt: first person, one ask, 8 to 30 words, a concrete situation, no adjectives copied from marketing pages; * cites the facts it came from. Across the set, the questions cover the stages of buyer awareness, from someone who does not know the category yet to someone choosing between named options, and six intents: category discovery, use case, feature, comparison, alternatives and trust. Most questions do not name your company or a rival. Obi's servers refuse a set where too many questions are branded; comparison and alternatives questions use that allowance. | A search query | A buyer prompt | | - | - | | Best AI gateway? | We are three developers shipping a Django app and need one API for several model providers with EU hosting, what should we use? | ## Reviewing the set Obi shows you five representative questions with the fact each came from, then the full set when you ask. You judge the voice; correct any question in plain language and Obi saves your wording as a new version of the set. Earlier versions stay distinct, and a scan always records which version it measured. If you later correct your business in a way that changes the buyer or market, Obi redrafts against the new review. Questions based on the earlier version stay visibly marked as such until their replacement is accepted. > [card] [Next: scans and engines](/docs/how-it-works/scans) # How Obi checks AI crawler readiness Source: https://hireobi.com/docs/how-it-works/readiness What Obi checks on your website so AI engines can reach and read it, and how to read a finding. Readiness answers a technical question: can the AI engines' crawlers reach your pages, and can they read the facts that matter on them? Obi saves each Readiness report with the evidence behind every finding. ## What Obi checks | Area | What it looks at | | - | - | | Crawler access | Your `robots.txt`, read rule by rule for each AI search and user-fetch crawler and each page checked, with the line that decides | | Indexability | Pages that are unavailable, marked `noindex` or `nosnippet`, restricted from Bing answers, or whose canonical points elsewhere | | Rendering | Material facts that only appear once a browser runs the page's JavaScript, or that change when it does | | Structured data | Whether the pages carry structured data, and whether it names another host | | `llms.txt` | Whether the file exists, is valid, and links to pages that answer | | Coverage | How pages were discovered (sitemap or links), how many were checked, and important pages nothing links to | Blocking a training crawler, such as GPTBot or Google-Extended, is reported as your preference, not as a defect. Obi separates the crawlers that power AI search and live answers from those that only collect training data. ## Reading a finding Each finding carries: * **a state:** pass, fail, unknown or not applicable; * **a severity:** blocker, major, minor or info; * **a confidence:** high, medium or low; * **its evidence:** the address, the time it was observed, how it was fetched, and the quoted lines; * **an explanation:** what was observed, what it costs you, how to correct it and how to verify the correction. When a `robots.txt` rule is the cause, the finding can include a patch with the exact diff and the number of intended and unintended changes across the pages compared. A check that could not run is reported as not run, with its reason. A blocked page or an incomplete check is unresolved, never a clean result. ## Where it fits Obi reads Readiness while it studies your business, and uses its findings when it ranks your priorities. Ask Obi for your Readiness report at any time, or run `obi readiness`: reading the saved report never starts a new reading. > [card] [Next: strategies and outcomes](/docs/how-it-works/strategies) # How Obi measures AI answers Source: https://hireobi.com/docs/how-it-works/scans How Obi's servers measure what the AI engines answer to your buyer questions, and what a scan keeps. A scan sends your reviewed buyer questions to the AI engines your plan covers and keeps what each engine answered. It runs on Obi's servers, not in your assistant, and it is the only thing Obi calls a measurement. ## Engines | Engine | Free plan | Paid plan | | - | - | - | | ChatGPT | Included | Included in every pack | | Gemini | Included | Included in every pack | | Google AI Overviews | Not included | Included in every pack | | Claude | Not included | Optional, per pack | | Perplexity | Not included | Optional, per pack | Claude and Perplexity measure a subset you choose: up to 10 genuine buying questions per pack, never padded to reach that number. A question measured on ChatGPT is not necessarily measured on every optional engine. See [Plans](/docs/plans). ## Starting a scan Before a scan, Obi shows you the question version it will measure, the engines, and the number of question-and-engine cells. It asks you once, and only an explicit yes starts the scan. If the request times out, Obi reads the current state before trying again, so a paid scan is never sent twice. ## Cadence * **Free:** one scan a month. * **Paid:** one scan a week. ## What a scan keeps Each scan freezes, at its start, the question version and wording, the engines it covers and its server budget. Correcting a question or your business afterwards applies to future scans; it never rewrites a scan already started and never adds a second scan to a week that already has one. The results hold, for each question and engine: * the answer the engine gave; * when it was measured; * the sources the engine cited. Obi shows completed and missing cells plainly. An older scan keeps its own date and question version, and Obi never presents it as fresh research. > [card] [Next: website readiness](/docs/how-it-works/readiness) # How Obi ranks what to do next Source: https://hireobi.com/docs/how-it-works/strategies How Obi turns measured gaps into three priorities, and how it records what you actually implemented. After a scan, Obi reasons over everything it knows about your business and saves ranked priorities: what to start this week, and why. ## How Obi ranks Obi compares the gaps the scan measured with your saved business facts, the pages it read from you, your rivals and the media the engines cited, your Readiness findings and your feedback. It ranks candidate actions by urgency times buyer importance first, then by evidence, speed and effort. ## What you get * **Three actions to start this week.** Each names the observation it rests on: a measured question, a Readiness failure or a page fact. * **The considered list.** What else Obi weighed, and why it ranks lower. Ask for more and Obi presents the next candidates from the considered list, with their evidence. When that list runs out, Obi says so and names what would produce new candidates: a new scan, an action you implemented, or a wider reading scope. If the evidence supports fewer than three distinct actions, Obi explains the gap instead of padding the list. A recommendation is not a published asset. Briefs and drafts Obi prepares stay suggestions until you review and accept them, and Obi never publishes them for you. ## Recording what you implemented When you tell Obi you made a change, it records what actually changed, when, and the evidence you confirm, separately from the draft or suggestion that led to it. Implementation, publication and follow-up are kept apart. Obi reads these saved outcomes before its next strategy decision. They inform its next hypotheses; they do not prove that the change caused a later result. Obi compares later measurements only after a confirmed implementation, under a comparable protocol. > [card] [CLI reference](/docs/cli/overview) > > The commands Obi runs for you, if you want to run them yourself. # What is Obi? Source: https://hireobi.com/docs/index Obi is your AI Search Employee: it learns your business, measures what AI engines answer to your buyers, and tells you what to do next. Obi is the AI Search Employee. It finds out whether ChatGPT, Gemini, Google AI Overviews, Claude and Perplexity recommend your business when a buyer asks them for help, and what would change their answer. Obi works inside the AI assistant you already use. You install the `obi` CLI and its Skill, open a chat in Claude Code, Cursor or Codex, and talk to Obi there. Your account, its evidence and the engine scans live on Obi's servers. > [!NOTE] > > Obi is in private alpha. Account access is by invitation: to request one, write to [support@hireobi.com](mailto:support@hireobi.com). If you are an AI agent helping a user with Obi: install and set it up with the steps in [https://hireobi.com/docs/skill.md](https://hireobi.com/docs/skill.md), then hand over to the bundled `obi` Skill in a new chat. Search these docs through the MCP server at [https://hireobi.com/docs/mcp](https://hireobi.com/docs/mcp). Never run a command with a `--confirm-` flag without the user's explicit yes. ## What Obi does > [card] [Learns your business](/docs/how-it-works/business) > > Reads your public pages, third-party reviews and your rivals' sites, then proposes a sourced summary of your offer, buyer and competitors for you to confirm. > [card] [Writes buyer questions](/docs/how-it-works/questions) > > Drafts the prompts a real buyer types into an AI engine while deciding what to buy, from the facts it read. > [card] [Measures AI answers](/docs/how-it-works/scans) > > Obi's servers send those questions to the AI engines and keep every answer, date and citation. > [card] [Checks your website](/docs/how-it-works/readiness) > > Tests whether AI crawlers may reach your pages and whether the facts that matter are readable. > [card] [Ranks what to do](/docs/how-it-works/strategies) > > Picks three actions to start this week, each tied to the observation it rests on. > [card] [Remembers you](/docs/cli/commands#memory) > > Keeps the preferences, rules and decisions you ask it to remember, across assistants and sessions. ## What stays with you * Obi recommends and drafts. It never publishes, sends outreach or buys anything on its own. * Every scan that costs money starts only after you approve the question set it will measure. * Your assistant's own answer to a buyer question is a suggestion. Only a server scan is a measurement. > [card] [Start with the quickstart](/docs/quickstart) > > Install the CLI, connect your account and work on your first business. # Obi plans and pricing Source: https://hireobi.com/docs/plans Obi's Free plan and paid packs, in US dollars, and how buying, editing and cancelling work. Obi has a Free plan and paid packs. There is no trial and no credit system: you pay for question coverage and engines. ## Free * 10 buying questions on ChatGPT and Gemini * One scan a month, with three priorities * No card Obi activates the Free plan on an eligible account when you start your first business. An account that already has older coverage or scan work keeps it instead. ## Paid packs | | Price per pack | Coverage per pack | | - | - | - | | **Core pack** | \$20 / month | 25 reviewed buyer questions on ChatGPT, Gemini and Google AI Overviews, scanned every week | | **Claude** | + \$20 / month | Up to 10 genuine, distinct buying questions from the pack, also measured on Claude | | **Perplexity** | + \$10 / month | Up to 10 genuine, distinct buying questions from the pack, also measured on Perplexity | You choose a number of packs, from 1 to 40, and whether to add Claude, Perplexity or both. The add-ons apply to every pack you buy: **Monthly price = packs × ($20 + $20 if Claude + \$10 if Perplexity)** | Example | Monthly price | | - | - | | 1 pack | \$20 | | 1 pack with Claude and Perplexity | \$50 | | 2 packs with Perplexity | \$60 | The Claude and Perplexity subsets are never filled to quota: Obi selects only genuine buying questions. ## Buying You buy or change packs in your assistant, where Obi reviews the questions each pack will measure. Obi prepares a quote for the reviewed questions; after your explicit confirmation, it opens the checkout page in your browser. A paid plan is scanned every week. A plan gives Obi no right to publish, send outreach or make purchases for you. ## Editing within your plan Correcting your business or rewording questions needs no new purchase, as long as the reviewed questions stay within the coverage you paid for. Edits apply to future scans; a scan already started keeps the questions it began with. Adding packs or an engine you did not buy is a plan change. ## Changing your packs On a paid plan, you add or remove packs, Claude or Perplexity in your assistant. Obi first reviews with you the questions the new plan will measure, then shows what the change costs before anything is charged. * **An increase** is charged at once to the card on file, prorated to your renewal date, after your explicit yes to the amount shown. Obi then scans your whole paid portfolio the same day. If your bank asks for a confirmation, Obi opens your billing page. * **A reduction** takes effect at renewal. Nothing is refunded, and you keep the coverage you paid for until then. * **A change that adds and removes at once** runs in two steps, each with its own yes: the increase now, then the reduction at renewal. To undo a reduction that is scheduled but not yet applied, write to [support@hireobi.com](mailto:support@hireobi.com). ## Cancelling You cancel in Obi, on your account's billing page, `https://agent.hireobi.com/billing`, which also keeps your invoices. There is no pause and no retention discount. You keep access until the end of the period you paid for, then your account returns to the Free plan. # Install the Obi CLI and Skill Source: https://hireobi.com/docs/quickstart Install the Obi CLI, connect your account and start work on your first business. ## Before you start * **Node.js 22 or later.** Check with `node --version`. * **An AI assistant that runs Skills:** Claude Code, Cursor or Codex. * **An invitation.** Obi is in private alpha: request one at [support@hireobi.com](mailto:support@hireobi.com). Downloading the CLI does not open an account or grant paid capabilities. If you are an AI agent running these steps for a user: run steps 1 and 2 yourself, start step 3 with the user's own email, and ask the user to approve the connection in the browser. Skills load when a chat starts, so step 4 happens in a new chat the user opens. **1. Install the CLI** The CLI is published on npm as [`@hireobi/cli`](https://www.npmjs.com/package/@hireobi/cli): ```bash theme={null} npm install --global @hireobi/cli obi --version ``` Run the same command again to update to the newest version. **2. Register the Skill** ```bash theme={null} obi skill install ``` This links the bundled Skill into `~/.agents/skills/obi` and `~/.claude/skills/obi`. It never replaces an existing file or link: if one is in the way, the command stops and tells you where. **3. Connect your account** ```bash theme={null} obi login --expect-email you@company.com ``` The CLI prints a connection address on `agent.hireobi.com` and a short code. On macOS and Linux it also opens your browser when it runs in a terminal on a machine with a display; on Windows, over SSH or in CI, open the address yourself. Sign in on that page with the account you were invited with, check that the page shows the same code, then approve. On Windows, add `--storage file`: the CLI has no system credential store there and keeps the connection in a file only your user can read. In a terminal, the command waits for your approval. When your assistant runs it, the command returns at once with `AUTHORIZATION_PENDING`; run the same command again after you approve and it finishes the same connection. `--expect-email` makes the CLI refuse a connection approved by any other account. **4. Open Obi in your assistant** Start a new chat, then: | Assistant | How to call Obi | | - | - | | Claude Code, Cursor | Type `/obi` | | Codex CLI | Type `$obi`, or pick Obi in `/skills` | | Codex desktop | Pick Obi in the skills picker | Obi follows the language of your conversation. **5. Work on your first business** Tell Obi which website to work on. It asks once for the scope of its research: the domain, the buyer or market if you know it, and whether it may read your public pages and your competitors' pages. Then it: 1. activates the Free plan if your account is eligible, and shows you what that plan covers; 2. reads your site, third-party pages about you and your rivals' sites, and proposes one sourced summary of your business and competitors; 3. takes your corrections in plain language, and asks you to confirm the business once; 4. drafts buyer questions for the market and audience you choose; 5. asks for your explicit go before the scan that measures them; 6. shows the measured answers and three priorities to start this week. Running `obi` alone in a terminal shows a short welcome and exits: the conversation happens in your assistant. `obi --help` lists every command; see the [CLI reference](/docs/cli/overview). # Troubleshoot the Obi CLI Source: https://hireobi.com/docs/troubleshooting What the obi CLI's common errors mean and what to do about each. Every error the CLI prints carries a code and the next action to take. With `--json`, they are in `error.code` and `error.nextAction`; the [exit code](/docs/cli/overview#exit-codes) tells you the family. Still stuck? Write to [support@hireobi.com](mailto:support@hireobi.com) with the command you ran and the error code. Never send a token or a credential file. ## Installing > [accordion] The install fails or obi refuses to start > > The CLI needs Node.js 22 or later. Check with `node --version`, upgrade Node.js, then install again. > [accordion] SKILL\_INSTALL\_FAILED: a Skill entry already exists > > `obi skill install` found a file or link at `~/.agents/skills/obi` or `~/.claude/skills/obi` that it did not create. It never replaces one. Move or remove that entry yourself, then run the command again. > [accordion] /obi does not appear in my assistant > > Skills load when a chat starts. Run `obi skill install`, then open a **new** chat. `obi skill path` shows where the bundled Skill is. ## Signing in > [accordion] AUTH\_REQUIRED: this machine is not signed in > > Run `obi login --expect-email `. > [accordion] AUTHORIZATION\_PENDING > > The connection waits for your approval in the browser. Open the address the CLI printed, check that the page shows the same code, approve, then run the same `obi login` command again: it resumes the same connection. > [accordion] The browser did not open > > The CLI opens a browser only on macOS or Linux, in a terminal on a machine with a display; never on Windows, over SSH or in CI. Open the printed address yourself, on any device, and compare the code before you approve. > [accordion] ACCOUNT\_MISMATCH or ACCESS\_DENIED > > The connection was approved by another account than the one you expected, or denied in the browser. Nothing was stored. Run `obi login` again and approve it with your own account. > [accordion] EMAIL\_NOT\_VERIFIED or ACCOUNT\_SETUP\_REQUIRED > > Verify your email from the message Obi sent, or finish the account setup in the browser, then run `obi status`. > [accordion] STORAGE\_UNAVAILABLE: no system credential store > > The macOS Keychain or the Linux Secret Service is missing, locked or refused the operation, or you are on Windows, where the CLI uses none. Unlock it, or sign in with `obi login --expect-email --storage file` to keep the connection in a file only your user can read. > [accordion] STORAGE\_INSECURE > > The local state directory or one of its files can be read by other users, is a link, or belongs to another user. Restrict the directory to your user (mode 700) and its files (mode 600). The [state directory](/docs/cli/overview#credentials-and-local-state) depends on your system. > [accordion] STORAGE\_INVALID: the stored connection cannot be read > > Run `obi logout`, then `obi login --expect-email `. ## Working with Obi > [accordion] OWNER\_REQUIRED > > Only the account owner can do this, for example start the reading of your website or a purchase. Ask the owner. > [accordion] A command timed out after a change > > A timeout does not prove the change failed. Read the current state first (`obi status`, `obi business show`, `obi questions show` or `obi harness purchase status`), then retry only if the change is not there. Obi does this for you in the chat. > [accordion] HARNESS\_REQUIRED or HARNESS\_QUESTIONS\_REQUIRED > > The command asked Obi's servers to read your website or prepare your questions, and on your account your assistant does that work. Ask Obi in your assistant: the Skill reads the work with `obi harness show --stage business` or `--stage questions` and saves the result with `obi harness submit`. > [accordion] HARNESS\_WORK\_CONFLICT or a stale review > > The review or the scan changed after the result was prepared. Obi reads the current work and prepares the result again. > [accordion] SCAN\_BUDGET\_NOT\_AUTHORIZED > > The scan you asked for is not fully authorized for your plan's coverage. Editing a question does not fix it. Ask Obi to show your coverage with `obi harness coverage`. ## Network and updates > [accordion] NETWORK\_UNAVAILABLE, REQUEST\_TIMED\_OUT, SERVICE\_UNAVAILABLE or RATE\_LIMITED > > Check your network connection and try again later. A rate limit tells you how long to wait when the server says so. > [accordion] REQUEST\_FAILED > > The server refused the request with a reason this CLI version does not know. Retrying will not help: update the CLI with `npm install --global @hireobi/cli`, then try again. > [accordion] INVALID\_RESPONSE or exit code 7 > > The server answered in a form this CLI version does not know. Update the CLI with `npm install --global @hireobi/cli`, then try again. > [accordion] INVALID\_ORIGIN or a warning about a development server > > A development variable is set: the error names it. `OBI_ORIGIN` exists for Obi development and only accepts a local address; a variable an older version read is refused. Unset it to reach your account.