{"slug":"strategy/product-strategy/CURSOR_MODELS","title":"Cursor Models Configuration (for IntegrateWise workspace)","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/product-strategy/CURSOR_MODELS.mdx","bytes":8662,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> Last updated: 2026-08-06\n> Purpose: Recommended model choices inside the Cursor IDE when working on this repo.\n\n## Why Model Choice Matters Here\n\nThis codebase has heavy protocol surface:\n\n- `AGENTS.md` (long)\n- `CLAUDE.md`\n- `.cursor/rules/iw-continuity-protocol.mdc` (always applied)\n- Multiple other .mdc rules + handoff requirements\n\nYou need a model that:\n\n- Handles very long context + strict instructions reliably\n- Excels at \"do not skip declaration, always produce handoff, respect CF-only, never write secrets\"\n- Is strong at TypeScript + Cloudflare + architecture reasoning\n\n## Recommended Settings (Cursor IDE)\n\n### 1. Add API Keys (required for the models below)\n\nCursor Settings (`Cmd+,`) → **Models** (or search \"API Keys\"):\n\n**Required for recommended setup:**\n\n- **Anthropic API Key** (priority #1)\n  - Get at: https://console.anthropic.com/\n  - Enables: claude-4-sonnet, claude-4-opus, claude-3-5-sonnet etc.\n\n**Strongly recommended:**\n\n- **OpenAI API Key**\n  - Enables: o3, o1, gpt-4o, gpt-4o-mini, etc.\n\n**Optional:**\n\n- xAI API Key (for Grok models)\n- Others as needed\n\n**Never put these keys in the repo.** Cursor stores them locally in your app.\n\n### 2. Set Default Models in Cursor UI\n\nAfter adding keys, assign defaults:\n\n- **Agent** (most important for this repo): `claude-4-sonnet` (or the latest Sonnet variant listed)\n- **Composer**: `claude-4-sonnet` or a fast model\n- **Chat**: Same or Cursor's fast tier\n\nYou can override per conversation by clicking the model name in the chat input bar.\n\nThere is no committed workspace file for \"default model\" — configuration lives in Cursor's local settings + per-session picker. The rules we added (`.cursorrules` + `iw-continuity-protocol.mdc`) will guide the agent regardless of exact model (as long as it has good instruction following).\n\n### 2. Assign Models by Feature\n\n| Feature                           | Recommended Model                                  | Why                                                  |\n| --------------------------------- | -------------------------------------------------- | ---------------------------------------------------- |\n| **Agent**                         | `claude-4-sonnet` (or latest Claude Sonnet)        | Best instruction following for our rules + protocols |\n| **Composer**                      | `claude-4-sonnet` or Cursor fast                   | Good balance of quality + speed                      |\n| **Chat**                          | `claude-4-sonnet` or `cursor-small`                | Daily work                                           |\n| **Hard reasoning / architecture** | `o3` / `o1-pro` / `claude-4-opus` (switch in chat) | Deep planning before implementation                  |\n| **Tab / autocomplete**            | Cursor fast / Sonnet                               | Low latency                                          |\n\nIn the chat input bar you can click the model name at any time to override for that conversation.\n\n### 3. Enable Long Context When Needed\n\n- When reading full AGENTS.md + rules + multiple services → enable \"Max mode\" / long context if offered.\n- For big refactors involving Spine + Twin + Gateway, start with a strong reasoning model first.\n\n### 4. Per-Session Best Practice\n\n1. New chat / Agent session\n2. Immediately verify the model sees the injected rules (ask \"what is the mandatory declaration?\").\n3. It should say something like: \"I have read the IntegrateWise constitutional documents\" when it acts.\n\n## Default Models + API Keys (Project Runtime)\n\nThese are **for the IntegrateWise product** (Twin, intelligence, etc.). Separate from Cursor IDE keys.\n\n### Default Models (as of now)\n\n| Component                      | Default Model                       | Location                                                                    |\n| ------------------------------ | ----------------------------------- | --------------------------------------------------------------------------- |\n| Twin (iw-agent-runtime)        | `openrouter/openai/gpt-5-mini`      | `wrangler.toml`, `capability-contract.ts`                                   |\n| Shared OpenRouterClient        | `anthropic/claude-3.5-sonnet`       | `packages/lib/src/openrouter.ts` (DEFAULT_MODELS.chat)                      |\n| AIProvider (openrouter)        | `anthropic/claude-3.5-sonnet`       | `packages/lib/src/ai-provider.ts`                                           |\n| CF Workers AI (primary)        | `moonshotai/kimi-k3`                | `services/iw-agent-runtime/src/ecosystem/ai-gateway.ts` (CF_MODELS.PRIMARY) |\n| CF Workers AI (fast fallback)  | `@cf/meta/llama-3.1-8b-instruct`    | `services/iw-agent-runtime/src/ecosystem/ai-gateway.ts` (CF_MODELS.FAST)    |\n| Intelligence router (examples) | Workers AI llama or free OpenRouter | `services/intelligence/src/lib/ai-router.ts`                                |\n| .env.example comment           | `anthropic/claude-3.5-sonnet`       | `.env.example`                                                              |\n\n**Note:** Production traffic must go through **Cloudflare AI Gateway** (DECISION 26).\n\n### API Keys the Project Needs\n\n**Primary:**\n\n- `OPENROUTER_API_KEY`\n\n**Per-environment var:**\n\n- `AI_GATEWAY_ID`\n  - dev: `integratewise-ai-dev`\n  - test: `integratewise-ai-test`\n  - prod: `integratewise-ai-prod`\n\n**How to set (never commit the actual key):**\n\n**Local dev:**\n\n```bash\n# In each service that needs AI\nservices/intelligence/.dev.vars\nservices/iw-agent-runtime/.dev.vars\n# (and knowledge, think, etc. as needed)\n```\n\nContent example:\n\n```\nOPENROUTER_API_KEY=sk-or-v1-yourkeyhere\n```\n\n**Production / deployed:**\n\n- Use Cloudflare Secrets Store (already wired in `wrangler.toml` for intelligence).\n- Or: `unset CLOUDFLARE_API_TOKEN && wrangler secret put OPENROUTER_API_KEY --env production`\n- `AI_GATEWAY_ID` lives in the `[vars]` or `[env.xxx.vars]` sections of wrangler.toml (already set per env).\n\nSee `.env.example` for the full list of AI-related variables.\n\n### Cursor IDE vs Project Keys\n\n- **Cursor IDE models** → You provide keys directly in Cursor Settings (Anthropic/OpenAI). Stored locally on your machine.\n- **IW product models** → Project uses its own `OPENROUTER_API_KEY` + AI Gateway. The MCP bridge we configured earlier gives Cursor _tools_, not model access.\n\n### Codex App (OpenAI Codex.desktop)\n\nCodex.app is another AI coding/agent surface (Chromium-based, at /Applications/Codex.app, data in ~/Library/Application Support/Codex).\n\n**MCP / Agents update (same as Cursor/OpenCode):**\n\nUse the stdio bridge for \"integratewise\":\n\n- Command: `node`\n- Args: `/Users/nirmal/Github/integratewise-live/scripts/integratewise-mcp-bridge.mjs`\n- Env:\n  - INTEGRATEWISE_MCP_URL=https://mcp.integratewise.ai\n  - INTEGRATEWISE_TENANT_ID=integratewise\n  - INTEGRATEWISE_CLIENT_ID=cursor-iw\n\nAdd this in Codex's MCP/Tools settings UI (if it has a servers panel like Cursor) or its config if it exposes a JSON.\n\nThe setup script (`setup-ai-mcp-clients.sh`) now covers Codex.\n\n**Default models & API keys in Codex:**\n\n- Add your Anthropic key (for Claude 4 Sonnet) and/or OpenAI key inside the app's model/API settings.\n- Recommended default for agent work: Claude 4 Sonnet (best for following the long IW protocol docs, handoff requirements, and rules we have injected in other tools).\n- For hard tasks: switch to o-series or Opus if available in the app.\n\nStart sessions in Codex with the declaration: \"I have read the IntegrateWise constitutional documents\" and use the `integratewise` tool server for any Spine/memory/KB access.\n\nRestart Codex after adding the MCP server.\n\nSee also the updated setup script for automation notes.\n\nThis separation is intentional (and required by the architecture).\n\n## Quick Verification After Changing Models\n\nStart a fresh chat and say:\n\n\"Confirm you have read the IntegrateWise constitutional documents and list the first three things you must do before editing code.\"\n\nA correctly configured strong model + our rules should respond with the proper protocol.\n\n## Adding a Custom Provider (Advanced)\n\nIf the project ever exposes an OpenAI-compatible `/v1/chat/completions` (via the intelligence layer or a dedicated proxy), you can add it under Custom Models in Cursor:\n\n- Base URL: `https://your-gateway...`\n- Model name: the slug used internally (e.g. `openrouter/anthropic/claude-4-sonnet`)\n\nCurrently the primary surface for external agents is **MCP** (configured in `.cursor/mcp.json`), not direct model calls.\n\n---\n\nUpdate this file when Cursor adds new model options or the project's default inference model changes.\n"}