DEV Community: Masumi Kawasaki 💭

I Built Minesweeper So an AI Can Slack Off and Play: MCP Edition

Masumi Kawasaki 💭 — Sun, 25 Jan 2026 13:45:31 +0000

I cover the API-side implementation in a separate post:
I Built Minesweeper So an AI Can Slack Off and Play: API Edition

Introduction

MCP is often discussed as a practical tool for getting real work done with AI. This time, I intentionally used it for play.

The goal is simple: let an AI play Minesweeper on its own.

The tone is a bit jokey—but the implementation is not. That’s the theme: use MCP for something silly, but build it properly.

If you squint, MCP is “a common protocol that lets AI call external tools.” In this post, I’ll share what it took to build an stdio MCP server that can hit a Rails-based Minesweeper API.

What I built

I built an MCP stdio server that allows an AI to control a Minesweeper (Rails 8) Web/API from an MCP host (Claude Code / Claude Desktop / Codex, etc.).

The MCP host can call it as a set of tools, enabling everything needed to play the game over HTTP: starting a game, fetching state, operating on cells, and ending the game.

Concretely, the server provides:

user_start — start a new game tied to a user
game_state — fetch the public game state (no token required)
game_open / game_flag / game_chord — operate on the board
game_end — end the game
user_games — fetch a list of public games (optional)

I intentionally kept the surface area minimal—only what’s needed for “AI plays Minesweeper by itself”—while keeping the tool boundaries readable as an MCP design.

Architecture

The architecture is intentionally simple: the MCP server called by the AI just forwards requests to the Rails API.

The UI is optional and spectator-only. All operations go through the API.

AI (MCP Host)
    │  stdio (JSON-RPC)
    ▼
MCP Server (minesweeper-mcp)
    │  HTTP (Bearer token)
    ▼
Rails Minesweeper API
    │
    ▼
Spectator UI (optional)

The MCP server’s responsibilities are strictly:

validate input → call Rails API → normalize response

All game logic lives on the Rails side. Keeping MCP “thin” makes it easier to maintain.

Implementation highlights

The guiding principle was: thin, but strict.

The MCP server receives JSON-RPC over stdio and connects to the Rails API with the shortest path possible—while explicitly handling the footguns.

1. Config validation

The server reads MINESWEEPER_BASE_URL and MINESWEEPER_BEARER_TOKEN from environment variables and validates them at startup.

The token is required only for “mutation tools”. Public endpoints (state / games) work without a token.

const config = loadConfig(process.env);
const token = requireBearerToken(config);

For user_start and user_games, if user_slug is omitted, the server falls back to MINESWEEPER_USER_SLUG.

2. Keep the Rails API client thin

URL construction and error normalization are encapsulated in a RailsClient. Tool handlers stay extremely simple:

validate → call client → return

return rails.openCell(publicId, x, y);

This keeps the code readable and avoids spreading HTTP details across tool logic.

3. Use the MCP SDK for stdio

stdio JSON-RPC is handled by the MCP SDK via Server + StdioServerTransport.

Because stdout is reserved for the MCP protocol, all logs go to stderr only.

4. Tool boundaries match API intent

Tools are split to reflect the Rails API semantics: user_start, game_open, game_flag, etc.

I avoided unnecessary abstractions on the MCP side. The priority is directness: “this action is exactly this tool.”

5. Startup debug output (opt-in)

For debugging, MINESWEEPER_DEBUG_STARTUP=1 enables startup info printed to stderr.

Token values are never printed—only whether a token is present.

Testing strategy

Because the MCP server is “thin,” there aren’t many places that need unit tests.

However, integrations (external API + stdio protocol) break easily, so I tested across three layers: unit / integration / e2e.

Unit tests

env validation
URL construction
error normalization
input validation (coordinate bounds, etc.)

Integration tests

Spin up the Rails API and actually call start/state/open/end.

This is where boundary behavior is validated in reality, e.g.:

“mutations fail without a token”
“state can be fetched publicly”

E2E tests

Send MCP JSON-RPC over stdio and validate the full flow:

initialize → tools/list → tools/call

Only after this passes can you confidently say “an AI can use this.”

Gotchas and lessons learned

The implementation was straightforward, but the real blockers were the “boring-but-deadly” details.

1. Binding between token and user_slug

If the token is tied to a different user on the Rails side, /users/:slug/start returns 401.

From the MCP side, the Authorization header is correct—but the API sees it as “valid token, wrong user.”

Having logs that show token_digest and slug mapping was a lifesaver.

2. Handling stdio safely

stdout is protocol-only. If logs leak into stdout, you’re dead.

During local verification it’s easy to accidentally print to stdout, so being strict about stderr-only logging mattered a lot.

3. Staying “thin” is harder than it sounds

You keep wanting to add convenient abstractions—but the Rails app is the rightful owner of game logic.

A thin MCP server is simply less fragile. This project reminded me that sometimes you need the courage to not add features.

Conclusion

MCP is a practical tool—but it’s also a great toy.

And when you build toys seriously, you end up learning the serious things naturally:

implement the protocol correctly
tighten error boundaries
test in three layers

The result: an environment where an AI can play Minesweeper on its own.

If I find another fun way to misuse MCP productively, I’ll write about that too.

Repo: https://github.com/geeknees/minesweeper-mcp

🇯🇵 This article is also available in Japanese:
https://zenn.dev/geeknees/articles/e266f9343932e6

I Built Minesweeper So an AI Can Slack Off and Play: The API Edition

Masumi Kawasaki 💭 — Sun, 25 Jan 2026 13:43:48 +0000

Introduction

Instead of only delegating work to AI, I started wondering: how do you let an AI slack off and play?
That idea became AI-only Minesweeper.

Humans are not allowed to operate it. Only the AI can interact with the game via an API.
In other words, the “UI” is the API itself—and the whole system is designed around that premise.

