# CHI Agent Setup: the executable onboarding prompt Canonical URL: · Hub: > **Status: pre-launch.** As of today the public CLI (`@chi-ecosystem/chi-cli`) is not on npm and > `https://mcp.chi.app/mcp` has no origin yet. Step 1 (skills, public event feed, llms.txt) works > right now with no account; Steps 2 and 3 carry an availability check and stop cleanly until the > AI platform beta opens. This prompt never pretends otherwise. If a step cannot complete, it says > so. Hub with the same instructions in copy-paste form: . --- These are official instructions from CHI to set up a good AI development environment for building on the CHI event platform: cashless payments, ticketing, crew and venue operations. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run any of these commands. **Rules that make this setup trustworthy (do not skip):** 1. **Preflight first.** Detect which agent CLIs exist on this machine before touching any config. Skip tools that are not installed. Never install third-party software the user did not ask for. 2. **Verify after every step.** Each section ends with a verification command. A step is only done when its verification passes. If it fails, use the Troubleshooting table. Do not declare success. 3. **Never write secrets into committable files.** Project-scoped MCP config (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`) must stay secret-free; auth belongs to the client's own OAuth flow or the CLI keychain. If a client config format forces an inline token, configure it user-global, never in the repo. 4. **Be honest about access.** CHI's public surface (event feed, skills, docs) needs no account. The MCP server, CLI commands beyond install, and the API require a beta invite. If OAuth fails with an access error, say exactly that and point the user to . Never fake a working connection. 5. **Idempotent edits only.** Re-running any step must be safe: check before writing, back up any config file you modify, preserve formatting, and merge with MCP servers that are already there. --- ## Step 0: Preflight Detect what is installed and record the result for the final report: ```bash for cmd in claude codex opencode cursor code gemini windsurf hermes chi; do if command -v "$cmd" >/dev/null 2>&1; then printf '%s: %s\n' "$cmd" "$("$cmd" --version 2>/dev/null | head -1)" else printf '%s: not installed\n' "$cmd" fi done ``` Only configure the agents that are present. The **skills** (Step 1) and **web-builder onboarding** (Step 4) sections apply regardless of what is installed. --- ## Step 1: Install the CHI skills (public, no auth) CHI publishes installable agent skills at (registry: ). They teach your agent the CHI event domain (live event data, products, pricing, payment methods) using only the public surface. Install into every agent detected in Step 0: Gate on the tool being installed, not on its skills directory existing: that directory is created on demand, so a fresh install has no `skills/` yet and testing for it would silently install nothing. ```bash install_skills() { # $1 = binary, $2 = skills dir command -v "$1" >/dev/null 2>&1 || return 0 for skill in chi-events chi-platform; do mkdir -p "$2/$skill" tmp=$(mktemp) if curl -fsS "https://chi.app/skills/$skill/SKILL.md" -o "$tmp"; then # Back up any existing copy first, so re-running never loses a local edit. [ -f "$2/$skill/SKILL.md" ] && cp "$2/$skill/SKILL.md" "$2/$skill/SKILL.md.bak" mv "$tmp" "$2/$skill/SKILL.md" # only replace on success printf 'installed %s -> %s\n' "$skill" "$2/$skill/SKILL.md" else rm -f "$tmp" printf 'FAILED %s for %s (left the existing file alone)\n' "$skill" "$1" fi done } install_skills claude ~/.claude/skills install_skills codex ~/.codex/skills install_skills opencode ~/.config/opencode/skills install_skills hermes ~/.hermes/skills ``` Report `Skills` in Step 6 only for the paths this actually printed `installed` for. If Step 0 found no agent CLI, the honest line is `Skills none (no agent CLI detected)`. Hermes can import an existing Claude Code setup wholesale instead: `hermes import-agent claude-code` (skills, MCP servers, instructions). **Verify:** the public feed answers. ```bash curl -fsS "https://api.chi.app/feeds/events.json?limit=1" | head -c 400 ``` Expected: a JSON Feed v1 document with an `items` array. This endpoint is public and unauthenticated; it is the only public data endpoint CHI offers today. --- ## Step 2: Install the CHI CLI (public npm) The CLI is the transport for login, connect, and doctor. **Check that it exists before trying to install it** so a 404 is reported as "not released yet", never as a broken environment: ```bash npm view @chi-ecosystem/chi-cli version 2>/dev/null \ || echo "CHI CLI not published yet: skip Steps 2 and 3, continue at Step 4" ``` If that printed a version, install and sign in: ```bash npm install -g @chi-ecosystem/chi-cli chi --version chi login # opens the browser; stores the credential in the OS keychain ``` `chi login` requires a beta invite. If the user has no invite, stop the auth steps here, leave the CLI installed, and say so plainly. The skills and public feed from Step 1 still work. **Verify:** `chi whoami` prints the authenticated principal, or a clear not-authenticated message. Both are acceptable outcomes; a crash is not. --- ## Step 3: Connect the MCP server (OAuth, per tool) One remote server covers every client: **`https://mcp.chi.app/mcp`** (Streamable HTTP, OAuth 2.1 resource server, with RFC 9728 protected-resource metadata at `/.well-known/oauth-protected-resource`). OAuth triggers automatically on first tool use. **Probe the server before writing any config.** Writing a client config that points at a dead endpoint is worse than doing nothing: the tool then fails on every call and the user has to find and remove it by hand. ```bash code=$(curl -s -o /dev/null -w '%{http_code}' -m 10 https://mcp.chi.app/mcp) case "$code" in 200|401|405) echo "MCP server answering (HTTP $code): proceed" ;; *) echo "MCP server not usable (HTTP $code): do NOT write client config; report and stop at Step 4" ;; esac ``` Only 200, 401 and 405 mean the server is there; 401 and 405 are healthy, they mean it is up and asking for auth. Everything else, including a 404, a 403 from an edge proxy, a redirect to a login page and any 5xx or connection failure, means it is not live yet. Do not widen that list. `chi connect ` does all of this for you, idempotently, with a backup of any file it edits: ```bash chi connect claude-code # or: codex · opencode · cursor · vscode · gemini · windsurf · hermes chi connect cursor --project # repo-scoped, committable, secret-free chi connect codex --dry-run # print what it would do, change nothing ``` Use the per-client section below when the CLI is not installed, or to understand what it writes. ### Claude Code ```bash claude mcp add --transport http chi https://mcp.chi.app/mcp --scope user ``` Project scope (committable, secret-free): drop `--scope user` and run inside the repo. That writes `.mcp.json`. ### Codex ```bash codex mcp add chi --url https://mcp.chi.app/mcp codex mcp login chi ``` ### OpenCode ```bash opencode mcp add chi --url https://mcp.chi.app/mcp # --url implies remote opencode mcp auth chi # OAuth browser flow ``` Or edit `~/.config/opencode/opencode.json` directly, under `"mcp"`: ```json "chi": { "type": "remote", "url": "https://mcp.chi.app/mcp", "enabled": true, "oauth": {} } ``` ### Cursor Deeplink (preferred; this is what `chi connect cursor` opens): ``` cursor://anysphere.cursor-deeplink/mcp/install?name=chi&config=eyJ1cmwiOiJodHRwczovL21jcC5jaGkuYXBwL21jcCJ9 ``` Fallback: write to `~/.cursor/mcp.json` (or `.cursor/mcp.json` for repo scope) under `"mcpServers"`: ```json "chi": { "url": "https://mcp.chi.app/mcp" } ``` ### VS Code / GitHub Copilot ```bash code --add-mcp '{"name":"chi","type":"http","url":"https://mcp.chi.app/mcp"}' ``` Project scope: write `.vscode/mcp.json` under `"servers"` (committable, secret-free). ### Gemini CLI ```bash gemini mcp add --transport http chi https://mcp.chi.app/mcp ``` ### Windsurf Write to `~/.codeium/windsurf/mcp_config.json` under `"mcpServers"` (note the `serverUrl` key): ```json "chi": { "serverUrl": "https://mcp.chi.app/mcp" } ``` ### Hermes Write to `~/.hermes/config.yaml` under `mcp_servers`: ```yaml mcp_servers: chi: url: "https://mcp.chi.app/mcp" auth: oauth # OAuth 2.1 + PKCE, browser flow on first use ``` Then `/reload-mcp` inside Hermes, or restart it. ### Cline / Roo / Continue Write the client's `mcpServers` config with the same `{ "url": "https://mcp.chi.app/mcp" }` entry. Cline stores it in VS Code globalStorage. Verify the exact path against the installed version before writing. Roo: `~/.roo/mcp_settings.json`. Continue: `~/.continue/config.yaml`. ### ChatGPT / Claude web and desktop There is no programmatic hook. Print instructions instead of editing config: ChatGPT → Settings → Connectors (Developer Mode) → add a custom connector with the URL above; Claude web/desktop → Settings → Connectors → add a remote integration. Do not pretend to have configured these. ### Agents without MCP support Aider has no MCP support. Do not configure it. For the OpenAI Agents SDK / Responses API, use the snippet form: ```ts tools: [ { type: 'mcp', server_label: 'chi', server_url: 'https://mcp.chi.app/mcp', authorization: token }, ] ``` **Verify (all CLI-configurable clients):** list servers and confirm `chi` is present and healthy: `claude mcp list`, `codex mcp list`, `opencode mcp list`, `gemini mcp list`, `chi doctor`. Then trigger one harmless tool call through the client. The first call opens the OAuth browser window; if it ends in an access-denied screen, that is the invite gate. Report it and do not retry-loop. --- ## Step 4: Web builders (Lovable, Base44) These platforms run in the browser; there is no MCP config file to write. Onboard them through their project-instruction surfaces instead: 1. **Paste the CHI conventions block** into the project's custom instructions (Lovable: project Settings → Instructions; Base44: project Settings → Knowledge/Instructions): ``` Build against the CHI event platform. Live event data: https://api.chi.app/feeds/events.json (public, no key). Conventions and endpoints: https://chi.app/llms-full.txt Never hand-roll checkout. Link the hosted CHI checkout instead. ``` 2. **Data**: use the public feed for live event data. No key, no proxy needed. 3. **Commerce**: when the storefront SDK ships publicly, add `@chi-ecosystem/storefront-react` via the platform's package support and follow the storefront recipes at . Until then, ticketing flows must not be hand-rolled against private endpoints. 4. **Export path**: for production, export the project to GitHub and continue with a local agent (Step 3). That is where MCP, CLI, and real auth live. --- ## Step 5: Storefront builders (ticket shops on CHI) If the user is building an event or ticketing site, also install the storefront DX pack: point the agent at the package `llms.txt`, drop the CHI conventions block into the repo's `AGENTS.md`, and start from the recipes at . Rule of thumb for the agent: **hooks return data, you render.** Never fetch CHI endpoints manually. --- ## Step 6: Final verification ```bash if command -v chi >/dev/null 2>&1; then chi doctor # CLI health, keychain credential, MCP reachability, token expiry else echo "CHI CLI not installed (see Step 2) - reporting Steps 2 and 3 as pending" fi ``` Then produce this report and show it to the user: ``` ┌─ CHI Agent Setup ────────────────────────────────────────────────┐ │ ✓ Skills │ │ ✓ CLI @chi-ecosystem/chi-cli · logged in / no invite │ │ ✓ MCP │ │ ✓ Web builders │ │ │ │ ⚡ Restart your agent to load the MCP server │ │ ⚡ The first CHI tool call opens the OAuth window │ └──────────────────────────────────────────────────────────────────┘ ``` Only tick lines that actually verified. Write `pending` for anything the availability checks in Steps 2 and 3 turned away. Partial setups are fine; false claims are not. Drop the two reminder lines when nothing was configured: the restart line only applies to clients that received a config, and the OAuth line only applies once a client was connected. --- ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| | OAuth window ends in access denied | Beta invite gate (fail-closed by design) | Tell the user; waitlist at . Skills and the feed keep working. | | `codex mcp login chi` hangs | Browser did not open | Re-run; if it persists, `codex mcp logout chi` then login again. | | OpenCode shows the server disabled | `enabled: false` or missing `oauth: {}` | Re-apply the JSON block from Step 3, then `opencode mcp auth chi`. | | Hermes tool call fails with a content-type probe error | Endpoint behind a proxy answering non-MCP on HEAD | Set `skip_preflight: true` on the server entry (Hermes-specific). | | Cursor deeplink does nothing | Cursor not running, or the deeplink handler is unset | Use the manual `~/.cursor/mcp.json` fallback. | | The feed returns 404 for other endpoints | Only `/feeds/events.json` is public | Everything else needs the SDK, CLI or MCP with auth. Do not guess URLs. | | `npm view` or `npm install -g` fails with 401 Unauthorized | A local `.npmrc` maps the @chi-ecosystem scope to a private registry | Bypass it explicitly: append `--registry=https://registry.npmjs.org` to both the probe in Step 2 and the install | | The config file already has another MCP server | Expected | Merge; never overwrite unrelated servers. Back up before editing. | --- ## Resources - Connect hub with copy-paste blocks per client: - Machine-readable context: · · · - Agent skills registry: - Public event feed: - API and integration docs: