This file provides guidance to WARP (warp.dev) when working with code in this repository.
All commands are intended to be run from the repository root.
yarn start— Run the development server (Create React App) athttp://localhost:3000.yarn build— Create a production build inbuild/.yarn test— Run the Jest test runner in watch mode (viareact-scripts test).yarn serve— Build the app and serve the production build locally.
Notes:
- Linting is handled by Create React App's built-in ESLint config (
react-app,react-app/jest). There are no separate lint scripts; linting runs automatically duringyarn start,yarn test, andyarn build. - When working on tests, use the interactive Jest/CRA UI provided by
yarn testto narrow to specific test files or test names.
- Client-only React single-page application created with Create React App + TypeScript.
- Uses
HashRouterfromreact-router-domfor routing, so URLs use#/fragments. - No backend in this repo; all persistence is via
localStorageand all model interaction is directly with the OpenRouter HTTP API.
src/index.tsx— React entry point; renders<App />into#root.src/App.tsx— Sets up theHashRouterand route configuration:/→Homepage./settings→Settingspage.
Defined in src/types/index.ts:
MessageSender— DistinguishesSystem,Moderator, andAgentmessages.MafiaRole— The semantic role for an agent in the Mafia-style game (Mafia,Civilian,Detective,Doctor,Don).GameState— High-level game lifecycle (Initial,Started,Ended).Message— Chat message shape shared across the app.AgentConfig— Serializable configuration for an agent (id, name, model, system prompt, color, Mafia role).OpenRouterModel— Minimal representation of a model returned from the OpenRouter models API.
These types form the core domain layer that connects pages, hooks, and the ChatAgent class.
Central state and behavior for the main experience:
- Holds React state for:
messages: Message[]— Ordered chat history.agents: ChatAgent[]— In-memory agent instances.isLoading: boolean— Indicates an in-flight agent call.activeAgentId: string | null— Which agent is currently responding.gameState: GameState— Overall game lifecycle.
- Uses
localStoragekeyopenrouter_api_keyto access the OpenRouter API key before creating or invoking agents. - Exposes callbacks consumed by the UI:
sendMessage— Append a moderator message.askAgent— Given aChatAgent, call itsgeneratemethod with the currentmessageshistory and append the agent's reply.addAgent— Create a newChatAgentfrom a partialAgentConfigand the stored API key; extendagents.removeAgent— Remove an agent by id.clearMessages— Reset chat history.startGame— Move state toStartedand append a system message announcing the start.
The Home page is effectively a thin container over useChat, wiring this state and these callbacks into presentational components.
Wrapper around the ai SDK and OpenRouter provider:
- Constructed with an
AgentConfigand an OpenRouter API key. - Internally creates an
openrouterclient viacreateOpenRouter({ apiKey })and aToolLoopAgentwith:modelderived fromconfig.model.instructionsfromconfig.systemPrompt.- An empty
toolsset for now.
generate(messages: Message[]): Promise<string>:- Maps internal
Messageinstances toModelMessages for theaiSDK. - Uses
MessageSenderto chooseuservsassistantroles and to decorate agent messages with[agentName]:prefixes. - Delegates to
this.agent.generate({ messages })and returns the resultingtext.
- Maps internal
- Provides read-only getters (
id,name,color,model,systemPrompt,mafiaRole) andtoJSON/fromJSONhelpers to serialize/deserialize agents if persistence is added later.
ChatAgent is the only place that knows about the ai SDK and OpenRouter client; all UI and hooks interact with it via its TypeScript interface.
- Pulls state and actions from
useChat. - Calculates derived UI flags:
isInitial— based onGameState.canStart— requires at least two agents.
- Renders:
Header— PassesonStart,disableStart, anddisableSettingsbased ongameStateand agent count.AgentPanel— Shows current agents, allows selecting one to respond, adding new agents, or removing existing ones.ChatMessages— Visual list of all messages with per-agent colors.ChatInput— Textarea for moderator messages.
Handles all persistent configuration via localStorage and the OpenRouter HTTP API:
- Storage keys:
openrouter_api_key— Bearer token for OpenRouter; used byuseChatand written here.selected_models— Array ofOpenRouterModelpersisted as JSON; used byAgentFormto populate model choices.
- API interactions:
POST https://openrouter.ai/api/v1/chat/completions— Simple test request with modelopenai/gpt-3.5-turboto validate the API key.GET https://openrouter.ai/api/v1/models— Fetches available models; response trimmed down to{ id, name }.
- Local UI state manages loading flags, test status, model search string, and the list of all and selected models.
Any changes to how API keys or model lists are stored should stay consistent with these storage keys so the rest of the app (notably useChat and AgentForm) continue to function.
Header— Top navigation bar:- Shows logo/link to
/. - Optional
Startbutton controlled byHome. - Either a
Settingslink (when allowed) or a disabled label, or a back link on the Settings page.
- Shows logo/link to
AgentPanel— Left-side panel listing agents and providing creation/removal controls:- Receives
ChatAgent[]plus callbacks fromHome/useChat. - Manages local
showFormtoggle to revealAgentForm.
- Receives
AgentForm— Agent creation form:- Builds an
Omit<AgentConfig, 'id'>foruseChat.addAgent. - Reads
selected_modelsfromlocalStorageto populate available models; if none, shows a hint to configure Settings. - Randomizes default name and color.
- Allows choosing a
MafiaRole, system prompt, and color.
- Builds an
AgentCard— Visual representation of a single agent:- Uses
MafiaRoleto choose background color and emoji. - Shows agent name and model, with a colored border from
agent.color. - Optional remove button, guarded to avoid triggering the card click.
- Uses
ChatMessages/ChatMessage— Present the chat transcript:- Scrolls to bottom on new messages.
- Colors agent messages based on the associated agent's
color(falling back to a default gray when unknown). - Distinguishes system, moderator, and agent messages in layout and styling.
ChatInput— Textarea and send button for moderator messages:- Submits on Enter (without Shift) and supports multi-line input with Shift+Enter.
- OpenRouter API key is stored only in
localStorageunder the keyopenrouter_api_key. - The list of selectable models is stored under
selected_modelsas a JSON array of{ id, name }. ChatAgentinstances themselves are not persisted; they are recreated in memory on each page load.
Any future persistence (e.g., saving agents or chat history) should reuse the existing AgentConfig and Message types where possible.
This repository also contains a CLAUDE.md file used to guide Claude Code. Its key instructions that are relevant here have been incorporated:
- Use the Yarn scripts defined in
package.json(start,build,test,serve) for all routine development workflows. - Treat the app as a client-only React SPA; do not assume a backend or server-side rendering in this repo.
- Respect the existing routing structure (
HashRouter) and the localStorage-based storage of the OpenRouter API key and model selections when extending functionality.