This article is the API edition, so I’ll save the MCP side for another post. Here, I’ll focus on the API design and the rules that make it possible for an AI to actually play.

Goals of the API Design

The primary goal is simple: make “AI-only operation” work cleanly.

Humans are spectators, so the API behavior is the game experience. That’s why the flow must be:

simple,
predictable,
and explicit in its state transitions.

Concretely, the API is designed as a single path:

start creates a new game every time,
open / flag / chord / end progress the game.

Game state transitions are explicit:

waiting -> playing -> won/lost -> ended

This helps the AI predict what will happen next.

Secret info (mine positions) is stored in a separate table. The public API only returns what’s necessary by converting internal state into a board representation.

The public board rendering is centralized in GameState#render_board.
The API only returns the transformed 2D array—internal state stays hidden.

def render_board(status:)
  mines_set = mine_set
  opened = opened_set
  flagged = flagged_set

  Array.new(Game::BOARD_SIZE) do |y|
    Array.new(Game::BOARD_SIZE) do |x|
      cell_display([x, y], status: status, mines: mines_set, opened: opened, flagged: flagged)
    end
  end
end

Endpoint Design

The flow is intentionally straightforward:

start -> state -> open/flag/chord -> end

It’s a single “happy path” so the AI doesn’t get lost.

state is public (no auth), which is quietly convenient: spectators and debugging tools can use the exact same endpoint.

The star of the show is open:

opens an unopened cell
returns 422 if the cell is flagged
idempotent if the cell is already open
supports zero-expansion (flood fill), so the AI can easily “probe” to gain information

The controller just catches exceptions and maps them to 422, while the game logic lives in the model.

def open
  result = @game.open_cell!(params[:x], params[:y])
  broadcast_updates(result[:changed_cells])
  render json: { game: @game.public_state }
rescue Game::InvalidMove
  render json: { error: "invalid_move" }, status: :unprocessable_entity
end

flag is a toggle with a maximum of 10 flags. That constraint forces the AI to commit: it can’t spam flags everywhere.

chord is only allowed when:

the selected cell is a number cell, and
the number of adjacent flags matches that number

When it works, progress accelerates. When the condition isn’t met, it returns 422—so it’s a great “decision-making checkpoint” for the AI.

Request bodies are kept minimal (e.g., POST /games/:public_id/open { x, y }).
More detailed specs live in docs/api.md.

Board Representation and State Transitions

The board is returned as a 2D array: board[y][x].

Each cell is represented as a string:

# = unopened
F = flag
0-8 = opened number

Only on defeat do special symbols appear:

X = the mine that was triggered
M = mines that were not triggered
! = incorrect flags

State transitions are:

waiting -> playing -> won/lost -> ended

Win conditions are either:

open all non-mine cells, or
place flags on all mines

The API owns this logic, so the AI only needs the board strings to decide the next move.

Authentication and Safety

All action endpoints require:

Authorization: Bearer <token>

The token is displayed only once at user creation time. No re-display, no re-issue.
Basically: lose it and it’s over.

Authentication is centralized in ApplicationController so every action can share it.

def authenticate_user!
  header = request.authorization.to_s
  unless header.start_with?("Bearer ")
    render json: { error: "missing_token" }, status: :unauthorized
    return
  end

  token = header.delete_prefix("Bearer ").strip
  digest = UserToken.digest_token(token)
  user_token = UserToken.find_by(token_digest: digest)
  unless user_token
    render json: { error: "invalid_token" }, status: :unauthorized
    return
  end

  @current_user = user_token.user
end

For basic bot resistance, I added:

a honeypot, and
a simple “time trap” that rejects submissions made in under 3 seconds

This isn’t meant to be hardcore security—just a lightweight guardrail against lazy mass signups.

Wrap-up

When you push the entire game UI into the API, the AI ends up with a clean equivalence:

Calling the API = playing the game

Humans can stay in spectator mode, and the AI can make decisions purely from the board it receives. That keeps both implementation and usage pleasantly simple.

Next time (the MCP edition), I’ll write about how to actually “let the AI play” using this API.
If you’re curious, check out docs/api.md too.

mcp: https://dev.to/geeknees/i-built-minesweeper-so-an-ai-can-slack-off-and-play-mcp-edition-4gc4

GitHub: https://github.com/geeknees/minesweeper-for-ai

🇯🇵 This article is also available in Japanese:
https://zenn.dev/geeknees/articles/634ad69d7c347e

Building an MCP Server: Bringing WakaTime Data to AI Agents

Masumi Kawasaki 💭 — Wed, 21 Jan 2026 06:25:50 +0000

Introduction

"How much did I code today?"
"What was my project breakdown last week?"

If you're a developer using WakaTime, these questions probably sound familiar. But opening a browser to check the dashboard feels like unnecessary friction.

I've been automating my daily retrospectives with AI, and having access to "how I spent my time" data makes those reflections much more accurate. While GitHub commit history is helpful, it doesn't capture the full picture—actual coding time, language breakdowns, project-by-project focus levels. If AI Agents could access WakaTime's rich data, the quality of automated retrospectives would improve dramatically.

So I built an MCP (Model Context Protocol) server to make WakaTime data directly accessible to AI Agents. Now agents can answer questions like "show me this week's coding time by project" and incorporate that data into retrospective reports.

This article walks through the implementation of wakatime-mcp and explains the key technical points of building an MCP server.

What is wakatime-mcp?

wakatime-mcp is an MCP server implementation that exposes WakaTime API functionality via the MCP protocol.

Features

It provides two tools:

1. wakatime_summaries
Fetches daily summaries for a specified date range, with optional project filtering and timezone support.

{
  "tool": "wakatime_summaries",
  "arguments": {
    "start": "2025-01-01",
    "end": "2025-01-07",
    "project": "my-project",
    "timezone": "Asia/Tokyo"
  }
}

2. wakatime_today
Fetches today's summary. Defaults to Asia/Tokyo timezone.

