# 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". Before anything that costs money, tell the user what it will cost and wait for a yes. Before any change to the machine, show the user the change (every command below has a dry run for that). ## What ByteAsk is ByteAsk makes tools for C and C++ engineers. Three products: - Context: C/C++ code intelligence for the coding agent you already use, built from the project's real build (compile_commands.json). It answers where a change most likely belongs, with the code. 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 (read-only commands, nothing installed). 2. Ask the user one question: which products. 3. Price it: tell the user what it costs ($0 to set up on Free). 4. Install with the one script: dry run first, show the user, then the real run. 5. Sign in: a few short browser approvals with the same ByteAsk account. 6. Verify each component. 7. Show the user what to do next, and how to remove it all. ## 1. Detect (read-only) - Which agent is running this guide. You know which one you are. If unsure: `claude --version` (Claude Code), `codex --version` (Codex). For Cursor or another MCP client, ask the user. - OS and shell: `uname -s` and `echo "$SHELL"`. The script is POSIX sh for Linux and macOS. On Windows, use WSL; native Windows is not covered by this guide yet. - Tools: `command -v curl python3` and `python3 -c 'import sys; print(sys.version_info >= (3, 8))'`. Context needs curl and Python 3.8 or newer. - Is ByteAsk already set up: `claude mcp get byteask`, `ls -la ~/.byteask`, `byteask --version`, and the script's `status` once you have downloaded it (step 4). If anything is there, including a setup from ByteAsk's older copy-paste prompt, this is an upgrade: run `upgrade` (or `install` again; it is idempotent). Never make a second copy. - The current folder: `git rev-parse --show-toplevel`, `git ls-files '*.c' '*.cc' '*.cpp' '*.cxx' '*.h' '*.hpp' | head -n 3`, and `ls compile_commands.json build/compile_commands.json 2>/dev/null`. Context works in a C or C++ git repository with a remote; a compile_commands.json lets ByteAsk index the real build (CMake: -DCMAKE_EXPORT_COMPILE_COMMANDS=ON; make: bear -- make). Note what you find for step 7. ## 2. Ask the user (one message) Ask which products they want, with the defaults marked: [x] Context in : C/C++ code intelligence for this agent, from the project's real build. Recommended for everyone; the Free plan covers it. [ ] Cloud Agent: hand tasks to ByteAsk from Slack or Jira; it works in a cloud sandbox and opens tested draft pull requests. Needs a GitHub organization admin to install the ByteAsk GitHub App. Set up in the browser; nothing is installed on this machine. [ ] ByteAsk CLI: a terminal coding agent with ByteAsk's C/C++ tools and models (a large download, about 100 MB). In the same message ask, for Context: "May ByteAsk index your C/C++ repositories without asking you each time?" (default no). For the CLI: the email address of their ByteAsk account. ## 3. Price it Say this before any paid step: "What this setup costs you: $0 on the Free plan." Installing Context, the CLI and connecting the Cloud Agent cost nothing. 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 Download the script once and check it: d=$(mktemp -d) && curl -fsSL https://byteask.ai/install.sh -o "$d/install.sh" && echo "$d/install.sh" sha256sum "$d/install.sh" (macOS: shasum -a 256 "$d/install.sh") Its SHA-256 must be the one for https://byteask.ai/install.sh under "Pinned files" at the end of this guide. If it differs, delete it, stop, and tell the user. Below, `install.sh` means the path that command printed. 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] - It downloads only pinned files and checks each SHA-256 before anything runs it; on a mismatch it deletes the file and stops. - 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. Run, with the user's choices (add `--allow-indexing` only if they said yes; add `,cli` or `,agent` to --components if chosen): sh install.sh install --components context --agent claude-code --dry-run Show the user the whole output. After their OK, run the same command without `--dry-run`. Your agent may need permission to run it: the script writes outside the current folder (~/.byteask, ~/.claude, ~/.codex) and uses the network. Codex: ask to run it outside the sandbox (Codex asks the user). Claude Code and Cursor: their usual approval prompt. 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}'` (an existing byteask entry with other settings is removed first); - `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 and . 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. - 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); - 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. ### The instruction text (the same for every agent) ## C/C++ repositories: ByteAsk The `byteask` MCP server knows C and C++ code through the project's real build. For a bug, crash, failing test or change request in a C or C++ repository: if "ByteAsk Context ran find_code_for_task on this request" is already in your context, start from its places. 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. With --allow-indexing, one more line goes before the end marker: "ByteAsk may index my C/C++ repositories without asking me first." ## 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): `sh install.sh login` prints a link and a code. Show both to the user; they open the link, sign in to ByteAsk, check the code and choose Allow. Then run `sh install.sh wait` (it waits up to 5 minutes; give the command a 6-minute timeout). The key is stored in ~/.byteask/context/hook.key (mode 0600) and can only call find_code_for_task for this 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 before you run it. ## 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 ". 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, 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. The dry run lists what applies here; tell the user about sudo before the real run. 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. ## 7. Next steps to show the user - 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 C or C++ git repository that has a compile_commands.json 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 the build reads, and uploads only after the user agrees. - Cloud Agent: the first task in Slack ("@ByteAsk ") 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 C or C++ git repository, the hook sends each request the user types (40 characters or more) and the repository's remote address 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. - 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: - 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. - 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). - Show every change before you make it: dry run first for install, upgrade and uninstall. - 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 99cfe941ee34d0d6f26d9f755e4e9a374ff5cdc8e3e68a16d17142c44688bbc5 https://byteask.ai/context/hook/v1/byteask-context-hook.py 905aaf7c04c3425d5eea96f73e25b47d85a8cc29c3edd766d05fa09bdba122da 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.