Stardew Valley SMAPI mod — HTTP API for external control + in-game AI chat.

📥 Download the latest release →

Grab NagiBridge.zip from the link above — it already contains the compiled NagiBridge.dll. You do not need to build anything.

1. Install SMAPI
2. Download NagiBridge.zip from Releases and unzip it
3. Move the unzipped NagiBridge folder into your Stardew Valley/Mods/ folder (so you end up with Stardew Valley/Mods/NagiBridge/NagiBridge.dll + manifest.json)
4. Launch the game through SMAPI

First launch auto-generates config.json. The mod is built for Stardew Valley 1.6+ / SMAPI 4.0+ and the same .dll works on Windows, macOS and Linux.

Cloning the source repo? There is no .dll in the source tree — it ships only in Releases. If you cloned/downloaded the code and SMAPI says it can't find NagiBridge.dll, download the release zip above, or build it yourself (see below).

Requires the .NET SDK (6.0+) and a local Stardew Valley install.

dotnet build -c Release

The project uses Pathoschild.Stardew.ModBuildConfig, which auto-detects your game folder (Steam / GOG / Xbox on any OS) and copies the built mod straight into Stardew Valley/Mods/NagiBridge/. No paths to edit. If auto-detection fails, set a GamePath property or GAME_PATH environment variable pointing at your install.

Game starts an HTTP server on localhost:7842 (host) / 7843 (farmhand).

Full endpoint list: see AGENTS.md

Press ` (backtick, keyboard top-left) to open the chat panel.

┌─────────────────────────┐
│  Nagi Chat              │
│                         │
│  > API Mode             │
│    Channel Mode         │
│                         │
│  Up/Down = Select       │
│  Enter = OK             │
└─────────────────────────┘

• API Mode — Connect to an LLM API (Claude, DeepSeek, OpenAI, or any compatible endpoint). The AI chats with you in-game.
• Channel Mode — Connect to Claude Code via a local channel server. Claude Code controls the game and chats through the panel.

After selecting a mode, you'll be prompted to enter a display name for the AI (default: "Nagi").

Press Tab (when input is empty) in the chat panel to return to mode selection. Switch between API and Channel at any time.

For chatting with an LLM directly in-game. No external tools required.

1. Select API Mode → enter display name → press Enter
2. API Key — Paste your key with Ctrl+V (shown as ****abcd)
3. URL — Auto-filled based on provider. Custom endpoints supported.
4. Press Enter to connect

The provider is auto-detected from the URL. Custom URLs use OpenAI-compatible format.

{
  "Mode": "",
  "ApiProvider": "deepseek",
  "ApiUrl": "",
  "ApiKey": "",
  "Model": "deepseek-chat",
  "SystemPrompt": "You are a friendly AI companion in Stardew Valley...",
  "MaxHistoryMessages": 20
}

• API key is saved locally after first entry. Next launch auto-fills (masked with stars).
• Chat history persists across game restarts in chat_history.json.
• SystemPrompt — Customize the AI's personality.
• MaxHistoryMessages — How many turns to include in API calls (memory window).

For LLMs that support tool calling (function calling), a standalone Python agent lets the AI actually play the game:

python scripts/tool_agent.py --provider deepseek --key sk-xxx --port 7842

The AI can use 17 game tools: get_state, warp, move_to, use_tool, farm, mine, harvest, etc.

See scripts/tool_agent.py for details.

For connecting to Claude Code (CC). CC controls the game via HTTP API and chats through the panel.

Game ChatHud → POST → channel_server.py (:9000) → inbox file → CC Monitor → CC responds
                                                                               ↓
Game ChatHud ← /chat/push (:7842) ←────────────────────────────────────────────┘

Each new CC session needs two things:

1. Start channel server:

bash ~/source/NagiBridge/scripts/start_channel.sh

Or manually:

cd scripts && python channel_server.py &

2. Start message monitor (CC tool):

Monitor(description="stardew chat", persistent=true,
        command="tail -f ~/nagi/overlay_inbox.jsonl | grep --line-buffered text")

3. Reply to player via API:

curl -X POST http://localhost:7842/chat/push \
  -H "Content-Type: application/json" \
  -d '{"sender":"Nagi","message":"Hello!"}'

{
  "Mode": "cc",
  "ChannelServerUrl": "http://localhost:9000/chat"
}

When Mode is "cc", the chat panel opens directly in Channel mode (skips mode selection).

When the chat panel is closed, the last 2 messages are shown as a preview above the toolbar (bottom-left corner).

Python scripts for common farm tasks. Require requests package.

pip install requests

All scripts default to --port 7842. Add PYTHONIOENCODING=utf-8 on Windows.