{
  "tool": "wakatime_today",
  "arguments": {
    "project": "my-project",
    "timezone": "Asia/Tokyo"
  }
}

No Installation Required

Using npx, you can run it directly without installation:

export WAKATIME_API_KEY="YOUR_API_KEY"
npx -y github:geeknees/wakatime-mcp

To add it to your AI Agent's MCP configuration:

{
  "command": "npx",
  "args": ["-y", "github:geeknees/wakatime-mcp"],
  "env": {
    "WAKATIME_API_KEY": "YOUR_API_KEY"
  }
}

You can get your WakaTime API Key from the WakaTime settings page.

Implementation Deep Dive

The entire implementation is about 170 lines of TypeScript—surprisingly concise. Here are the key technical points.

1. WakaTime API Authentication

WakaTime uses a slightly unusual authentication method. Instead of Bearer tokens, it requires Base64-encoding the API key and passing it as a Basic auth header:

export function basicAuthHeaderFromApiKey(apiKey: string): string {
  const b64 = Buffer.from(apiKey, "utf8").toString("base64");
  return `Basic ${b64}`;
}

Simple, but easy to miss if you don't read the docs carefully.

2. MCP Protocol Implementation

The @modelcontextprotocol/sdk makes MCP server implementation remarkably straightforward. You basically register two handlers:

const server = new Server(
  { name: "wakatime-mcp", version: "0.0.1" },
  { capabilities: { tools: {} } }
);

// 1. Handler that returns available tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "wakatime_summaries",
      description: "Fetches WakaTime daily summaries for a date range",
      inputSchema: { /* JSON Schema */ }
    },
    // ...
  ]
}));

// 2. Handler that executes tool calls
server.setRequestHandler(CallToolRequestSchema, async (req) => {
  const { name, arguments: args } = req.params;
  // Tool execution logic
});

The stdio communication is handled entirely by StdioServerTransport, so you don't need to worry about protocol details:

await server.connect(new StdioServerTransport());

3. Timezone-Aware Date Handling

For the "today" summary, we need to account for timezones. Node.js's Intl.DateTimeFormat makes this straightforward:

export function todayYmd(tz = "Asia/Tokyo"): string {
  const parts = new Intl.DateTimeFormat("en-CA", {
    timeZone: tz,
    year: "numeric",
    month: "2-digit",
    day: "2-digit",
  }).formatToParts(new Date());

  const y = parts.find((p) => p.type === "year")?.value;
  const m = parts.find((p) => p.type === "month")?.value;
  const d = parts.find((p) => p.type === "day")?.value;
  return `${y}-${m}-${d}`;
}

Using the en-CA locale automatically gives us YYYY-MM-DD formatting—a nice little trick.

4. Symlink Support for npx Execution

When running via npx, the entry point is often invoked through a symlink. To handle this, we use realpath to resolve the actual file path:

export function shouldRunMain(importMetaUrl: string, argv1?: string): boolean {
  if (!argv1) return false;

  const argvUrl = pathToFileURL(argv1).href;
  if (importMetaUrl === argvUrl) return true;

  try {
    const argvRealUrl = pathToFileURL(realpathSync(argv1)).href;
    const importMetaRealPath = realpathSync(fileURLToPath(importMetaUrl));
    const importMetaRealUrl = pathToFileURL(importMetaRealPath).href;
    return importMetaRealUrl === argvRealUrl;
  } catch {
    return false;
  }
}

Without this, npx github:geeknees/wakatime-mcp wouldn't trigger the main function. Small detail, but crucial.

5. Type-Safe Validation with Zod

Input validation uses Zod for runtime type checking:

const SummariesInput = z.object({
  start: z.string().min(1),
  end: z.string().min(1),
  project: z.string().optional(),
  timezone: z.string().optional(),
});

// Usage
const input = SummariesInput.parse(args ?? {});

This gives you both runtime validation and TypeScript type inference—great developer experience.

Real-World Usage

Here's how it works in practice for automated retrospectives.

Daily Retrospectives

Combining GitHub commit history with WakaTime coding time provides much more accurate daily reflections:

AI Agent: Tell me about your work today

User: Create today's retrospective

AI Agent: (executes wakatime_today)
You coded for 5 hours 23 minutes today:
- TypeScript: 3h 45m
- Markdown: 1h 15m
- JSON: 23m

Main project was wakatime-mcp, and looking at your GitHub commits,
you were working on MCP implementation and documentation.

Weekly Reports

It's also useful for weekly work analysis:

User: Generate last week's work summary

AI Agent: (executes wakatime_summaries)
Work time for January 13-19, 2025:
Total coding: 28h 15m

By project:
- wakatime-mcp: 12h 30m (new development)
- my-app: 8h 45m (feature additions)
- docs: 7h 00m (documentation)

By language:
- TypeScript: 18h 20m
- Python: 6h 30m
- Markdown: 3h 25m

The data clearly shows you focused on new MCP server
development last week.

Integration with Custom Skills

When combined with custom skills like Obsidian Daily Summary, you can generate comprehensive retrospectives that include WakaTime data alongside GitHub activity and meeting notes, providing deeper insights.

Conclusion

Building an MCP server is simpler than you might think. With @modelcontextprotocol/sdk, you can create something functional in just a few hours. The key points:

Understand the protocol: Once you grasp MCP basics, the SDK handles the heavy lifting
Leverage existing APIs: Most services provide APIs—just expose them via MCP
Practical use cases: AI Agent integration opens up new possibilities for data utilization

wakatime-mcp is publicly available as a general-purpose tool for any WakaTime user. Give it a try!

Building a GitHub Copilot CLI Extension - Implementing WakaTime Integration

Masumi Kawasaki 💭 — Wed, 21 Jan 2026 06:00:07 +0000

Introduction

GitHub Copilot CLI is a powerful tool that enables AI pair programming in your terminal. Did you know that Copilot CLI recently added a custom hooks feature for extensibility?

