Fastest way in

Run it with your AI agent

Paste one prompt into Claude Code, Gemini CLI, Codex, Cursor or any coding agent with a terminal. It clones the repo, installs everything with uv, starts the simulator, and waits for you before it touches the real panel. Then it connects itself to the panel through the MCP server.

Copy the prompt

It follows the repo's own rules in CLAUDE.md: only the engine talks Bluetooth, and nothing gets "fixed" by editing source.

Start your agent in an empty folder

Pick your agent below for the exact command and where its MCP config lives.

Watch the simulator

The studio opens at http://127.0.0.1:8765 with a simulated panel. No hardware needed yet.

Say "the panel is on"

Close the iDotMatrix phone app first; the panel takes one connection at a time. The agent scans, pairs and draws a test pattern.

Ask it to draw

"Draw a pixel-art rocket, check the snapshot, fix anything that looks off." More in docs/MCP.md.

setup-prompt.txt

Set up DeskDot for me: an open-source engine, studio and MCP server for the
iDotMatrix 32×32 LED panel. Repository: https://github.com/shivpatel2468/idotmatrix

Work step by step and tell me what you are doing before each step.

1. Check prerequisites: git, uv (https://docs.astral.sh/uv/, install it if missing;
   it brings its own Python 3.13) and Node.js 20+ (only to build the studio once).
   Tell me whether this machine has Bluetooth LE.
2. Clone the repo into a folder called deskdot and work inside it:
     git clone https://github.com/shivpatel2468/idotmatrix.git deskdot
3. Read CLAUDE.md and README.md before doing anything else, and follow their rules.
   Above all: only the DeskDot engine may talk to the panel over Bluetooth. Never
   connect to it with any other tool, and never disconnect it on purpose.
4. Install the Python dependencies:   uv sync --extra mcp
5. Build the studio once (in web/):   npm ci, then npm run build
6. Start the engine with the simulated panel, in the background:
     uv run deskdot serve --sim
   Wait until http://127.0.0.1:8765 answers, then tell me to open it.
7. STOP and ask me before touching real hardware. When I confirm the panel is on
   and the iDotMatrix phone app is closed:
   - stop the simulator
   - uv run deskdot scan      (finds the panel, named IDM-xxxxxx)
   - copy deskdot.example.toml to deskdot.toml and set address = "<the MAC found>"
   - uv run deskdot doctor    (draws a test pattern; ask me whether I can see it)
   - uv run deskdot serve     (the real panel; leave it running)
8. Connect yourself to the panel through DeskDot's MCP server (docs/MCP.md):
   a stdio server started with
     uv run --project <absolute path to deskdot> deskdot-mcp
   with env DESKDOT_URL=http://127.0.0.1:8765. Then call panel_snapshot,
   list_apps, and show_app with "clock" to prove it works.
9. Finish with a short summary: what is running, the studio URL, how to stop and
   restart it, and where my deskdot.toml is.

If something fails, read the error and the docs (docs/DEPLOY.md, docs/MCP.md,
docs/HARDWARE_PROTOCOL.md) and fix the setup. Do not edit DeskDot's source code to
work around a problem; tell me instead.

Install Claude Code, open a terminal in the folder that should hold DeskDot, start it and paste the prompt.
Inside the repo, the MCP server is already registered by .mcp.json: approve it when asked, or run /mcp.
From any other folder, add it once with the command from docs/MCP.md.

start

$ claude

$ claude mcp add deskdot -- uv run --project /path/to/deskdot deskdot-mcp

Bonus: merge integrations/claude-code/hooks.json into .claude/settings.json and a mascot on the panel shows when Claude is thinking, working or waiting for you.

Install Gemini CLI, open a terminal in the folder that should hold DeskDot, start it and paste the prompt.
Register DeskDot's MCP server in Gemini CLI's settings.json (your user one, or .gemini/settings.json in the project), then restart Gemini CLI.

start

$ gemini

settings.json

{
  "mcpServers": {
    "deskdot": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/deskdot", "deskdot-mcp"],
      "env": { "DESKDOT_URL": "http://127.0.0.1:8765" }
    }
  }
}

Install the Codex CLI, open a terminal in the folder that should hold DeskDot, start it and paste the prompt.
Register DeskDot's MCP server in Codex's config.toml (usually ~/.codex/config.toml), then restart Codex.

start

$ codex

config.toml

[mcp_servers.deskdot]
command = "uv"
args = ["run", "--project", "/path/to/deskdot", "deskdot-mcp"]
env = { DESKDOT_URL = "http://127.0.0.1:8765" }

Open an empty folder in Cursor, open the Agent chat and paste the prompt. Let it run terminal commands when it asks.
Register DeskDot's MCP server in .cursor/mcp.json in the project (or your user-level mcp.json), then enable it in Cursor's MCP settings.

.cursor/mcp.json

{
  "mcpServers": {
    "deskdot": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/deskdot", "deskdot-mcp"],
      "env": { "DESKDOT_URL": "http://127.0.0.1:8765" }
    }
  }
}

Any agent that can run terminal commands can follow the prompt: start it in an empty folder and paste.
Any MCP client can drive the panel. DeskDot's server speaks stdio; point your client at the command below. Claude Desktop uses this shape in claude_desktop_config.json.
Engine on another machine? Set DESKDOT_URL=http://<host>:8765 in the server's env.

stdio MCP server

{ "mcpServers": { "deskdot": { "command": "uv", "args": ["run", "--project", "/path/to/deskdot", "deskdot-mcp"] } } }

Config formats for third-party agents change over time; if a key is rejected, check that agent's MCP docs. The command itself (uv run --project … deskdot-mcp) is always the same.

Then

Things to ask once it's connected

“Show the weather, then a clock”

The agent calls show_app and checks the result with panel_snapshot.

“Draw a pixel-art rocket”

It draws pixel by pixel, looks at the snapshot and fixes anything that reads badly at 32×32.

“Ping me when the build passes”

Notifications slide over whatever is on screen, then the panel goes back to its app.

Pick an app to try Prefer doing it by hand?