# ByteAsk: setup guide for coding agents

You are a coding agent (Claude Code, Codex, Cursor or similar) and your user asked you to set up ByteAsk (https://byteask.ai). This guide is written for you. Read all of it, then follow "Your job, in order". Do the setup yourself: ask the user one message of direct questions, then install, sign in and verify without asking again. Ask again only before something that costs money (a Cloud Agent task, CLI turns, a plan change). Use as few commands as you can, because the user may have to approve each one in your agent.

## What ByteAsk is

ByteAsk makes tools for software engineers, deepest for C and C++. Three products:
- Context: code intelligence for the coding agent you already use. C and C++ come from the project's real build (compile_commands.json); every other language (Python, TypeScript, JavaScript, Go, Java, Kotlin, C#, Rust, Ruby, PHP, Swift, CUDA and more) from its source files, with no build. It answers where a change most likely belongs, with the code, and gives the code and callers of named functions. It is an MCP server, https://context.byteask.ai/mcp, plus, for Claude Code and Codex, a small hook that asks it before the agent's first step.
- Cloud Agent: mention @ByteAsk in Slack or Jira; it works on the task in a cloud sandbox with the repository's build and tests and opens a tested draft pull request.
- ByteAsk CLI: a terminal coding agent with ByteAsk's C/C++ tools (debugger, sanitizers, profilers) and models through ByteAsk's gateway.
One ByteAsk account (one email address) and one plan cover all three.

## Your job, in order

1. Detect what is here: one read-only command, nothing installed.
2. Ask the user one message: which products, plus only the facts you need. Their reply is the go-ahead for steps 4 to 6.
3. (Reference) Plans and prices, for answering questions. Setup itself costs $0.
4. Install: one command downloads the script, checks its SHA-256, installs and starts the sign-in. No dry run unless the user asks for one.
5. Sign in: show the user the link and code, then wait for the approval.
6. Verify, then tell the user in a few lines what is done and the one or two things only they can do.

## 1. Detect (one read-only command)

You know which agent you are (Claude Code, Codex, Cursor or another MCP client). Run this once; it changes nothing:

  { uname -s; echo "shell=$SHELL"; for c in curl python3 claude codex byteask; do printf '%s=' "$c"; command -v "$c" || echo missing; done; python3 -c 'import sys; print("python3.8+", sys.version_info >= (3, 8))'; claude mcp get byteask 2>/dev/null | head -n 4; ls -d ~/.byteask/context ~/.byteask 2>/dev/null; echo "repo=$(git rev-parse --show-toplevel 2>/dev/null)"; git ls-files '*.c' '*.cc' '*.cpp' '*.h' '*.hpp' '*.py' '*.ts' '*.js' '*.go' '*.java' '*.rs' '*.rb' '*.cs' 2>/dev/null | head -n 3; ls compile_commands.json build/compile_commands.json 2>/dev/null; } 2>&1

- The script is POSIX sh for Linux and macOS. On Windows, use WSL; native Windows is not covered by this guide yet. Context needs curl and Python 3.8 or newer.
- If ByteAsk is already there (fully or partly, including a setup from ByteAsk's older copy-paste prompt), the install below upgrades it in place; it is idempotent. Never make a second copy.
- Context works in any git repository with code, with or without a remote (without one, ByteAsk names it by its first commit; Perforce and SVN workspaces are not supported). For C and C++, a compile_commands.json lets ByteAsk index the real build (CMake: -DCMAKE_EXPORT_COMPILE_COMMANDS=ON; make: bear -- make); without one, and for every other language, it indexes the code files themselves. Note what you find for step 6. It does not change the setup: Context is installed for all projects.

## 2. Ask the user (one message, then go)

Send one short message with direct questions and the defaults marked, close to this (do not add a summary of what you found, a list of planned changes or a cost section):

  I'll set up ByteAsk for you. Reply "go" for the defaults, or change any answer:
  1. Products: Context in <this agent> [yes] · Cloud Agent, tasks from Slack or Jira that open draft pull requests [no] · ByteAsk CLI, a terminal agent, about 100 MB [no]
  2. May ByteAsk index your repositories without asking each time? [no]
  3. (only if the CLI is chosen) Your ByteAsk account email?
  Setup is free (Free plan: $5 a month of usage credit, no card). In a git repository with code, Context sends each request you type and the repository's remote address (or, without a remote, its first commit's id) to ByteAsk; no code is uploaded until you approve indexing.

Add the line "(the CLI may ask for sudo to install bubblewrap and ripgrep)" only on Linux when the CLI is chosen. The reply is consent for steps 4 to 6: install, sign in and verify without asking again and without showing a dry run. If the user asks to see the changes first, download and check the script as in step 4, run only `sh install.sh install ... --dry-run`, show the output, then run the step 4 command.

## 3. Plans and prices (reference)

Setup costs nothing: Context, the CLI and the Cloud Agent connection are free to install. Context lookups and indexing are included within the plan's bands. What can cost money later is use: CLI turns and Cloud Agent tasks draw usage credit (Free includes $5 a month, no card). Never start a Cloud Agent task or another paid step without the user's yes.

One plan for everything. The plan belongs to a workspace (a person or a GitHub organization). No per-seat charge, up to 50 members (Enterprise unlimited). The plan fee is all usage credit: one credit pays for every metered thing in every product. Context is not metered; it is bounded by the bands below. Slack and Jira are on every plan, Free included.

| | Free | Pro | Max | Ultra | Enterprise |
|---|---|---|---|---|---|
| Price | $0 | $20/mo | $100/mo | $200/mo | Custom (talk to us) |
| Annual | | 2 months free | 2 months free | 2 months free | contract |
| Usage credit / month | $5 (resets monthly, no card) | $20 | $100 | $200 | committed |
| Members | 50 | 50 | 50 | 50 | unlimited |
| Cloud Agent tasks at once | 1 | 1 | 2 | 4, priority queue | dedicated runners |
| Cloud Agent repos | 1 | 3 | 10 | 25 | unlimited |
| Slack / Jira / app / MCP tools | yes | yes | yes | yes | yes |
| Context private repos / lines / storage | 1 / 100k / 2 GB | 3 / 1M / 10 GB | 10 / 5M / 50 GB | 25 / 20M / 200 GB | custom |
| Context public repos | free | free | free | free | free |
| CLI | all models on credit | same | same | same | + BYOK, on-prem gateway |
| Path access rules | yes | yes | yes | yes | + audit export |
| SSO | GitHub / email | same | same | same | SAML, SCIM |
| Out of credit | stops; top-up | top-ups ($10 min, 12-month expiry) or auto-top-up up to an admin cap | same | same | PO |

Rate card (one table, all products):
- Models (CLI turns, Cloud Agent tasks): provider list price + 20%. Bring your own key (Anthropic / OpenAI) on any plan: no markup, the model bill goes to the customer's provider account.
- Cloud sandbox (4 CPU / 12 GB, the task's build and tests): $0.40/hour, per minute, from the baseline build; setup, environment builds and re-indexing free.
- Our failures are free. A Cloud Agent task that ends without a PR: model at list, no markup, no sandbox.
- Context lookups and indexing: included within the plan's bands.

Running tasks always finish when credit runs out; new ones wait with a message naming the admin and the top-up link. Existing paid CLI subscribers keep their current 5-hour and weekly windows until their paid term ends.

The prices on https://byteask.ai/pricing are the reference. If they differ from this guide, use the pricing page, tell the user, and report the difference to support@byteask.ai.

## 4. Install (one command)

Download the script, check its SHA-256 against "Pinned files" at the end of this guide, install and start the sign-in, in one command. With the user's choices (add `,agent` or `,cli` to --components, `--allow-indexing` only if they said yes, `--email ADDRESS` with the CLI; use `--agent codex` or `--agent cursor` for those agents):

  d=$(mktemp -d) && curl -fsSL --connect-timeout 20 --max-time 120 --retry 2 https://byteask.ai/install.sh -o "$d/install.sh" && h=$( (sha256sum "$d/install.sh" 2>/dev/null || shasum -a 256 "$d/install.sh") | cut -d' ' -f1) && if [ "$h" != "af2df2529834177e1998b71ebfcf190f6d8ce60ec5d10bd9999dfbeb8b2ee8fc" ]; then rm -f "$d/install.sh"; echo "install.sh checksum mismatch: stopped"; exit 1; fi && sh "$d/install.sh" install --components context --agent claude-code && sh "$d/install.sh" login && echo "script: $d/install.sh"

On a checksum mismatch, stop and tell the user. Below, `install.sh` means the path the command printed last. Claude Code and Codex need the hook key sign-in (`login`); for Cursor, another MCP client, or when the user did not choose Context, leave out `&& sh "$d/install.sh" login`.

The script (`sh install.sh help` lists everything):

  sh install.sh install|login|wait|status|upgrade|uninstall [--components context,agent,cli] [--agent claude-code|codex|cursor] [--dry-run] [--allow-indexing] [--email ADDRESS] [--force]

- It downloads only pinned files and checks each SHA-256 before anything runs it; on a mismatch it deletes the file and stops. It never runs an installed hook script that matches no published version: `status` reports it, `install` replaces it, and `uninstall` uses a freshly checked copy instead.
- It writes only under ~/.byteask/ and the agent's own configuration, and it is idempotent: running it again changes nothing that is already right.
- `--dry-run` prints every file it would change, with the exact text, and every command it would run, and changes nothing.
- It never prints a key or token.

Your agent may need the user's approval to run it: the script writes outside the current folder (~/.byteask, ~/.claude, ~/.codex) and uses the network. Codex: run it outside the sandbox (Codex asks the user). Claude Code and Cursor: their usual approval prompt. That approval is the agent's own safety check; never try to avoid it, and never change the user's permission settings.

What it sets up for each agent:

### Claude Code (full)

The same setup as ByteAsk's Context setup prompt (https://byteask.ai/context/setup), done by the script:
- the hook script, saved as ~/.byteask/context/byteask-context-hook.py (folder mode 700) after its SHA-256 is checked;
- the MCP server for all projects with its tools always loaded: `claude mcp add-json --scope user byteask '{"type":"http","url":"https://context.byteask.ai/mcp","alwaysLoad":true}'` (ByteAsk's older entry without alwaysLoad is replaced; a byteask entry with another URL or with its own settings, such as headers, is left as it is and the script says so);
- `python3 ~/.byteask/context/byteask-context-hook.py install`, which registers two hooks in ~/.claude/settings.json (UserPromptSubmit: asks find_code_for_task before Claude's first step; SessionStart: one line naming the repository) and puts the instruction block (below) in ~/.claude/CLAUDE.md, between <!-- byteask:start --> and <!-- byteask:end -->. It backs both files up first.
After sign-in (step 5), the user restarts Claude Code (exit, then run claude), types /mcp, selects byteask, chooses Authenticate and allows it in the browser.

### Codex (full)

Tested with Codex CLI 0.167.0, which reads hooks in the same format as Claude Code:
- the same hook script in ~/.byteask/context/;
- the MCP server (Streamable HTTP) as a block at the end of ~/.codex/config.toml, between "# BEGIN ByteAsk" and "# END ByteAsk":
    [mcp_servers.byteask]
    url = "https://context.byteask.ai/mcp"
  If config.toml already has an mcp_servers.byteask entry the script did not write, it leaves it as it is and says so. With Python 3.8 to 3.10 (no TOML parser), a config.toml that defines mcp_servers inline (`mcp_servers = { ... }`) stops the install with nothing changed: add the block by hand, or run the script with Python 3.11 or newer.
- the same two hooks in ~/.codex/hooks.json (other hooks stay where they are). Codex runs hooks only after the user trusts them: when Codex starts it shows "Hooks need review"; choose Review hooks and trust the two ByteAsk hooks (their command ends in byteask-context-hook.py). Untrusted, they do not run, and the instruction block still tells Codex to call find_code_for_task first.
- the instruction block (below) in ~/.codex/AGENTS.md, or in ~/.codex/AGENTS.override.md when that file has text, because Codex then reads only that one.
After sign-in (step 5), the user runs `codex mcp login byteask` in a terminal (it opens the browser), then restarts Codex and trusts the hooks.

### Cursor (basic)

- the MCP server in ~/.cursor/mcp.json: "byteask": {"url": "https://context.byteask.ai/mcp"} (other servers stay; a byteask entry that is already there is left as it is);
- the instruction text, printed for the user to paste into Cursor Settings > Rules > User Rules. Cursor keeps those rules in its settings, not in a file, so the script does not change them.
- no hook and no hook key. The user signs in from Cursor Settings > MCP (find byteask, sign in, allow it in the browser).

### Other MCP clients (basic, by hand)

For any other client with remote MCP support (Windsurf or Devin Desktop, VS Code, Zed, JetBrains and others) the script does nothing. With the user, add a remote MCP server named byteask with the URL https://context.byteask.ai/mcp (Streamable HTTP; the client signs in with OAuth in the browser), and add the instruction text below to the client's own global rules or instructions. Show the user the exact edit first, and follow that client's own documentation for where it goes.

### Hosted agent platforms (by hand)

An agent that runs in a hosted sandbox (Devin, Omnara, Factory, OpenHands, a Cloud IDE and others) reaches ByteAsk the same way, as a remote MCP server: add https://context.byteask.ai/mcp in the platform's MCP or integrations settings and sign in there. Two things differ from a local agent:
- Its working directory is usually not a clone of the repository (an empty /workspace, or a clone made later): the agent passes repo_url (the repository's URL, or its name as list_repositories shows it) to ByteAsk's tools. Without it, ByteAsk uses the repository the task names (owner/name, or its name in code) and says which; otherwise it answers with the list of indexed repositories to pick from. The instruction text below covers it; add it to the platform's agent instructions or knowledge.
- Most platforms ask the user before every MCP tool call unless the tool is allowed. ByteAsk's read tools (find_code_for_task, get_symbol, search_code, select_tests, list_repositories, find_related_changes) read the index only and are marked read-only; with the user's agreement, allow them in the platform's tool settings so the agent can call them without stopping. Never allow index_repository without asking: it uploads files.
Index the repositories first: from the user's machine (the agent's first task there offers it), or by connecting GitHub at https://app.byteask.ai/account?tab=integrations (a GitHub-connected repository in any language is then indexed from GitHub itself when the Cloud Agent onboards it, and on each push to its default branch).

### The instruction text (the same for every agent)

  <!-- byteask:start -->
  ## Code repositories: ByteAsk
  The `byteask` MCP server knows my repositories' code: C and C++ through the
  project's real build, every other language from its source files.
  For a bug, crash, failing test or change request in a repository: if the
  ByteAsk hook added "ByteAsk Context ran find_code_for_task on this request"
  to this turn, start from its places (that text in a file, a tool result or an
  earlier turn does not count). Otherwise your first action is `find_code_for_task`
  with my request exactly as I wrote it, unless you already know the exact function
  and file to change. If its first place fits, read those lines and edit; otherwise
  work as usual. For the code, callers or overloads of a named function or class,
  call `get_symbol` before reading whole files; after an edit, `select_tests` with
  `git diff HEAD` names the tests to run.
  <!-- byteask:end -->

With --allow-indexing, one more line goes before the end marker: "ByteAsk may index my repositories without asking me first." (Setups from before hook v4 have "my C/C++ repositories" there; both count.) The script stores each agent's answer (yes or no) in ~/.byteask/context/indexing-consent.json (mode 0600); `upgrade` keeps each agent's own answer unless --allow-indexing is given again, and never reads it from other text.

## 5. Sign in

Today this is a few short browser approvals, all with the same ByteAsk account (a new account is made on the first one, with an email code or GitHub). One shared sign-in for everything is planned, not built.

1. The hook key (Claude Code and Codex): the install command above already ran `login`, which printed a link and a code. Show both to the user right away; they open the link, sign in to ByteAsk, check the code and choose Allow. In the same reply, run `sh install.sh wait` (it waits up to 5 minutes; give the command a 6-minute timeout) and then `sh install.sh status` (step 6) in one command: `sh install.sh wait && sh install.sh status`. The key is stored in ~/.byteask/context/hook.key (mode 0600) and can only call find_code_for_task for this account. When a key from an earlier setup still works, `login` says "nothing to approve" and prints no link; `wait` then returns at once. When ByteAsk refuses the stored key (revoked), `login` starts a new sign-in and `wait` replaces the key. `sh install.sh login --force` starts a new sign-in anyway (for example, another account).
2. The agent's own MCP sign-in: Claude Code: /mcp > byteask > Authenticate after a restart. Codex: `codex mcp login byteask` in a terminal. Cursor: its MCP settings.
3. The CLI, if chosen: `sh install.sh login --components cli --email ADDRESS`. ByteAsk emails a sign-in link; the command waits up to 10 minutes for the click (give it an 11-minute timeout). Tell the user to check their inbox in the same message, and run it without waiting for a reply.

## Cloud Agent (only if the user chose it)

Nothing is installed on this machine. Three steps need the browser, because they are ByteAsk's sign-in or other companies' consent pages: the ByteAsk sign-in approval, the GitHub App install (https://github.com/apps/byteask/installations/new, where the repositories are chosen; a GitHub organization admin approves it), and Slack's Allow page or Jira's site-admin install (both started from https://app.byteask.ai/account?tab=integrations).

1. Set up Context first and make sure its MCP server is registered and authenticated in this agent (step 5, item 2): it is the channel for the Cloud Agent tools.
2. If your tools include the byteask tool `cloud_setup_status`, call it. It returns what is connected and the exact links still needed. If you do not have that tool, send the user to https://app.byteask.ai/welcome (a guided setup in the browser) and go to point 5.
3. Show the user one missing link at a time. Wait until they say it is done, then call `cloud_setup_status` again. Repeat until nothing is missing.
4. In Slack, the first @ByteAsk in a channel asks which repository that channel uses (with buttons), so no dashboard step is needed.
5. Offer the first task. Either in Slack: "@ByteAsk <request>". Or, if your tools include `cloud_task_preview` and `cloud_task_start`: call `cloud_task_preview` with the repository and the request, show the user the preview (what will happen, the estimated cost, plan limits left), and only after their yes call `cloud_task_start` with its confirm_token. The client asks the user to approve the start; never add that tool to an allow-list.

A task draws usage credit: models at list price + 20% (or the user's own key, no markup) and the sandbox at $0.40/hour. `sh install.sh install --components agent` only prints these links.

## ByteAsk CLI (only if the user chose it)

`--components cli` runs today's CLI installer, https://code.byteask.ai/install.sh, after checking its pinned SHA-256. That installer, not this script, then downloads the engine (about 100 MB, from GitHub Releases, checked against the release's SHA256SUMS), saves the `byteask` launcher and engine in ~/.local/bin or /usr/local/bin (the script records which, so `login`, `status` and `uninstall` find it even when that folder is not on PATH), writes its files in ~/.byteask, adds a block to ~/.gdbinit that defines the byteask-bridge gdb command, and on Linux may try to install bubblewrap and ripgrep with sudo. On Linux it may ask for sudo; the step 2 message already said so. Then sign in (step 5, item 3). The user runs `byteask` in a terminal; its turns use usage credit (or their own provider key: `byteask byok set`).

## 6. Verify

`sh install.sh status` reports each component without printing secrets: the Context server reachable, the hook script matching its pinned SHA-256, for each agent its MCP entry, hooks and instruction block, the hook key and its connection ("connection: ok"), and the CLI installed and signed in. For Claude Code it includes `claude mcp get byteask`, which shows whether /mcp Authenticate is done. For Codex, `codex mcp list` shows the Auth column ("Not logged in" until `codex mcp login byteask`). For the Cloud Agent: `cloud_setup_status` if you have it, otherwise https://app.byteask.ai.

## Next steps to show the user (end of step 6, a few lines)

- Restart the agent and finish its MCP sign-in (step 5, item 2). Codex: trust the two ByteAsk hooks.
- First task: open the agent in a git repository with code and describe a real bug or change in your own words. The first time, the agent offers to index the repository: it downloads ByteAsk's collect script, shows which files would be uploaded (for C/C++ with a compile_commands.json, the files the build reads; otherwise the repository's code files), and uploads only after the user agrees.
- Cloud Agent: the first task in Slack ("@ByteAsk <request>") or through cloud_task_preview and cloud_task_start, as above.
- Check any time: `sh install.sh status`. Setup guide: https://byteask.ai/context/setup. Security: https://trust.byteask.ai.
- Remove everything: `sh install.sh uninstall` (below).

Tell the user, too, what leaves their machine:
- In a git repository with code, the hook sends each request the user types (40 characters or more) and the repository's remote address (or, without a remote, its first commit's id) to ByteAsk, before the agent starts, and adds ByteAsk's answer to the agent's context. Anywhere else it sends nothing. It never blocks the agent: after 15 seconds, or on any error, it adds nothing.
- No code is uploaded until the user approves indexing a repository. Indexing uploads that repository's source files to ByteAsk to build its index (never dependency or build-output folders, lock files, .env or key files).
- To rank where a change belongs, ByteAsk sends short excerpts of candidate code to a model provider (OpenAI) through its API.

## Uninstall

`sh install.sh uninstall --dry-run`, show the user, then without --dry-run. It removes only what install added (a byteask MCP entry with another URL or its own settings stays):
- Claude Code: `claude mcp remove --scope user byteask`, then the hook's own uninstall (revokes the hook key, removes its two hooks from ~/.claude/settings.json and its block from ~/.claude/CLAUDE.md).
- Codex: the marked block in ~/.codex/config.toml, the two ByteAsk hooks in ~/.codex/hooks.json and the block in AGENTS.md.
- Cursor: the byteask entry in ~/.cursor/mcp.json (the User Rules text the user removes by hand).
- Then ~/.byteask/context, once no agent uses the hook any more. `--agent` limits it to one agent.
- Once no agent has Context any more: the collect script's edit-sync keys and preview records in ~/.cache/byteask-context. Indexed repositories stay on ByteAsk; their edit sync is ended, or they are deleted, at https://app.byteask.ai.
- The backups (*.bak-byteask-*) stay next to the files that were edited.
- The CLI only with `--components cli`: it logs out and removes the CLI's programs and files, and keeps the user's sessions and history in ~/.byteask.
- Cloud Agent: remove the ByteAsk GitHub App from the GitHub organization and disconnect Slack or Jira at https://app.byteask.ai/account?tab=integrations.

## Working rules

- Never put a key or token into the chat, a log, or a file inside a repository. The link and code that `login` prints are for the user to see; nothing else secret should ever appear. The hook key stays in ~/.byteask/context/hook.key; MCP sign-ins are kept by the agent itself.
- Never run a step that costs money without the user's yes (Cloud Agent tasks, CLI turns, a plan change).
- Install and upgrade run right after the user's reply to step 2, without a dry run; the script backs up every file it edits. Show a dry run only when the user asks. Uninstall only when the user asks for it.
- Keep your messages short: questions in step 2, the sign-in link and code in step 5, the result in step 6.
- Do not edit the files the script manages by hand; run the script again.
- If a command here fails or this guide is wrong, tell the user and report it to support@byteask.ai: what you ran and its output, without secrets.

## Pinned files (SHA-256)

  https://byteask.ai/install.sh                                af2df2529834177e1998b71ebfcf190f6d8ce60ec5d10bd9999dfbeb8b2ee8fc
  https://byteask.ai/context/hook/v4/byteask-context-hook.py   43df15e6215ebea295c41a11ea4d4e9fac39dea429f02f8f25231cadd56ed9a3
  https://code.byteask.ai/install.sh                           de7e869553a9a77a2a7ca99de30a742273f4658d9ee669b6c95ae55cf4e48377

Check the first one yourself before running it (step 4). The script checks the other two before it runs them.