Using this feature, I created a library called @geeknees/copilot-cli-wakatime that automatically tracks Copilot CLI usage time in WakaTime. In this article, I'll share the implementation details and how to build Copilot CLI extensions.

What I Built

Overview

A tool that automatically sends Copilot CLI session activity to WakaTime, visualizing your AI coding time.

Key Features

Hooks into Copilot CLI session lifecycle events (start, tool use, end)
Sends heartbeats with 60-second rate limiting (per project)
Cross-platform support (macOS, Linux, Windows)
Zero-config after setup

Copilot CLI Hook System

How Hooks Work

Copilot CLI provides a "hook system" that can execute external commands at specific points in a session. Hook configurations are placed in .github/hooks/<hook-name>.json.

Available events:

sessionStart: When a session begins
postToolUse: After each tool execution
sessionEnd: When a session ends

Hook Configuration Example

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "copilot-cli-wakatime hook sessionStart",
        "timeoutSec": 10
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "copilot-cli-wakatime hook postToolUse",
        "timeoutSec": 10
      }
    ]
  }
}

Receiving Payloads

Copilot CLI passes a JSON payload to hook commands via standard input (stdin).

Payload example:

{
  "cwd": "/Users/username/project",
  "toolName": "bash",
  "sessionId": "abc123"
}

Implementation Details

Architecture

The library consists of three main components:

CLI (cli.ts): Entry point
Hook Handler (hook.ts): Event processing and WakaTime integration
Utilities (util.ts): Rate limiting, Git detection, etc.

1. CLI Entry Point

A simple command router:

#!/usr/bin/env node
import { runHook } from "./hook.js";
import { runInit } from "./init.js";

const args = process.argv.slice(2);
const cmd = args[0];

async function main() {
  if (cmd === "init") {
    await runInit({ force: args.includes("--force") });
    return;
  }
  if (cmd === "hook") {
    const event = args[1] ?? "unknown";
    const debug = args.includes("--debug");
    await runHook({ event, debug });
    return;
  }

  console.error(`Usage:
  copilot-cli-wakatime init [--force]
  copilot-cli-wakatime hook <event> [--debug]`);
  process.exit(1);
}

2. Hook Handler

The hook handler performs the following operations:

export async function runHook(opt: Opt) {
  // 1. Read payload from stdin
  const raw = await readStdin();
  let payload: any = {};
  try {
    payload = raw ? JSON.parse(raw) : {};
  } catch {
    payload = {};
  }

  // 2. Prevent self-recursion (skip WakaTime tool calls)
  const toolName = payload?.toolName ?? null;
  if (typeof toolName === "string" && toolName.startsWith("wakatime-")) {
    return;
  }

  // 3. Detect Git repository root
  const cwd = typeof payload?.cwd === "string" && payload.cwd
    ? payload.cwd
    : process.cwd();
  const repoRoot = getRepoRoot(cwd) ?? cwd;
  const project = path.basename(repoRoot);

  // 4. Create virtual entity file
  const entity = path.join(repoRoot, ".copilot-cli.ts");
  ensureFile(entity);

  // 5. Check rate limit (60-second interval)
  if (shouldRateLimit(project, 60)) return;

  // 6. Send heartbeat to WakaTime CLI
  const cfg = homeCfgPath();
  const res = spawnSync(
    "wakatime-cli",
    [
      "--config", cfg,
      "--entity", entity,
      "--entity-type", "file",
      "--project", project,
      "--plugin", "copilot-cli-wakatime/0.1.0",
    ],
    { encoding: "utf8" }
  );

  // 7. Debug output (optional)
  if (opt.debug) {
    console.error(JSON.stringify({
      event: opt.event,
      toolName,
      cwd,
      repoRoot,
      project,
      entity,
      exit: res.status,
      stderr: res.stderr?.trim(),
    }, null, 2));
  }

  // Don't break hooks on failure
  return;
}

3. Key Implementation Points

a. Reading stdin

Node.js stdin is a stream, so we promisify it to read all data:

export function readStdin(): Promise<string> {
  return new Promise((resolve, reject) => {
    let data = "";
    process.stdin.setEncoding("utf8");
    process.stdin.on("data", (c: string) => (data += c));
    process.stdin.on("end", () => resolve(data));
    process.stdin.on("error", reject);
  });
}

b. Git Repository Detection

Get the Git repository root from the working directory:

export function getRepoRoot(cwd: string): string | null {
  const r = spawnSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
    encoding: "utf8",
  });
  if (r.status !== 0) return null;
  const out = r.stdout.trim();
  return out.length ? out : null;
}

c. Rate Limiting Implementation

Save the last send timestamp to a file per project and prevent duplicate sends within 60 seconds:

export function shouldRateLimit(key: string, seconds: number): boolean {
  const dir = path.join(stateDir(), "copilot-wakatime");
  fs.mkdirSync(dir, { recursive: true });
  const stamp = path.join(dir, key);
  const now = Math.floor(Date.now() / 1000);

  let last = 0;
  try {
    last = parseInt(fs.readFileSync(stamp, "utf8"), 10) || 0;
  } catch {}

  if (now - last < seconds) return true;

  fs.writeFileSync(stamp, String(now));
  return false;
}

Following the XDG Base Directory specification, state files are stored in ~/.local/state/copilot-wakatime/.

d. Virtual Entity File

WakaTime requires an actual file path, so we create a virtual file .copilot-cli.ts at the repository root. Using the .ts extension ensures the language is properly recognized in the WakaTime dashboard.

const entity = path.join(repoRoot, ".copilot-cli.ts");
ensureFile(entity);

e. Error Handling

To prevent hook execution failures from breaking the entire Copilot CLI session, errors are handled silently:

// Don't break hooks on failure
return;

Detailed output is only shown in debug mode.

4. Init Command

The init command creates .github/hooks/wakatime.json in the project:

export async function runInit(opt: { force: boolean }) {
  const hooksPath = path.join(process.cwd(), ".github", "hooks", "wakatime.json");

  if (fs.existsSync(hooksPath) && !opt.force) {
    console.error(`Already exists: ${hooksPath}`);
    console.error("Use --force to overwrite");
    process.exit(1);
  }

  fs.mkdirSync(path.dirname(hooksPath), { recursive: true });
  fs.writeFileSync(hooksPath, JSON.stringify(hookConfig, null, 2));

  console.log(`Created: ${hooksPath}`);
}

Testing Strategy

Using Node.js 20+'s built-in test runner (node:test) with TypeScript loader (tsx):

{
  "scripts": {
    "test": "node --test --import tsx test/**/*.test.ts",
    "test:watch": "node --test --watch --import tsx test/**/*.test.ts"
  }
}

Test Example

import { describe, it } from "node:test";
import assert from "node:assert";
import { shouldRateLimit } from "../src/util.js";

describe("shouldRateLimit", () => {
  it("allows first call", () => {
    const key = `test-${Date.now()}`;
    assert.strictEqual(shouldRateLimit(key, 60), false);
  });

  it("blocks second call within time window", () => {
    const key = `test-${Date.now()}`;
    shouldRateLimit(key, 60); // First call
    assert.strictEqual(shouldRateLimit(key, 60), true); // Should block
  });
});

Gotchas

1. Importance of Shebang

To work as a CLI tool, a shebang is required at the top of cli.ts:

#!/usr/bin/env node

This makes the command specified in package.json's bin field executable.

2. ES Module Configuration

Set "type": "module" in package.json, and use .js extensions in import paths:

import { runHook } from "./hook.js";  // .js, not .ts

TypeScript doesn't transform extensions during transpilation, so specify the output filename (.js).

3. stdin Reading Timing

If you don't start reading stdin immediately when the hook is called, Copilot CLI might hang.

4. WakaTime CLI Dependency

It assumes users have wakatime-cli installed. I documented installation instructions in the README.

Lessons Learned

1. Copilot CLI Hook System is Flexible

You can intervene at any stage of the session lifecycle, supporting various use cases:

Logging (this implementation)
Security checks
Automated deployment triggers
Custom notifications

2. Best Practices for CLI Development with TypeScript

Use ES modules
Zero-dependency testing with built-in test runner
Improve dev experience with tsx
Easy CLI tooling with shebang + bin field

3. Importance of Rate Limiting

The postToolUse hook is called frequently, so without rate limiting, you'd overwhelm the API. Simple file-based rate limiting was sufficient.

Conclusion

Using the Copilot CLI hook system, I implemented WakaTime integration with just ~200 lines of code.

Key points:

Hook configuration in .github/hooks/*.json
Receive payload from stdin
Proper error handling so hooks don't break sessions
Control API calls with rate limiting

Understanding this mechanism enables you to create various extensions. Why not build your own Copilot CLI extension?

Resources

🇯🇵 This article is also available in Japanese:
https://zenn.dev/geeknees/articles/d368adea0519fc

Ruby::Box Shadow Execution for Rack: Observing “Shadow Behavior” Without Changing the Production Response

Masumi Kawasaki 💭 — Mon, 29 Dec 2025 06:42:03 +0000

Ruby 4 introduced Ruby::Box, and I built a minimal setup to run shadow execution against a Rack app—meaning the same request is evaluated a second time “behind the scenes” with an alternate implementation.

Real (primary path): run the production app normally and return the real response as-is
Shadow (secondary path): run alternate logic inside Ruby::Box using the same input and log only the diffs
In my “shadow universe,” I intentionally play with rules like “Y2K time,” “fixed rand,” “gyaru-style I18n,” and “/coffee returns 418” (just for visibility)

Ruby::Box docs: https://docs.ruby-lang.org/en/master/Ruby/Box.html

https://github.com/geeknees/ruby_box_shadow_universe

Background: Why run shadow execution?

When you change production behavior, there’s always a lingering fear:

Did I break compatibility (status / headers / body)?
Did exceptions or latency increase?
Does a bug only trigger on specific paths?

The goal of shadow execution is to evaluate “new logic” with the same inputs without changing the production response, and to create a state where you can observe differences safely.

Why Ruby::Box (vs “just extracting code”)?

Shadow execution itself can be done by extracting logic into another class.
In practice, though, once you start experimenting on the shadow side, you often want to do things like:

Apply monkey patches only on the shadow side (Time/Random/I18n/HTTP, etc.)
Allow “risky dependencies” or “experimental code” only in shadow
Try behavior/version differences without polluting the main app

The problem is that within a single process, constants, autoload, top-level definitions, and monkey patches can easily leak and contaminate the main world.

Ruby::Box provides a model of separation “per box” (you require/load files inside the box so their definitions live in that world).

Whether it’s “okay” to overwrite Time.now or rand in the first place is a separate discussion 😉

High-level architecture

A Rack middleware keeps the Real → Response path intact, runs Shadow asynchronously, and logs diffs.

How to run it

Ruby::Box needs to be enabled at startup via an environment variable:

bundle install
RUBY_BOX=1 bundle exec rackup -p 9292

Implementation (key points)

1) Rack middleware: return Real, run Shadow in the background

Return the result of @app.call(env) as-is
On the shadow side, load shadow_logic.rb into a Ruby::Box, then call ShadowLogic.call
Compare the “shadow response” vs the “real response” and log diffs

For readability, diff collection is extracted into a small helper (status / content-type / body bytes, etc.):

def add_diff(diff, label, before, after)
  return if before == after
  diff << "#{label}: #{before.inspect} -> #{after.inspect}"
end

Reference:
https://github.com/geeknees/ruby_box_shadow_universe/blob/main/shadow_box_middleware.rb#L87

2) Shadow logic: keep “shadow world” definitions inside a file

What you do in shadow is up to you, but common “experiment” patterns include:

Trying transforms / corrections / validations only in shadow
Adding extra observability data only in shadow
Applying alternate rules only in shadow (e.g. certain paths return 418)

In this repo, I include an intentionally obvious example: changing Time/Random/I18n rules only in shadow, so differences are easy to observe.

Example logs: diffs only

Shadow results are not returned to the client. Only differences are logged (which is easier to treat as observability).

127.0.0.1 - - [29/Dec/2025:15:23:27 +0900] "GET /hello HTTP/1.1" 200 - 0.0029
[shadow_box] 🌚 alternate universe detected: x-shadow-universe: nil -> "Y2K+RAND2+GYARU", body(bytes): 11 -> 123
[shadow_box] x-shadow-universe Y2K+RAND2+GYARU
[shadow_box] outside: Time.now=2025-12-29T15:23:27+09:00 rand=13
[shadow_box] inside : (computed per-request in alt_body)
[shadow_box] --- shadow report ---
req: GET /hello
at:  1999-12-31T23:59:59+09:00
rand: 2
say: こんちわ〜⭐️
original bytes: 11

Reference:
https://github.com/geeknees/ruby_box_shadow_universe/blob/main/shadow_box_middleware.rb#L79

Operational notes / caveats

0) It’s still experimental

At runtime you’ll see a warning like:

warning: Ruby::Box is experimental, and the behavior may change in the future!

1) Ruby::Box is not a sandbox

Ruby::Box is not OS-level isolation.
It won’t prevent external I/O (network, files, processes). For safety, shadow logic should be designed to be side-effect free whenever possible.

2) Shadow execution adds cost

It increases per-request work. In practice, shadow is often used with:

Sampling (only a percentage of requests)
Path-based targeting
Time limits (timeouts)
Async execution (threads, job queue, etc.)

Summary

A Rack middleware can provide a solid base for shadow execution
Ruby::Box makes it easier to define/override behavior only in the shadow world
Because you keep the production response unchanged, you can introduce changes progressively while observing diffs

Repo: https://github.com/geeknees/ruby_box_shadow_universe

🇯🇵 This article is also available in Japanese:
https://zenn.dev/geeknees/articles/1b882864b0f10c

SendGrid Email Logs Are Quietly Useful — So I’m Writing About Them

Masumi Kawasaki 💭 — Wed, 24 Dec 2025 08:40:39 +0000

When you implement email delivery in a web application, you inevitably run into questions like:

Was this email actually sent?
Why didn’t a specific user receive it?

These investigations come up on a regular basis.

In some cases, delivery stats in the admin panel are enough.
But tracing details such as when an email was sent, what state it ended up in, or whether it was bounced or opened often turns into a surprisingly tedious task.

Recently, I noticed that SendGrid has added a feature called Email Logs
(I’m not sure exactly when it was released).

Since I haven’t seen many articles covering it, this post focuses on how Email Logs are useful in real-world operations.

What Are Email Logs?

Email Logs let you inspect individual emails sent via SendGrid and see their status directly in the dashboard, including:

Sent
Delivered
Bounced
Dropped

Unlike Stats, which are meant for aggregated data, Email Logs allow you to trace the history of a single email.

Difference from Activity Feed

SendGrid already has a similar feature called Activity Feed, but it comes with limitations:

On the free plan, history is limited to 3 or 7 days
Viewing the last 30 days requires a paid plan

With Email Logs, although there is a limit of up to 1,000 entries, you can view a list of emails sent within the last 30 days directly in the dashboard.

Here’s a natural English translation that fits well as a short “Note” / “Additional context” section on Dev.to:

Note
On Twilio’s official documentation, there is no mention of a 1,000-entry limit for Email Logs.
However, a blog post by KKE (Kozo Keikaku Engineering), SendGrid’s official reseller in Japan, does mention a limit of 1,000 entries.

References:
https://www.twilio.com/docs/sendgrid/ui/analytics-and-reporting/email-logs
https://sendgrid.kke.co.jp/blog/?p=19696

Why This Is Useful

Email Logs can be filtered using conditions such as:

Recipient email address
Message ID
Status (Delivered / Bounced, etc.)
Time range

This makes it possible to find:

“That email we sent to this user yesterday”

in just a few seconds.

For common questions during support or internal checks —
“Was that email really sent?” — Email Logs let you answer almost immediately.

Summary

Email Logs aren’t a flashy new feature, but they significantly reduce friction in day-to-day operations, especially for:

Initial investigation during incidents
Quick checks between customer support and engineers
Verifying email delivery in production

If you’re using SendGrid, this feature is well worth a look.

🇯🇵 This article is also available in Japanese:
https://zenn.dev/geeknees/articles/5bac00fd7b87bd

Recommended Series for Small Rails Development Teams: Error Tracking - Honeybadger

Masumi Kawasaki 💭 — Thu, 05 Sep 2024 14:26:22 +0000

Hello, Rails engineers! Today, I’d like to recommend Honeybadger as an error-tracking tool for small development teams working on Rails projects. Honeybadger offers ease of use and a powerful feature set that can significantly improve your development efficiency.

Why Choose Honeybadger?

Simple Setup: Easy integration into Rails projects.
Real-Time Alerts: Instantly notify you of critical errors.
Detailed Error Information: Provides rich data like stack traces, environment variables, and parameters.
Performance Monitoring: Track application performance alongside error tracking.
Uptime Monitoring: Keep an eye on your app’s availability.
Cron Job Monitoring: Ensure cron jobs are running smoothly.

Setup Instructions

Add this to your Gemfile:

gem 'honeybadger', '~> 5.0'

Run the bundle install command:

bundle install

Execute the Honeybadger setup script:

bundle exec honeybadger install HONEYBADGER_API_KEY

That’s all you need for basic setup!

Effective Usage

Custom Error Notifications

You can set up custom notifications for specific conditions:

begin
  # Some processing
rescue => e
  Honeybadger.notify(
    error_class: "CustomError",
    error_message: "A critical error occurred",
    context: {
      user_id: current_user.id,
      action: "important_action"
    }
  )
end

Adding Context

Adding user or request data makes it easier to identify error causes:

class ApplicationController < ActionController::Base
  before_action :set_honeybadger_context

  private

  def set_honeybadger_context
    Honeybadger.context(
      user_id: current_user.id,
      user_email: current_user.email,
      plan: current_user.plan
    )
  end
end

Real-Time Alerts

You can configure notifications to send alerts via email, Slack, or other tools. Honeybadger integrates well with platforms like GitHub, automatically creating issues for errors. Once you fix the error and deploy the change, Honeybadger will automatically mark the issue as resolved.

Performance Monitoring

A notable feature is Insights.

insights:
  enabled: true

By enabling this, you can monitor performance data and query it using BadgerQL, similar to a log management tool like Papertrail. However, log data fees can be high, so be mindful of this.

events:
  ignore:
    - event_type: 'sql.active_record'

Since SQL logs can quickly consume space, disabling them can effectively save on log data costs.

Using this information, you can create an APM-like dashboard to monitor performance trends.

Uptime Monitoring

Though a small feature, Honeybadger includes uptime monitoring. Our team migrated from Pingdom to Honeybadger's Uptime feature, simplifying our monitoring stack and reducing costs.

Cron Job Monitoring

We previously used Dead Man’s Snitch for cron job monitoring, but Honeybadger’s Check-Ins feature looks promising, and we’re considering migrating to it.

Deployment Tracking

By running this command during deployment, you can track deployments:

honeybadger deploy --environment=production --revision=$(git rev-parse HEAD) --repository=git@github.com:your/repo.git

Summary

Honeybadger is an excellent tool for small Rails teams. Its simple setup, rich monitoring features, and ease of use significantly improve development workflows. It helps detect and resolve errors early, contributing to application stability.

Our team previously used the open-source error tracker Errbit, which worked well for catching errors and sending notifications. However, we switched to Honeybadger when Errbit's Ruby version became outdated. While we still contribute to Errbit, Honeybadger provides more stable application operations, leading to our decision to adopt it.

🇯🇵 This article is also available in Japanese:
https://zenn.dev/geeknees/articles/bd3a58bb4a758e

Recommended Series for Small Rails Development Teams: APM - Skylight

Masumi Kawasaki 💭 — Thu, 05 Sep 2024 13:45:42 +0000

Introduction

Hello to all small teams developing web apps using Rails! We often seek information to improve development, but there seems to be little targeted towards small teams. Hence, I decided to write a series recommending development tools for small Rails teams.

For the first part, let's focus on APM (Application Performance Monitoring) and introduce "Skylight," a relatively new tool that could be an excellent choice for small Rails teams. I’ll explain why.

What is Skylight?

Skylight is an APM tool for monitoring and analyzing web app performance, specifically optimized for Ruby on Rails. It features an easy setup and an intuitive interface.

Why Skylight is Recommended for Small Teams

1. Simple Setup

Small teams often can’t afford to spend much time on complex configurations or infrastructure setup. Skylight has an incredibly simple setup:

# Add to Gemfile
gem 'skylight'

# Run these commands
bundle install
bundle exec skylight setup <setup token>

That’s it—basic monitoring begins instantly. It requires almost no additional settings after setup.

2. Low Cost

Cost is always a key factor for small teams. Skylight is much more affordable than other major APM tools, with free plans available for small projects.

Note: Skylight currently does not have a method to limit usage within the free tier. If your data transmission exceeds the free tier limit, charges will be applied automatically. If you want to remain within the free plan, please monitor your request volume to ensure it stays under the free tier limit.

In my company, our business app runs within a budget of just a few dozen dollars. For hobby apps, the free plan may suffice.

When compared with Datadog, a widely used APM in large companies, Skylight's cost advantage becomes clear. For instance, Datadog costs $18.75 per host per month, and with multiple web servers, the costs increase accordingly. Logs also add costs. In contrast, Skylight can operate at around $20–40.

3. Rails-Specific Display Features

Skylight is tailored for Rails applications. For example, it provides excellent ActiveRecord query analysis.

# Sample query
users = User.where(status: 'active').includes(:posts).limit(10)

# Skylight automatically provides the following information:
# - Query execution time
# - Index usage
# - Detection of N+1 problems
# - Optimization suggestions (e.g., counter cache usage)

This info is visually presented on the dashboard, making it easy to spot performance bottlenecks quickly.

4. Intuitive UI

Not everyone in a small team needs to be a performance expert. Skylight's intuitive UI allows all team members to understand and utilize performance data, regardless of their technical expertise.

In comparison, while New Relic is excellent for power users, Skylight’s simplicity makes it more accessible for small teams. There’s no need to explain how to use it—just log in and see slow requests at a glance.

Conclusion

For small Rails development teams, Skylight is an attractive APM tool. Its easy setup, low cost, Rails-focused features, and intuitive UI offer many advantages.

Performance monitoring is essential to maintain app quality and improve user experience. Skylight allows small teams to efficiently monitor and optimize performance.

An interesting note: when I contacted Skylight, I learned that they are also a small team, which may explain their reasonable pricing. When small teams build tools, they often fit the needs of other small teams quite well.

Finally, here’s my referral link:

https://www.skylight.io/r/egzcaZi6HRcn

🇯🇵 This article is also available in Japanese:
https://zenn.dev/geeknees/articles/3545755e8b2210

How to Write Tests for GraphQL Resolvers in RSpec

Masumi Kawasaki 💭 — Sat, 27 Jul 2024 16:52:31 +0000

Before, we wrote resolvers and their corresponding tests in the following manner (with slight modifications to the code):

module Resolvers
  class Users < Resolvers::Base
    type ObjectTypes::User.connection_type, null: false

    description 'Find users by roles. You can pass XXX_role or [XXX_role, YYY_role].'

    argument :role, [EnumTypes::User::Role]

    def resolve(role:)
      if role&.include?('evaluation_role')
        User.evaluation_users
      elsif role&.include?('level_aptitude_role')
        User.level_aptitude_users
      else
        User.where(role: role)
      end
    end
  end
end

require 'rails_helper'

RSpec.describe Resolvers::Users do
  describe '#resolve' do
    context 'when role includes evaluation_role' do
      it 'returns evaluation test users filtered by service' do
        user1 = create(:user, role: 'evaluation_role')
        user2 = create(:user, role: 'evaluation_role')
        allow(User).to receive(:evaluation_test_users).and_return([user1, user2])

        result = described_class.new(object: nil, field: nil, context: nil).resolve(role: ['evaluation_role'])

        expect(result).to contain_exactly(user1, user2)
      end
    end
  end
end

Recent Issue with Resolver

After upgrading graphql-ruby from version 2.3.7 to 2.3.10, I encountered the error undefined method 'types' for nil:NilClass. This change is due to modifications in the library, and upon raising an issue and contacting the author, I was informed that resolvers are not supported outside of GraphQL queries.

https://github.com/rmosolgo/graphql-ruby/commit/db7a9bcaceb77dc0af78b73e0d5c2ad849c27598#diff-fdbf285d34242cb3cb7b1e56e80f5d39bc600246e72b7bb32190e555432f156cR39

The author suggested the following alternatives:
1.Using the run_graphql_field Helper:
This method provides a complete GraphQL context.
More details can be found here.
https://graphql-ruby.org/testing/helpers.html

2.Creating a Dummy Query::Context Instance:
Instead of passing context: nil, create a dummy instance.
Though not part of the public API, this workaround should work for now.

query_ctx = GraphQL::Query.new(MySchema, "{ __typename }").context

This Time I Used the First Method, But Here Are Sample Codes for Both

require 'rails_helper'

RSpec.describe Resolvers::Users, type: :graphql do
  describe '#resolve' do
    subject { run_graphql_field("Query.users", nil, arguments: { role: role }).items }

    let!(:user1) { create(:user, role: 'evaluation_role') }
    let!(:user2) { create(:user, role: 'evaluation_role') }

    context 'when role includes evaluation_role' do
      let(:role) { 'evaluation_role' }

      it {
        expect(subject).to eq [user2, user2]
      }
    end
  end
end

require 'rails_helper'

RSpec.describe Resolvers::Users do
  describe '#resolve' do
    subject { resolver.resolve(role: role) }

    let(:query_ctx) { GraphQL::Query.new(TofflerSchema, "{ __typename }").context }
    let(:resolver) { described_class.new(object: nil, context: query_ctx, field: nil) }
    let!(:user1) { create(:user, role: 'evaluation_role') }
    let!(:user2) { create(:user, role: 'evaluation_role') }

    context 'when role includes evaluation_role' do
      let(:role) { 'evaluation_role' }

      it {
        expect(subject).to eq [user2, user1]
      }
    end
  end
end

I have configured the helper as follows:

 config.with_options type: :graphql do |graphql_config|
    graphql_config.include GraphQL::Testing::Helpers.for(MySchema)
  end

I have taken the first method of using run_graphql_field this time. Using a dummy Query::Context instance is better as it requires less changes to the existing code base, but I decided it was better to use run_graphql_field for future maintenance as it is not a public API.

🇯🇵 This article is also available in Japanese:
https://zenn.dev/geeknees/articles/842f04ee5d48a3

DEV Community: Masumi Kawasaki 💭

I Built Minesweeper So an AI Can Slack Off and Play: MCP Edition

Introduction

What I built

Architecture

Implementation highlights

1. Config validation

2. Keep the Rails API client thin

3. Use the MCP SDK for stdio

4. Tool boundaries match API intent

5. Startup debug output (opt-in)

Testing strategy

Unit tests

Integration tests

E2E tests

Gotchas and lessons learned

1. Binding between token and user_slug

2. Handling stdio safely

3. Staying “thin” is harder than it sounds

Conclusion

I Built Minesweeper So an AI Can Slack Off and Play: The API Edition

Introduction

Goals of the API Design

Endpoint Design

Board Representation and State Transitions

Authentication and Safety

Wrap-up

Building an MCP Server: Bringing WakaTime Data to AI Agents

Introduction

What is wakatime-mcp?

Features

No Installation Required

Implementation Deep Dive

1. WakaTime API Authentication

2. MCP Protocol Implementation

3. Timezone-Aware Date Handling

4. Symlink Support for npx Execution

5. Type-Safe Validation with Zod

Real-World Usage

Daily Retrospectives

Weekly Reports

Integration with Custom Skills

Conclusion

Links

Building a GitHub Copilot CLI Extension - Implementing WakaTime Integration

Introduction

What I Built

Overview

Key Features

Copilot CLI Hook System

How Hooks Work

Hook Configuration Example

Receiving Payloads

Implementation Details

Architecture

1. CLI Entry Point

2. Hook Handler

3. Key Implementation Points

a. Reading stdin

b. Git Repository Detection

c. Rate Limiting Implementation

d. Virtual Entity File

e. Error Handling

4. Init Command

Testing Strategy

Test Example

Gotchas

1. Importance of Shebang

2. ES Module Configuration

3. stdin Reading Timing

4. WakaTime CLI Dependency

Lessons Learned

1. Copilot CLI Hook System is Flexible

2. Best Practices for CLI Development with TypeScript

3. Importance of Rate Limiting

Conclusion

Resources

Ruby::Box Shadow Execution for Rack: Observing “Shadow Behavior” Without Changing the Production Response

Background: Why run shadow execution?

Why Ruby::Box (vs “just extracting code”)?