DEV Community: Rizèl Scarlett

8 Things You Didn't Know About Code Mode

Rizèl Scarlett — Thu, 19 Feb 2026 06:54:38 +0000

Agents fundamentally changed how we program. They enable developers to move faster by disintermediating the traditional development workflow. This means less time switching between specialized tools and fewer dependencies on other teams. Now that agents can execute complicated tasks, developers face a new challenge: using them effectively over long sessions.

The biggest challenge is context rot. Because agents have limited memory, a session that runs too long can cause them to "forget" earlier instructions. This leads to unreliable outputs, frustration, and subtle but grave mistakes in your codebase. One promising solution is Code Mode.

Instead of describing dozens of separate tools to an LLM, Code Mode allows an agent to write code that calls those tools programmatically, reducing the amount of context the model has to hold at once. While many developers first heard about Code Mode through Cloudflare's blog post, fewer understand how it works in practice.

I have been using Code Mode for a few months and recently ran a small experiment. I asked goose to fix its own bug where the Gemini model failed to process images in the CLI but worked in the desktop app, then open a PR. The fix involved analyzing model configuration, tracing image input handling through the pipeline, and validating behavior across repeated runs. I ran the same task twice: once with Code Mode enabled and once without it.

Here is what I learned from daily use and my experiment.

1. Code Mode is Not an MCP-Killer

In fact, it uses MCP under the hood. MCP is a standard that lets AI agents connect to external tools and data sources. When you install an MCP server in an agent, that MCP server exposes its capabilities as MCP tools. For example, goose's primary MCP server called the developer extension exposes tools like shell enabling goose to run commands and text_editor, so goose can view and edit files.

Code Mode wraps your MCP tools as JavaScript modules, allowing the agent to combine multiple tool calls into a single step. Code Mode is a pattern for how agents interact with MCP tools more efficiently.

2. goose Supports Code Mode

Code Mode support landed in goose v1.17.0 in December 2025. It ships as a platform extension called "Code Mode" that you can enable in the desktop app or CLI.

To enable it:

Desktop app: Click the extensions icon and toggle on "Code Mode"
CLI: Run goose configure and enable the Code Mode extension

Since its initial implementation, we've added so many improvements!

3. Code Mode Keeps Your Context Window Clean

Every time you install an MCP server (or "extension" in the goose ecosystem), it adds a significant amount of data to your agent's memory. Every tool comes with a tool definition describing what the tool does, the parameters it accepts, and what it returns. This helps the agent understand how to use the tool.

These definitions consume space in your agent's context window. For example, if a single definition takes 500 tokens and an extension has five tools, that is 2,500 tokens gone before you even start. If you use multiple extensions, you could easily double or even decuple that number.

Without Code Mode, your context window could look like this:

[System prompt: ~1,000 tokens]
[Tool: developer__shell - 500 tokens]
[Tool: developer__text_editor - 600 tokens]
[Tool: developer__analyze - 400 tokens]
[Tool: slack__send_message - 450 tokens]
[Tool: slack__list_channels - 400 tokens]
[Tool: googledrive__search - 500 tokens]
[Tool: googledrive__download - 450 tokens]
... and so on for every tool in every extension

As your session progresses, useful context gets crowded out by tool definitions you aren't even using: the code you are discussing, the problem you are solving, or the instructions you previously gave. This leads to performance degradation and memory loss. While I used to recommend disabling unused MCP servers, Code Mode offers a better fix. It uses three tools that help the agent discover what tools it needs on demand rather than having every tool definition loaded upfront:

search_modules - Find available extensions
read_module - Learn what tools an extension offers
execute_code - Run JavaScript that uses those tools

I wanted to see how true this was so I ran an experiment: I had goose solve a user's bug and put up a PR with and without code mode. Code Mode used 30% fewer tokens for the same task.

Metric	With Code Mode	Without Code Mode
Total tokens	23,339	33,648
Input tokens	23,128	33,560

4. Code Mode Batches Operations Into a Single Tool Call

The token savings do not just come from loading fewer tool definitions upfront. Code Mode also handles the "active" side of the conversation through a method called batching.

When you ask an agent to do something, it typically breaks your request into individual steps, each requiring a separate tool call. You can see these calls appear in your chat as the agent executes the tasks. For example, if you ask goose to "check the current branch, show me the diff, and run the tests," it might run four individual commands:

▶ developer__shell → git branch --show-current

▶ developer__shell → git status

▶ developer__shell → git diff

▶ developer__shell → cargo test

Each of these calls adds a new layer to the conversation history that goose has to track. Batching combines these into a single execution. When you turn Code Mode on and give that same prompt, you will see just one tool call:

▶ Code Execution: Execute Code
  generating...

Inside that one execution, it batches all the commands into a script:

import { shell } from "developer";

const branch = shell({ command: "git branch --show-current" });
const status = shell({ command: "git status" });
const diff = shell({ command: "git diff" });
const tests = shell({ command: "cargo test" });

As a user, you see the same results, but the agent only has to remember one interaction instead of four. By reducing these round trips, Code Mode keeps the conversation history concise so the agent can maintain focus on the task at hand.

5. Code Mode Makes Smarter Tool Choices

When an agent has access to dozens of tools, it sometimes makes a "logical" choice that is technically wrong for your environment. This happens because, in a standard setup, the agent picks tools from a flat list based on short text descriptions. This can lead to a massive waste of time and tokens when the agent picks a tool that sounds right but lacks the necessary context.

I saw this firsthand during my experiments. I had an extension enabled called agent-task-queue, which is designed to run background tasks with timeouts.

When I asked goose to run the tests for my PR, it looked at the available tools and saw agent-task-queue. The LLM reasoned that a test suite is a "long-running task," making that extension a perfect fit. It chose the specialized tool over the generic shell.

However, the tool call failed immediately:

FAILED exit=127 0.0s
/bin/sh: cargo: command not found

My environment was not configured to use that specific extension for my toolchain. goose made a reasonable choice based on the description, but it was the wrong tool for my actual setup.

In the Code Mode session, this mistake never happened. Code Mode changes how the agent interacts with its capabilities by requiring explicit import statements.

Instead of browsing a menu of names, goose had to be intentional about which module it was using. It chose to import from the developer module:

import { shell } from "developer";

const test = shell({ command: "cargo test -p goose --lib formats::google" });

By explicitly importing developer, Code Mode ensured the tests ran in my actual shell environment.

6. Code Mode Is Portable Across Editors

goose is more than an agent; it's also an ACP (Agent Client Protocol) server. This means you can connect it to any editor that supports ACP, like Zed or Neovim. Plus, any MCP server you use in goose will work there, too.

I wanted to try this myself, so I set up Neovim to connect to goose with Code Mode enabled. Here's the configuration I used:

{
  "yetone/avante.nvim",
  build = "make",
  event = "VeryLazy",
  opts = {
    provider = "goose",
    acp_providers = {
      ["goose"] = {
        command = "goose",
        args = { "acp", "--with-builtin", "code_execution,developer" },
      },
    },
  },
  dependencies = {
    "nvim-lua/plenary.nvim",
    "MunifTanjim/nui.nvim",
  },
}

The key line is the one where I enable Code Mode right inside the editor config:

args = { "acp", "--with-builtin", "code_execution,developer" },

To test it, I asked goose to list my Rust files and count the lines of code. Instead of a long stream of individual shell commands cluttering my Neovim buffer, I saw one singular tool call: Code Execution. It worked exactly like it does in the desktop app. This portability means you can build a powerful, efficient agent workflow and take it with you to whatever environment you're most comfortable in.

7. Code Mode Performs Differently Across LLMs

I ran my experiments using Claude Opus 4.5. Your results may vary depending on which model you use.

Code Mode requires the LLM to do things that not all models do equally well:

Write valid JavaScript - The model has to generate syntactically correct code. Models with stronger code generation capabilities will produce fewer errors.
Follow the import pattern - Code Mode expects the LLM to import tools from modules like import { shell } from "developer". Some models might try to call tools directly without importing, which will fail.
Use the discovery tools - Before writing code, the LLM should call search_modules and read_module to learn what tools are available. Some models skip this step and guess, leading to hallucinated tool names.
Handle errors gracefully - When a code execution fails, the model needs to read the error, understand what went wrong, and try again. Some models are better at this feedback loop than others.

If Code Mode is not working well for you, try switching models. A model that excels at code generation and instruction following will generally perform better with Code Mode than one optimized for other tasks.

8. Code Mode Is Not for Every Task

Code Mode adds overhead. Before executing anything, the LLM has to:

Call search_modules to find available extensions
Call read_module to learn what tools an extension offers
Write JavaScript code
Call execute_code to run it

For simple, single-tool tasks, this overhead is not worth it. If you just need to run one shell command or view one file, regular tool calling is faster.

Based on my experiments, here is when Code Mode makes sense:

Use Code Mode When	Skip Code Mode When
You have multiple extensions enabled	You only have 1-2 extensions
Your task involves multi-step orchestration	Your task is a single tool call
You want longer sessions without context rot	Speed matters more than context longevity
You are working across multiple editors	You are doing a quick one-off task

Try It Out

If you want to experiment with Code Mode, here are some resources:

Documentation:

Previous posts:

Code Mode MCP in goose by Alex Hancock
Code Mode Doesn't Replace MCP by me

Community:

Join our Discord to share what you learn
File issues on GitHub if something does not work as expected

Run your own experiments and let us know what you find.

5 Tips for Building MCP Apps That Work

Rizèl Scarlett — Thu, 19 Feb 2026 06:49:01 +0000

MCP Apps allow you to render interactive UI directly inside any agent supporting the Model Context Protocol. Instead of a wall of text, your agent can now provide a functional chart, a checkout form, or a video player. This bridges the gap in agentic workflows: clicking a button is often clearer than describing the action you hope an agent executes.

MCP Apps originated as MCP-UI, an experimental project. After adoption by early clients like goose, the MCP maintainers incorporated it as an official extension. Today, it's supported by clients like goose, MCPJam, Claude, ChatGPT, and Postman.

Even though MCP Apps use web technologies, building one isn't the same as building a traditional web app. Your UI runs inside an agent you don't control, communicates with a model that can't see user interactions, and needs to feel native across multiple hosts.

After implementing MCP App support in our own hosts and building several individual apps to run on them, here are the practical lessons we've picked up along the way.

Overview of how UI renders with MCP Apps

At a high level, clients that support MCP Apps load your UI via iFrames. Your MCP App exposes an MCP server with tools and resources. When the client wants to load your app's UI, it calls the associated MCP tool, loads the resource containing the HTML, then loads your HTML into an iFrame to display in the chat interface.

Here's an example flow of what happens when goose renders a cocktail recipe UI:

You ask the LLM "Show me a margarita recipe".
The LLM calls the get-cocktail tool with the right parameters. This tool has a UI resource link in _meta.ui.resourceUri pointing to the resource containing the HTML.
The client then uses the URI to fetch the MCP resource. This resource contains the HTML content of the view.
The HTML is then loaded into the iFrame directly in the chat interface, rendering the cocktail recipe.

There's a lot that also goes on behind the scenes, such as View hydration, capability negotiation, and CSPs, but this is how it works at a high level. If you're interested in the full implementation of MCP Apps, we highly recommend giving the spec a read.

Tip 1: Adapt to the Host Environment

When building an MCP App, you want it to feel like a natural part of the agent experience rather than something bolted on. Visual mismatches are one of the fastest ways to break that illusion.

Imagine a user starting an MCP App interaction inside a dark-mode agent, but the app renders in light mode and creates a harsh visual contrast. Even if the app works correctly, the experience immediately feels off.

By default, your MCP App has no awareness of the surrounding agent environment because it runs inside a sandboxed iframe. It cannot tell whether the agent is in light or dark mode, how large the viewport is, or which locale the user prefers.

The agent, referred to as the Host, solves this by sharing its environment details with your MCP App, known as the View. When the View connects, it sends a ui/initialize request. The Host responds with a hostContext object describing the current environment. When something changes, such as theme, viewport, or locale, the Host sends a ui/notifications/host-context-changed notification containing only the updated fields.

Imagine this dialogue between the View and Host:

View: "I'm initializing. What does your environment look like?"
Host: "We're in dark mode, viewport is 400×300, locale is en-US, and we're on desktop."
User switches to light theme
Host: "Update: we're now in light mode."

It is your job as the developer to ensure your MCP App makes use of the hostContext so it can adapt to the environment.

How to use hostContext in your MCP App

import { useState } from "react";
import { useApp } from "@modelcontextprotocol/ext-apps/react";
import type { McpUiHostContext } from "@modelcontextprotocol/ext-apps";

function MyApp() {
  const [hostContext, setHostContext] = useState<McpUiHostContext | undefined>(undefined);

  const { app, isConnected, error } = useApp({
    appInfo: { name: "MyApp", version: "1.0.0" },
    capabilities: {},
    onAppCreated: (app) => {
      app.onhostcontextchanged = (ctx) => {
        setHostContext((prev) => ({ ...prev, ...ctx }));
      };
    },
  });

  if (error) return <div>Error: {error.message}</div>;
  if (!isConnected) return <div>Connecting...</div>;

  return (
    <div>
      <p>Theme: {hostContext?.theme}</p>
      <p>Locale: {hostContext?.locale}</p>
      <p>Viewport: {hostContext?.containerDimensions?.width} x {hostContext?.containerDimensions?.height}</p>
      <p>Platform: {hostContext?.platform}</p>
    </div>
  );
}

💡 Tip: If you're using the useApp hook in your MCP App, the hook provides a onhostcontextchanged listener. You can then use a React useState to update your app context. The host will provide their context, it's up to you as the app developer to decide what you want to do with that. For example, you can use theme to render light mode vs dark mode, locale to show a different language, or containerDimensions to adjust the app's sizing.

Tip 2: Control What the Model Sees and What the View Sees

There are cases where you may want to have granular control over what data the LLM has access to, and what data the view can show. The MCP Apps spec specifies three different tool return values that lets you control data flow, each are handled differently by the app host.

content: Content is the info that you want to expose to the model. Gives model context.
structuredContent: This data is hidden from the model context. It is used to send data over the View for hydration.
_meta: This data is hidden from the model context. Used to provide additional info such as timestamps, version info.

Let's look at a practical example of how we can use these three tool return types effectively:

server.registerTool(
  "view-cocktail",
  {
    title: "Get Cocktail",
    description: "Fetch a cocktail by id with ingredients and images...",
    inputSchema: z.object({ id: z.string().describe("The id of the cocktail to fetch.") }),
    _meta: {
      ui: { resourceUri: "ui://cocktail/cocktail-recipe-widget.html" },
    },
  },
  async ({ id }: { id: string }): Promise<CallToolResult> => {
    const cocktail = await convexClient.query(api.cocktails.getCocktailById, {
      id,
    });

    return {
      content: [
        { type: "text", text: `Loaded cocktail "${cocktail.name}".` },
        { type: "text", text: `Cocktail ingredients: ${cocktail.ingredients}.` },
        { type: "text", text: `Cocktail instructions: ${cocktail.instructions}.` },
      ],
      structuredContent: { cocktail },
      _meta: { timestamp: new Date().toString() }
    };
  },
);

This tool renders a view showing a cocktail recipe. The cocktail data is being fetched from the backend database (Convex). The View needs the entire cocktail data so we pass the data to it via structuredContent. For the model context, the LLM doesn't need to know the entire cocktail data like the image URL. We can extract the information that the model should know about the cocktail, like the name, ingredients, and instructions. That information can be passed to the model via content.

It's important to note that currently, ChatGPT apps SDK handles it differently, where structuredContent is exposed to both the model and the View. Their model is the following:

content: Content is the info that you want to expose to the model. Gives model context.
structuredContent: This data is exposed to the model and the View.
_meta: This data is hidden from the model context.

If you're building an app that supports both MCP Apps and ChatGPT apps SDK, this is an important distinction. You may want to conditionally return values, or conditionally render tools based off of whether the client is MCP App support or ChatGPT app.

Tip 3: Properly Handle Loading States and Error States

It's pretty typical for the iFrame to render first before the tool finishes executing and the View gets hydrated. You're going to want to let your user know that the app is loading by presenting a beautiful loading state.

One powerful feature to note: toolInputs are sent and streamed into the View even before the tool execution is done. This allows you to create cool partial loading states where you can show the user what's being requested while the data is still being fetched.

To implement this, let's take a look at the same cocktail recipes app. The MCP tool fetches the cocktail data and passes it to the View via structuredContent. We don't know how long it takes to fetch that cocktail data, could be anywhere from a few ms to a few seconds on a bad day.

server.registerTool(
  "view-cocktail",
  {
    title: "Get Cocktail",
    description: "Fetch a cocktail by id with ingredients and images...",
    inputSchema: z.object({ id: z.string().describe("The id of the cocktail to fetch.") }),
    _meta: {
      ui: {
        resourceUri: "ui://cocktail/cocktail-recipe-widget.html",
        visibility: ["model", "app"],
      },
    },
  },
  async ({ id }: { id: string }): Promise<CallToolResult> => {
    const cocktail = await convexClient.query(api.cocktails.getCocktailById, {
      id,
    });

    return {
      content: [
        { type: "text", text: `Loaded cocktail "${cocktail.name}".` },
      ],
      structuredContent: { cocktail },
    };
  },
);

On the View side (React), the useApp AppBridge hook has a app.ontoolresult listener that listens for the tool return results and hydrates your View. While onToolResult hasn't come in yet and the data is empty, we can render a beautiful loading state.

import { useApp } from "@modelcontextprotocol/ext-apps/react";

function CocktailApp() {
  const [cocktail, setCocktail] = useState<CocktailData | null>(null);

  useApp({
    appInfo: IMPLEMENTATION,
    capabilities: {},
    onAppCreated: (app) => {
      app.ontoolresult = async (result) => {
        const data = extractCocktail(result);
        setCocktail(data);
      };
    },
  });

  return cocktail ? <CocktailView cocktail={cocktail} /> : <CocktailViewLoading />;
}

Handling errors

We also want to handle errors gracefully. In the case where there's an error in your tool, such as the cocktail data failing to load, both the LLM and the view should be notified of the error.

In your MCP tool, you should return an error in the tool result. This is exposed to the model and also passed to the view.

server.registerTool(
  "view-cocktail",
  {
    title: "Get Cocktail",
    description: "Fetch a cocktail by id with ingredients and images...",
    inputSchema: z.object({ id: z.string().describe("The id of the cocktail to fetch.") }),
    _meta: {
      ui: { resourceUri: "ui://cocktail/cocktail-recipe-widget.html" },
      visibility: ["model", "app"],
    },
  },
  async ({ id }: { id: string }): Promise<CallToolResult> => {
    try {
      const cocktail = await convexClient.query(api.cocktails.getCocktailById, {
        id,
      });

      return {
        content: [
          { type: "text", text: `Loaded cocktail "${cocktail.name}".` },
        ],
        structuredContent: { cocktail },
      };
    } catch (error) {
      return {
        content: [
          { type: "text", text: `Could not load cocktail` },
        ],
        error
      };
    }
  },
);

Then in useApp on the React client side, you can detect whether or not there was an error by looking at the existence of error from the tool result.

Tip 4: Keep the Model in the Loop

Because your MCP App operates in a sandboxed iframe, the model powering your agent can't see what happens inside the app by default. It won't know if a user fills out a form, clicks a button, or completes a purchase.

Without a feedback loop, the model loses context. If a user buys a pair of shoes and then asks, "When will they arrive?", the model won't even realize a transaction occurred.

To solve this, the SDK provides two methods to keep the model synchronized with the user's journey: sendMessage and updateModelContext.

sendMessage()

Use this for active triggers. It sends a message to the model as if the user typed it, prompting an immediate response. This is ideal for confirming a "Buy" click or suggesting related items right after an action.

// User clicks "Buy" - the model responds immediately
await app.sendMessage({
  role: "user",
  content: [{ type: "text", text: "I just purchased Nike Air Max for $129" }],
});
// Result: Model responds: "Great choice! Want me to track your order?"

updateModelContext()

Use this for background awareness. It quietly saves information for the model to use later without interrupting the flow. This is perfect for tracking browsing history or cart updates without triggering a chat response every time.

// User is browsing - no immediate response needed
await app.updateModelContext({
  content: [{ type: "text", text: "User is viewing: Nike Air Max, Size 10, $129" }],
});
// Result: No response. But if the user later asks, "What was I looking at?", the model knows.

Tip 5: Control Who Can Trigger Tools

With a standard MCP server, the model sees your tools, interprets the user's prompt, and calls the right tool. If a user says "delete that email," the model decides what that means and invokes the delete tool.

However, with an MCP App, tools can be triggered in two ways: the model interpreting the user's prompt, or the user interacting directly with the UI.

By default, both can call any tool. For example, say you build an MCP App that visually surfaces an email inbox and lets users interact with emails. Now there are two potential triggers for your tools: the model acting on a prompt to delete an email, and the user clicking a delete button directly in the App's interface.

The model works by interpreting intent. If a user says "delete my old emails," the model has to decide what "old" means and which emails qualify. For some actions like deleting emails, that ambiguity can be risky.

When a user clicks a "Delete" button next to a specific message in your MCP App, there is no ambiguity. They have made an explicit choice.

To prevent the model from accidentally performing high-stakes actions based on a misunderstanding, you can use tool visibility to restrict certain tools to the MCP App's UI only. This allows the model to display the interface while requiring a human click to finalize the action.

You can define visibility using these three configurations:

["model", "app"] (default) — Both the model and the UI can call it
["model"] — Only the model can call it; the UI cannot
["app"] — Only the UI can call it; hidden from the model

Here's how you might implement this:

// Model calls this to display the inbox
registerAppTool(server, "show-inbox", {
  description: "Display the user's inbox",
  _meta: {
    ui: {
      resourceUri: "ui://email/inbox.html",
      visibility: ["model"],
    },
  },
}, async () => {
  const emails = await getEmails();
  return { content: [{ type: "text", text: JSON.stringify(emails) }] };
});

// User clicks delete button in the UI
registerAppTool(server, "delete-email", {
  description: "Delete an email",
  inputSchema: { emailId: z.string() },
  _meta: {
    ui: {
      resourceUri: "ui://email/inbox.html",
      visibility: ["app"],
    },
  },
}, async ({ emailId }) => {
  await deleteEmail(emailId);
  return { content: [{ type: "text", text: "Email deleted" }] };
});

Start Building with goose and MCPJam

MCP Apps open up a new dimension for agent interactions. Now it's time to build your own.

Test with MCPJam — the open source local inspector for MCP Apps, ChatGPT apps SDK, and MCP servers. Perfect for debugging and iterating on your app before shipping.
Run in goose — an open source AI agent that renders MCP Apps directly in the chat interface. See your app come to life in a real agent environment.

Ready to dive deeper? Check out the MCP Apps tutorial or build your first MCP App with MCPJam.

How I Used RPI to Build an OpenClaw Alternative

Rizèl Scarlett — Thu, 19 Feb 2026 06:44:39 +0000

Everyone on Tech Twitter has been buying Mac Minis, so they could run a local agentic tool called OpenClaw. OpenClaw is a messaging-based AI assistant that connects to platforms such as Discord and Telegram allowing you to interact with an AI agent through DMs or @mentions. Under the hood, it uses an agent called Pi to execute tasks, browse the web, write code, and more.

Seeing the hype made me want to get my hands dirty. I wanted to see if I could build a lite version for myself. I wanted something minimal that used goose as the engine instead of Pi. I tentatively dubbed it AltOpenClaw.

Choosing RPI

My usual move is to just jump in, start breaking things, and refactor as I go. I actually prefer the back and forth conversation with an agent because it helps me learn how the project works in real time. But when I tried that here, I hit a wall fast. goose did not naturally know what OpenClaw was, and it kept hallucinating how to use its own backend. It would forget context mid-conversation or suggest API calls that simply did not exist.

I realized I needed to change my approach. While I love the iterative learning process, I needed a way to give the agent a better foundation so our pair programming sessions actually made progress. I decided to try the RPI method (Research, Plan, Implement). This is a framework introduced by HumanLayer that trades raw speed for predictability. It is built into goose as a series of recipes. Since I did not fully understand the technical landscape myself, this investment in structure felt like the right move to help us both get on the same page.

Research

First, I needed goose to understand what I was building and whether it was even possible. I kicked things off with a detailed research prompt:

/research_codebase topic="learn what openclaw is, how people use it, 
and how it works. learn if goose can actually be used as a backend 
or if that's not yet possible; understand the port issues especially 
if you have an instance of goose that's running to help you build 
an agent that uses goose as a backend. learn if there will be any 
auth issues"

goose spawned multiple parallel subagents to investigate.

Key findings from the research:

OpenClaw uses its own embedded agent runtime (Pi), not goose. This meant there was no existing integration to copy.
goose CAN be used as a backend! The goosed server exposes a full HTTP API.
Port conflicts are manageable. We just needed to run on a different port with GOOSE_PORT=3001.
Authentication is simple. We could pass a secret key in the X-Secret-Key header.

The research also mapped out all the relevant API endpoints, such as POST /sessions to create a new session and POST /sessions/{id}/reply to handle the actual messaging.

Plan

With the research complete, I asked goose to create an implementation plan. This is where we defined the personality and security of the bot:

/create_plan ticket-or-context="I want to build a Discord MCP server 
for goose that replicates the popular features of OpenClaw but with 
better security. Core Features: Users can DM the bot or @ it in a 
channel to give goose tasks. goose responds in Discord with results. 
Security requirements: Allowlist (only specific Discord user IDs can 
interact), Approval flow (before goose executes any tool/action, the 
bot posts what it wants to do and waits for user approval), 
Non-allowlisted users get a polite 'you don't have access'"

goose analyzed the requirements and produced a detailed plan with four phases:

Phase 1: Project Setup (Discord.js skeleton and allowlist)
Phase 2: goose HTTP Client (Connecting to the API and handling SSE streaming)
Phase 3: Tool Approval Flow (The UI for ✅/❌ reactions)
Phase 4: Polish & Error Handling (Slash commands and session management)

I liked this phased approach because it gave us less to debug at each step. We could handle features in chunks rather than trying to fix everything at once.

Implement

With the plan in place, I gave the signal to start building:

/implement_plan start building

The first two phases were surprisingly smooth. Within an hour, the bot was online and I could actually DM it. Seeing a Discord message trigger a goose session for the first time was a massive win.

First, we tested if AltOpenClaw could respond to me with a joke!

However, as every developer knows, it was not all perfect. We still ran into some classic real-world hurdles during implementation:

The SSE (Server-Sent Events) format was different than we expected. We spent a good chunk of time debugging why the messages were not appearing until we realized the event structure was nested deeper than anticipated.
My local path did not have npm properly mapped, which led to a brief detour.
Discord has a strict limit on message length. If goose wrote a long script, the bot would just crash. We had to implement a chunking system on the fly.

Currently, the tool approval feature is still a work in progress. I actually got so excited that the core part of the project was working that I sat down to write this post before finishing the UI for the reactions.

The Takeaway

The RPI method felt like a superpower, even if it didn't magically delete every bug from the project. There is a big difference between fighting a hallucination and fighting a real technical challenge.

When I didn't use RPI, goose hallucinated nonexistent endpoints and tried to build a complex MCP server when a simple HTTP API was all we needed. Those are the kinds of bugs that waste hours because you are chasing ghosts.

Instead, RPI helped us clear the conceptual fog so we could focus on real implementation details like SSE parsing and character limits.

By forcing the agent to research first, it built up the context it was missing. It is a bit slower at the start (which I barely have patience for), but it turns the agent into a much more capable partner for that back and forth learning process I enjoy.

I even had AltOpenClaw push its own repository to GitHub.

Try It Out

If you want more reliability from your agent, give the RPI recipes in goose a shot:

/research_codebase
/create_plan
/implement_plan
/iterate_plan

Happy hacking!

[Boost]

Rizèl Scarlett — Wed, 14 Jan 2026 20:03:16 +0000

Amanda

Jan 13

Dynamic MCP Server discovery with goose

#ai #mcp #agents

Comments 3

1 min read

How I Taught My Agent My Design Taste

Rizèl Scarlett — Mon, 05 Jan 2026 00:15:14 +0000

Can you automate taste? The short answer is no, you cannot automate taste, but I did make my design preferences legible.

But for those interested in my experiment, I'll share the longer answer: I wanted to participate in Genuary, the annual challenge where people create one piece of creative coding every day in January.

My goal here wasn't to "outsource" my creativity. Instead, I wanted to use Genuary as a sandbox to learn agentic engineering workflows. These workflows are becoming the standard for how developers work with technology. To keep my skills sharp, I used goose to experiment with these workflows in small, daily bursts.

By building a system where goose handles the execution, I could test different architectures side-by-side. This experiment allowed me to determine which parts of an agentic workflow actually add value and which parts I should ditch. I spent a few hours focused on infrastructure to buy myself an entire month of workflow data.

💡 Skills are reusable sets of instructions and resources that teach goose how to perform specific tasks.

The Inspiration

I have to give a huge shout-out to my friend Andrew Zigler. I saw him crushing Genuary and reached out to see how he was doing it. He shared his creations and mentioned he was using a "harness."

I'll admit, I'd been seeing people use that term all December, but I didn't actually know what it meant. Andrew explained: a harness is just the toolbox you build for the model. It's the set of deterministic scripts that wrap the LLM so it can interact with your environment reliably. He had used this approach to solve a different challenge, building a system that could iterate, submit, and verify itself.

He justified that if you spend time upfront working on a spec and establishing constraints. Then, you delegate. Once you have deterministic tools with good logging, the agent is incredibly good at looping until it hits its goal.

My approach is typically very vanilla, and I lean heavily on prompting, but I was open to experimenting since Andrew was getting such excellent results.

Harness vs. Skills

Inspired by that conversation, I built two versions of the same workflow to see how they handled the same daily Genuary prompts.

Approach 1: Harness + Recipe: This lives in /genuary. Following Zig's lead, I wrote a shell script to act as the harness. It handles the scaffolding, creating folders and surfacing the daily prompt, so goose doesn't have to guess where to go. The recipe is about 300 lines long and fully self-contained.
Approach 2: Skills + Recipe: This lives in /genuary-skills. This recipe is much leaner because it delegates the "how" to a skill. The skill contains the design philosophy, references, and examples. I wanted to see how the work changed when the agent had to "discover" its instructions in a bundle rather than following a flat script.

I spent one focused session building the entire system: recipes, skills, harness scripts, templates, and GitHub Actions. (This happened in the quiet hours of my December break, with my one-year-old sleeping on my lap.) This was about trading short-term effort for long-term leverage. From that point on, the system did the daily work.

On Taste

The automation was smooth, but when I reviewed the output, I noticed everything looked suspiciously similar.

That's when I started to think about the discourse on how you can't teach an agent "taste." I thought about how I develop taste. I honestly develop taste by:

Seeing what's cool and copying it.
Knowing what's overplayed because you've seen it too much.
Following people with "good taste" and absorbing their patterns.

Obviously, I approached goose about this problem:

"I noticed it always does salmon colored circles..i know we said creative..any ideas on how to make sure it thinks outside the box"

goose shared that it was following a p5.js template it retrieved, which included a fill(255, 100, 100) (salmon!) value and an ellipse example. Since LLMs anchor heavily on concrete examples, the agent was following the code more than my "creative" instructions.

I removed the salmon circle from the template, but then I took it further: I asked how to ban common AI generated clichés altogether. goose searched discussions, pulled examples, and produced a banned list of patterns that scream "AI-generated."

BANNED CLICHÉS

Category	Banned Patterns
Color Crimes	Salmon or coral pink, teal and orange combinations, purple-pink-blue gradients.
Composition Crimes	Single centered shapes, perfect symmetry with no variation, generic spirals.
The Gold Rule	If it looks like an AI generated output, do not do it.

ENCOURAGED PATTERNS

Category	Encouraged Patterns
Color Wins	HSB mode with shifting hues, complementary palettes, gradients that evolve over time.
Composition Wins	Particle systems with emergent behavior, layered depth with transparency, hundreds of elements interacting.
Movement Wins	Noise-based flow fields, flocking/swarming, organic growth patterns, breathing with variation.
Inspiration Sources	Natural phenomena: starlings murmurating, fireflies, aurora, smoke, water.
The Gold Rule	If it sparks joy and someone would want to share it, you're on the right track.

goose determined this list through pattern recognition. So perhaps, agents can use patterns to reflect my taste, not because they understand beauty, but because I'm explicitly teaching them what I personally respond to.

I showed Andrew my favorite output of the three days: butterflies lining themselves in a Fibonacci sequence.

His response was validating:

"WOW that's an incredible Fibonacci… I'd be really curious to know your aesthetic prompting. Mine leans more pixel art and mathematical color manipulation because I've conditioned it that way… I like that yours leaned softer and tried to not look computer-created… like phone wallpaper practically lol..How did you even get that cool thinned line art on the butterflies? It looks like a base image. It's so cool. Did it draw SVGs? Like where did those come from?"

Because I'd specifically told goose to look at "natural phenomena" and "organic growth," it used Bezier curves for the wings and shifted the colors based on the spiral position to create depth, and a warm amber-to-blue gradient instead of stark black.

Scaling Visual Feedback Loops

Both workflows use the Chrome DevTools MCP server so goose can see the output and iterate on it. This created a conflict where multiple instances couldn't use the same Chrome profile. I didn't want a manual step, so I asked the agent if it was possible to run Chrome DevTools in parallel. The solution was assigning separate user data directories.

# genuary recipe example
- type: stdio
  name: Chrome Dev Tools
  cmd: npx
  args:
    - -y
    - chrome-devtools-mcp@latest
    - --userDataDir
    - /tmp/genuary-harness-chrome-profile

What I Learned

I automated execution so I could study taste, constraint design, and feedback loops.

The two approaches behaved very differently. The harness-based workflow was more reliable and efficient, but it produced more predictable results. It followed instructions faithfully and optimized for consistency.

The skills-based approach was messier. It surfaced more surprises, made stranger connections, and required more editorial intervention. But the output felt more like a collaboration than a pipeline.

What this reinforced for me is that the "AI vs. human" framing is too simplistic. Automation handles repetition and speed well. Taste still lives in constraint-setting, curation, and deciding what should never happen. I ended up not automating taste. Instead, the end result was a system that made my preferences legible enough to be reflected back to me.

See the Code

The code and full transcripts live in my Genuary 2026 repo. Each day folder contains the complete conversation history, including the pitches, iterations, and the back-and-forth between me and the agent. You can also view the creations on the Genuary 2026 site.

The Worst Thing to Happen to React and Next.js: React2Shell

Rizèl Scarlett — Wed, 31 Dec 2025 08:34:22 +0000

"I ain't reading all that. I'm happy for you tho, or sorry that happened."

That was my internal reaction when I saw the headlines about CVE-2025-55182, more commonly called React2Shell. I had deadlines to meet. I bookmarked the articles, added "read React vulnerability stuff" to my todo list, and kept working. I didn't think it would affect me anyway. Most of my projects are demos for my work in Developer Relations. Who would bother attacking those?

A few days later, someone messaged me: "Hey, your demo site redirected me to some sketchy crypto site."

Wait, what? My heart sank to my stomach.

I frantically combed through my repository. Everything looked fine. The commit history was clean, the codebase unchanged, and I couldn't find any redirect logic that would explain what users were experiencing. I felt that uncomfortable combination of confusion and exposure. Someone was exploiting my project, but I couldn't figure out how they'd gotten in.

I resorted to asking goose, my AI coding agent, to help me investigate since this was outside my usual debugging territory. It suggested the injection might be happening at the DNS level or somewhere in my Railway deployment infrastructure. I changed my DNS settings, and it looked like that fixed it.

A few days later, I went to check my demo site to see if things were still the same, and it was redirecting to the crypto site. My hands felt clammy.

Then a memory surfaced. It felt like I was Raven from That's So Raven. The memory was of a fellow open source contributor who had pinged me saying: "Hey Rizel, make sure you update your Next.js projects. That React vulnerability is really serious." At the time, I thought, "I only have a demo project that needs upgrading. I can do it later."

That's when it clicked. I realized attackers were exploiting CVE-2025-55182, a vulnerability in React Server Components that allowed them to execute arbitrary JavaScript on my server. They didn't need to touch my codebase at all. They just needed to send specially crafted HTTP requests to my application, and the vulnerable React deserialization would execute their code.

I upgraded my Next.js and React dependencies immediately, and the redirects finally stopped for good.

I felt foolish. A trusted colleague had literally warned me, and I'd put it on my "important but not urgent" list because I thought it didn't apply to me, except it did apply to me.

Understanding React2Shell

React Server Components introduced a new way for React applications to run code on the server. When you write a function marked with 'use server', React automatically creates endpoints that handle communication between your client and server using something called the Flight protocol. This protocol serializes and deserializes data as it travels back and forth.

The vulnerability was in how this deserialization worked. When your server received data through these automatically-generated Flight endpoints, it would unpack that data and process it. But the deserialization logic had a flaw. Attackers could craft malicious payloads that, when unpacked, would execute arbitrary code on your server instead of just calling your legitimate server functions.

Think about it like this: imagine you have a package delivery system where you automatically open and process every package that arrives. CVE-2025-55182 was like someone figuring out they could put a bomb inside a package, and your system would dutifully unpack and activate it without checking what was inside first.

In my case, the attackers were injecting code that intercepted HTTP responses and redirected users to crypto scam sites. But they could have done much worse. With arbitrary code execution on the server, they could have stolen my database credentials, exfiltrated my environment variables and API keys, installed persistent backdoors, or used my server for crypto mining. I got lucky.

Who Was Affected

This vulnerability affected applications using React Server Components across several common setups.

Affected versions included:

Next.js App Router on 15.x, 16.x, and 14.x canary releases after 14.3.0-canary.77
React versions 19.0, 19.1.0, 19.1.1, and 19.2.0

The impact extended beyond Next.js. Any framework experimenting with or building on React Server Components was potentially affected, including Vite RSC plugins and React Router’s unstable RSC APIs.

Why This Was So Severe

Because it required no authentication, no user interaction, and had near-perfect reliability, this vulnerability was rated CVSS 10.0, the maximum severity score. Security researchers observed active exploitation in the wild starting December 5th, just two days after the patches were released, with some of the activity linked to threat groups with suspected ties to state actors.

What You Should Do Right Now

If you're running any React or Next.js application with Server Components or Server Actions, upgrade immediately. Not later, not after you finish your current sprint, not once you've checked whether you're actually affected.

After upgrading, rotate your secrets. Even if you didn't notice any exploitation like I did, if you were vulnerable, you should assume attackers might have accessed your environment variables. Change your database passwords, API keys, deployment tokens, and anything else sensitive.

Lessons Learned

This experience reminded me that I’m not exempt from security vulnerabilities . Even toy projects and demos matter because they're running on real servers with real access to real infrastructure.

Online security often feels like someone else's problem until it becomes your problem. Don't wait until you're scrambling to understand how your project got compromised.

My Predictions for MCP and AI-Assisted Coding in 2026

Rizèl Scarlett — Wed, 31 Dec 2025 01:36:04 +0000

I'm writing this fully aware that predictions about AI often age badly.

I don't want to sound like those CEOs who confidently announce that AI will replace engineers in six months, only to quietly move the timeline when nothing happens. Instead, this is a personal thought experiment.

I've been experimenting with AI-assisted coding since it was still taboo to admit you were doing it. I started in 2021 while working at GitHub, helping developers understand the value of well-written prompts through GitHub Copilot. I was an early user of ChatGPT, alongside Claude and many other tools, long before "prompting" became its own discipline.

Today, I'm a Developer Advocate for goose, which serves as a reference implementation for Model Context Protocol and one of the first MCP clients. I use multiple MCP servers daily workflow to solve real problems.

All of that gives me a decent sense of where things might head next.

So I decided to make a few predictions for 2026, mostly to sharpen my own visionary skills. Will any of these come true? Would I tweak them a year from now? Let's find out.

These are my personal opinions. I'm not speaking on behalf of my employer or any project I work on.

Prediction 1: AI Code Review Gets Solved

By the end of 2026, I believe we'll have cracked AI code review.

Right now, one of the biggest bottlenecks in software development, especially in open source, is review capacity. People generate code faster than ever with AI, but that speed shifts pressure downstream. Maintainers, tech leads, and engineering managers now face more pull requests, more diffs, and more surface area to validate.

We already see AI-powered code review tools, but none fully hit the mark. They often feel noisy, overly rigid, or disconnected from real-world developer workflows.

Recently, Aiden Bai publicly shared thoughtful, constructive feedback on how AI code review tools like CodeRabbit could improve.

Beyond the controversy around how CodeRabbit responded, the attention his tweet received signaled something important: developers are actively hoping for a better solution.

By 2026, I expect either an existing product to meaningfully level up or a new company to enter and get it right. This is one of the most pressing problems in the space, and I think the industry will prioritize fixing it.

If you want to stay on top of developments in AI code review, I recommend following Nnenna Ndukwe / @nnennahacks

// Detect dark theme var iframe = document.getElementById('tweet-1998408841285837197-64'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1998408841285837197&theme=dark" }

Prediction 2: MCP Apps Become the Default

I think MCP Apps will become a core part of how people interact with AI agents.

MCP Apps are the successor to MCP-UI, which first showed that agents didn't need to respond with text alone, but could render interactive interfaces directly inside the host environment. Think embedded web UIs, buttons, toggles, and selections. Users express intent through interaction rather than explanation.

As this pattern gained traction, it became clear that interactive interfaces needed first-class support in the protocol itself. MCP Apps build on that momentum and are now being incorporated into the MCP standard.

Below is a video of MCP-UI in action:

This matters beyond developer ergonomics. For years, companies tried to keep users inside their apps with embedded chatbots, hoping increased "stickiness" would drive revenue. That approach never fully worked. Meanwhile, user behavior shifted. People now go directly to AI tools like ChatGPT for answers instead of navigating websites, even if they aren't engineers.

MCP Apps flip the model. Instead of pulling users into your app, your app meets users inside their AI environment.

We already see early adoption. OpenAI is moving in this direction with ChatGPT, and goose adopted MCP-UI early and is close to shipping full MCP Apps support. Other platforms are taking similar steps.

To learn more about MCP Apps, check out this blog post.

Prediction 3: Agents Become Portable Across Platforms

I think agents will follow users wherever they work.

Today, I benefit heavily from MCP servers because they make it possible to connect agents to tools and systems. Still, I there's friction. Many users grow attached to a specific agent and want it available across environments without constant reconfiguration.

This is where Agent Client Protocol becomes interesting. ACP allows an agent to run inside any editor or environment that supports the protocol, without tightly coupling it to a specific plugin or extension.

We felt this pain firsthand with goose. Maintaining a VS Code extension proved difficult. goose would evolve, the extension would lag, and users would hit breakage. ACP changed that dynamic. Instead of tightly coupling the agent to a plugin, the editor becomes the client.

Zed Industries introduced this model. When I tried goose inside the Zed editor, the experience felt noticeably smoother. Editors from JetBrains have also adopted the protocol. ACP tends to get less attention than MCP, partly because it's less flashy and partly because the acronym overlaps with other agent-related protocols. Even so, the impact is real.

Here's where I get more ambitious. I don't think this stops at editors. Over time, agent portability may extend to design tools, browsers, and other platforms. I can imagine bringing goose, Codex, or Claude Code directly into tools like Figma without rebuilding the integration each time. This part is more speculative, but the direction feels plausible.

Prediction 4: DIY Agent Configuration Hits a Ceiling

This one feels riskier to say out loud, but I think we eventually move away from heavy context engineering and excessive configuration.

Right now, we compensate for model limitations by adding layers of structure: rules files, memory files, subagents, reusable skills, system prompt overrides, toggles, and switches. All of these help agents behave more reliably, and in many cases, they're necessary, especially for large codebases, legacy systems, and high-impact code changes.

As an engineer, I find this exciting. Configuring my setup feels participatory. I enjoy shaping how an agent reasons and responds. There's satisfaction in tuning behavior instead of treating AI as a black box.

But there's another side we haven't fully felt the consequences of yet.

Every week introduces a new "best practice." Another rule or configuration users feel pressure to adopt. At some point, the overhead may outweigh the benefit. Instead of building, people spend more time configuring the act of building.

I already see developers opting out. Some reject AI because of poor early experiences. Others reject it because the process feels exhausting. They just want to write code.

I've seen this pattern before. When Kubernetes became widely adopted, it unlocked enormous power but also exposed developers to infrastructure complexity they weren't meant to manage. The response wasn't to turn every developer into a Kubernetes expert, but to introduce platform teams, DevOps roles, and abstractions that absorbed that complexity.

I don't want to leave anyone behind in this AI era.

The thought genuinely makes me sad when we say things like "People will get left behind," so I'm brainstorming ways of how to make sure everyone "eats".

When we approach a similar inflection point with agents, I see two likely paths forward:

Tooling improves to the point where most configuration fades into the background.
Companies formalize roles around AI enablement. I've already seen early versions of this. We have internal AI champions at and enablement groups (led by my manager Angie Jones) that help teams use agents safely and effectively.

Personally, I hope for balance. I enjoy configuration and depth, but I don't think productivity scales if every repo demands a complex setup just to get started.

Those are my predictions for 2026. Let's revisit this in a year and see what holds up.

What are your predictions? And what do you think of mine?

yass

Rizèl Scarlett — Tue, 30 Dec 2025 00:32:22 +0000

Nick Taylor

Dec 29 '25

What Makes Goose Different From Other AI Coding Agents

#goose #ai #agents #cli

Comments

12 min read

How We Use goose to Maintain goose

Rizèl Scarlett — Sun, 28 Dec 2025 17:45:33 +0000

As AI agents grow in capability, more people feel empowered to code and contribute to open source. The ceiling feels higher than ever. That is a net positive for the ecosystem, but it also changes the day-to-day reality for maintainers. Maintainers like the goose team face a growing volume of pull requests and issues, often faster than they can realistically process.

We embraced this reality and put goose to work on its own backlog.

We actually used goose pre-1.0 to help us build goose 1.0. The original goose was a Python CLI, but we needed to move quickly to Rust, Electron, and an MCP-native architecture. goose helped us make that transition. Using it to triage issues and review changes felt like a natural extension, so we embedded goose directly into a GitHub Action.

Credit: That GitHub Action workflow was built by Tyler Longwell, who took an idea we had been exploring manually and turned it into something any maintainer could trigger with a single comment.

Before the GitHub Action

Before the GitHub Action existed, the goose team was already using goose to accelerate our issue workflow. Here's a real example.

A user reached out on Discord asking why an Ollama model was throwing an error in chat mode. Rather than digging through the codebase myself, I asked goose to explore the code, identify the root cause, and explain it back to me. Then, I asked goose to use the GitHub CLI to open an issue.

During that same session, goose mentioned it had 95% confidence it knew how to fix the problem. The change was small, so I asked goose to open a PR. It was merged the same day.

This kind of workflow has changed how I operate as a Developer Advocate. Before goose, when a user reported a problem, the process unfolded in fragments. I would ask clarifying questions, check GitHub for related issues, pull the latest code, grep through files, read the logic, and try to form a hypothesis about what was going wrong.

If I figured it out, I had two options:

I could write up a detailed issue and add it to a developer's backlog, which meant someone else had to context-switch into the problem later.
Or I could attempt the fix myself, which often led to more time spent and more back-and-forth during code review if I got something wrong.

Either way, the process stretched across hours or days. And if the problem wasn't high priority, it sometimes slipped through the cracks. The report would sit in Discord or a GitHub comment until it scrolled out of view, and the user would assume nobody was listening.

With goose, that entire process collapsed into a single conversation.

The local workflow works. But when I solve an issue locally with goose, I'm still the one driving. I stop what I'm doing, open a session, paste the issue context, guide goose through the fix, run the tests, and open the PR.

Scaling with a GitHub Action

The GitHub Action compresses that entire sequence into a single comment. A team member sees an issue, comments /goose, and moves on. goose spins up in a container, reads the issue, explores the codebase, runs verification, and opens a draft PR. The maintainer returns to a proposed solution rather than a blank slate.

We saw this play out with issue #6066. Users reported that goose kept defaulting to 2024 even though the correct datetime was in the context. The issue sat for two days. Then Tyler saw it, commented /goose solve this minimally at 1:59 AM, and went back to whatever he was doing (presumably sleeping). Fourteen minutes later, goose opened PR #6101.

The maintainer's role shifts from implementing to reviewing. The bottleneck in open source is rarely "can someone write this code." It's "can someone with enough context find the time to write this code." The GitHub Action decouples those two constraints. Any maintainer can trigger a fix attempt without deep familiarity with that part of the codebase.

This scales in a way manual triage cannot. A backlog contains feature requests, complex bugs, and quick fixes in equal measure. The Action lets you point at an issue and say "try this one" without committing your afternoon. If goose fails, you lose minutes of compute. If it succeeds, you save hours.

For contributors, responsiveness changes everything. When a user filed issue #6232 about slash commands not handling optional parameters, a maintainer quickly commented /goose can you fix this, and within the hour there was a draft PR with the fix and four new tests. Even if the PR is not perfect and needs adjustments, contributors see momentum.

Under the Hood

Maintainers summon goose with /goose followed by a prompt as a comment on an issue. GitHub Actions spins up a container with goose installed, passes in the issue metadata, and lets goose work. If goose produces changes and verification passes, the workflow opens a draft pull request.

But there's more happening under the hood than a simple prompt like "/goose fix this."

The workflow uses a recipe that defines phases to ensure goose actually accomplishes the job and doesn't do more than we ask it to.

Phase	What goose does	Why it matters
Understand	Read the issue and extract all requirements to a file	Forces the AI to identify what "done" looks like before writing code
Research	Explore the codebase with search and analysis tools	Prevents blind edits to unfamiliar code
Plan	Decide on an approach	Catches architectural mistakes before implementation
Implement	Make minimal changes per the requirements	"Is this in the requirements? If not, don't add it"
Verify	Run tests and linters	Catches obvious failures before a human sees the PR
Confirm	Reread the original issue and requirements	Prevents the AI from declaring victory while forgetting half the task

The recipe also gives goose access to the TODO extension, a built-in tool that acts as external memory. The phases tell goose what to do. The TODO helps goose remember what it's doing. As goose reads through the codebase and builds a solution, its context window fills up and earlier instructions can be compressed or lost. The TODO persists, so goose can always check what it's done and what's left.

The workflow also enforces guardrails around who can invoke /goose, which files it's allowed to touch, and the requirement that a maintainer review and approve every PR.

There's something strange about using goose to maintain goose. But it keeps us honest. We're our own first customer, and if the agent can't produce mergeable PRs here, we feel it immediately.

The future we're aiming for isn't one where AI replaces maintainers. It's one where a maintainer can point at a problem, say "try this," and come back to a concrete proposal instead of a blank editor.

If that becomes the norm, open source scales differently.

The GitHub Action workflow is public for anyone who wants to explore this pattern in their own CI pipeline.

Code Mode Doesn't Replace MCP (Here's What It Actually Does)

Rizèl Scarlett — Mon, 22 Dec 2025 01:37:24 +0000

One day, we will tell our kids we used to have to wait for agents, but they won't know that world because the agents in their day would be so fast. I joked about this with Nick Cooper, an MCP Steering Committee Member from OpenAI, and Bradley Axen, the creator of goose. They both chuckled at the thought because they understand exactly how clunky and experimental our current "dial-up era" of agentic workflows can feel.

Model Context Protocol (MCP) has moved the needle by introducing a new norm: the ability to connect agents to everyday apps. However, the experience isn't perfect. We are still figuring out how to balance the power of these tools with the technical constraints of the models themselves.

The "Too Many Extensions" Problem

(Quick note: In goose, we call MCP servers "extensions." I'll use "extensions" from here on out.)

Many people write off MCP because they experience lag or instability, often without realizing they've fallen into the trap of "tool bloat." Admittedly, there's a lot of "don't do this" advice so you can have a good experience. For example, a best practice that the goose team and power users follow is: don't turn on too many extensions at once. Otherwise, your sessions will degrade quicker, you'll see more hallucinations, and task execution may be slower.

I've seen first-time users turn on a bunch of extensions in excitement. "This is so cool. I'm going to need it to access GitHub, Vercel, Slack, my database..." They are effectively flooding the agent's context window with hundreds of tokens worth of tool definitions. Each tool call requires the model to hold all those definitions in its "active memory", which leads to a noticeable degradation in performance. The agent becomes slower, begins to hallucinate details that aren't there, and eventually starts throwing errors, leading the frustrated user to conclude that the platform isn't ready for prime time.

Making Extensions Dynamic

The goose team initially combatted this by adding dynamic extensions, which allow the system to keep most tools dormant until the agent specifically identifies a need for them. While this was a massive step toward efficiency, it remained a somewhat hidden feature that many casual users rarely discovered. I spent plenty of time watching people operate with a huge list of active extensions, cringing as I realized they were wasting tokens on extensions and tools they weren't even using.

Code Mode Explained

Code Mode resolves the issue of extension bloat by taking this idea of limiting tools a step further. I first learned about this concept from a Cloudflare blog post where they proposed agents should write JavaScript or TypeScript that decides which tools to call and how, and then runs that logic in one execution instead of calling tools one step at a time. Instead of forcing the LLM to memorize a hundred different tool definitions, you provide it with just three foundational tools: search_modules, read_module, and execute_code. The agent then learns to find what it needs on the fly and writes a custom script to chain those actions together in a single execution.

Code Mode Doesn't Replace MCP

When the concept of Code Mode landed on socials, many people claimed it was a replacement for MCP. Actually, Code Mode still uses MCP under the hood. The tools it discovers and executes are still MCP tools. Think of it like HTTP and REST: HTTP is the underlying protocol that makes communication possible, while REST is an architectural pattern built on top of it. Similarly, MCP is the protocol that standardizes how agents connect to tools, and Code Mode is a pattern for how agents interact with those tools more efficiently. In fact, the goose ecosystem actually treats Code Mode as an MCP server (extension).

How goose Implemented Code Mode

goose took a unique approach by making Code Mode itself an extension called the Code Execution extension. When active, it wraps your other extensions and exposes them as JavaScript modules, allowing the LLM to see only three tools instead of eighty.

When the agent needs to perform a complex task, it writes a script that looks something like this:

import { shell, text_editor } from "developer";

const branch = shell({ command: "git branch --show-current" });
const commits = shell({ command: "git log -3 --oneline" });
const packageJson = text_editor({ path: "package.json", command: "view" });
const version = JSON.parse(packageJson).version;

text_editor({ 
  path: "LOG.md", 
  command: "write", 
  file_text: `# Log\n\nBranch: ${branch}\n\nCommits:\n${commits}\n\nVersion: ${version}` 
});

Code Mode vs. No Code Mode

In addition to reading about Code Mode, I had to try it out, so I could really understand how it works. So, I conducted an experiment where I compared my experience with Code Mode and without Code Mode. I used Claude Opus 4.5, enabled eight different extensions, and gave the agent a straightforward, but multi-step prompt to see how it handled the load:

"Create a LOG.md file with the current git branch, last 3 commits, and the version from package.json"

Without Code Mode

When I ran this test with Code Mode disabled, goose successfully performed five separate tool calls to gather the data and write the file. However, because all eight extensions had their full definitions loaded into the context, this relatively simple task consumed 16% of my total context window. This demonstrates the clear scalability issues of standard workflows, as the system becomes increasingly unstable and prone to failure when you aren't using Code Mode.

With Code Mode

When I toggled Code Mode on and ran the exact same prompt, the experience changed completely. The agent used its discovery tools to find the necessary modules and wrote a single, unified JavaScript script to handle the entire workflow at once. In this scenario, only 3% of the context window was used.

This means I can have a longer session before the model's performance begins to degrade or it begins to hallucinate under the weight of too many tools.

The Value of Code Mode

This exercise cleared up a few misconceptions I had about Code Mode's behavior in goose.

I thought it would make tasks execute faster: Code Mode doesn't necessarily speed up task execution; in fact, I noticed additional round-trips because the LLM has to discover tools and write JavaScript before it can act.
I thought it was for every task: If you are only using one or two tools, the overhead of writing and executing code might actually be more work than just calling the tool directly.

However, Code Mode shines when goose:

Has too many extensions enabled
Needs to perform multi-step orchestration
Needs to stay coherent over a long-running session

Therefore, it doesn't make sense for me to use Code Mode when:

I only have 1-2 extensions enabled
The task is single-step
Speed matters more than context longevity

Improving Code Mode Support in goose

The cool part is Code Mode is only getting better. The team is currently refining Code Mode following its release in goose v1.17.0 (December 2025):

Better UX - showing what tools are being called instead of raw JavaScript
Better reliability - improving type signatures so LLMs get the code right the first time
More capabilities - enabling subagents to work inside Code Mode

Code Mode helps us take a step forward in building agents that can scale to handle all your tools without falling apart. I love seeing how MCP is evolving, and I can't wait for the day I tell my children that agents weren't always this limitless and that we actually used to have to ration our tools just to get a simple task done.

Ready to try Code Mode? Enable the "Code Execution" extension in goose v1.17.0 or later. Join our Discord to share your experience!

Does Your AI Agent Need a Plan?

Rizèl Scarlett — Sat, 20 Dec 2025 06:32:47 +0000

To plan or not to plan, that's the wrong question. Rather than a binary yes/no, planning exists on a spectrum. The real question is which approach fits your current task and working style.

Different developers approach planning in different ways. One builder might draft detailed pseudocode before touching a keyboard, while another practices test driven development to let the architecture emerge organically. You'll find teams sketching complex diagrams on whiteboards and others spinning up fast prototypes to "fail fast" and refactor later.

If planning is a spectrum when coding manually, why wouldn't it be a spectrum when using an agent to code as well?

Lately, there's been a healthy debate in the industry about planning in AI coding agents. While some find dedicated plan modes essential, others see them as unnecessary overhead. After all, you can always just tell an agent to "make a plan first." Some even argue that if you need a durable plan, you should write it in a file yourself so you can see it, edit it, and version it alongside your code.

This reveals an interesting truth: the value of a plan mode isn't just about the plan itself. It's about creating the right mental model and workflow for the developer using it. Sometimes you want the agent to just execute. Other times, you want to see its thinking, provide feedback, and collaborate on the approach before any code changes happen.

Rather than picking one philosophy, goose supports multiple approaches because different situations call for different methods.

Choose Your Strategy

For The Architect

/plan Mode

When you enter plan mode in the goose CLI, goose shifts into an interactive dialogue. Instead of immediately executing, it asks clarifying questions to understand your project deeply. It might ask about your tech stack preferences, authentication requirements, deployment targets, or how you want to handle error cases. This back and forth continues until goose has enough context to generate a comprehensive, actionable plan.

Plan mode uses a separate planner configuration that you can customize. By setting GOOSE_PLANNER_PROVIDER and GOOSE_PLANNER_MODEL environment variables, you can use one model for strategic planning and a different model for execution. When you're satisfied with the plan, goose asks if you want to clear the message history and act on it, giving you a clear checkpoint before any code changes happen.

I used this approach recently when converting a static Vite/React project to Next.js. I understood the scope clearly since it's a common migration pattern, so I asked goose to make a comprehensive plan before starting any work. It produced an 11 phase migration plan with specific checkboxes for each step, covering everything from dependency updates to routing changes to component boundaries. Once I approved, I said "yes start" and goose executed methodically, committing after each phase.

Learn more about creating plans →

For The Director

Instruction Files

Sometimes you already know exactly what needs to happen. You've thought through the steps, you've made the decisions, and you just need goose to do the work. Instead of explaining your plan through conversation, you write it down and hand it over.

You can write your instructions in a markdown file as a detailed execution plan, a living document that guides goose through implementation step by step. The plan can include context about the codebase, specific files to modify, expected outcomes, and validation steps. When you're ready, you run it with goose run -i plan.md and goose executes what you've specified.

This approach works when you've already done the thinking. Maybe you sketched the architecture on a whiteboard. Maybe you wrote a technical design doc. Maybe you just know this codebase well enough that you don't need goose to ask clarifying questions. You write the spec, goose executes it.

You can also run instruction files in headless mode for CI/CD pipelines or automation, but that's just one use case. The core idea is: you own the plan, goose owns the execution.

Learn more about running tasks →

For The Explorer

Conversational Context Building

This approach combines three goose features that work together:

Conversational planning means treating goose as a pairing partner rather than a task executor. You ask goose to analyze, explain, and explore. You build a shared mental model together. Then, when you're ready, you shift into execution.

The todo extension watches for complexity in the background. When goose recognizes that a task has two or more steps, involves multiple files, or has uncertain scope, it automatically creates a checklist. As goose works, it updates progress and checks off completed items. The plan emerges from the work rather than preceding it.

Project rules provide invisible scaffolding. Using files like goosehints or agents.md, you encode persistent preferences, commit policies, testing requirements, project conventions, that automatically steer the agent in the right direction. This gives goose the context to make better decisions without you repeating the rules every time.

Together, these features let you have a casual, exploratory conversation while maintaining structure underneath. You scope your prompts deliberately. The todo extension creates organization when complexity appears. The project rules ensure your preferences are always in play.

This is typically how I work. When I migrated a legacy LLM credit provisioning app to Next.js, many cringed at my approach. However, in context, I was returning to a codebase I'd built eight months earlier and didn't remember well. The app was split across two repositories and I didn't know which one handled what. Writing a plan.md file upfront would have been guessing.

So I asked goose to analyze both projects and explain how they communicated. I scoped my prompts deliberately: "just the frontend, no API calls." I had the todo extension enabled, knowing it would create structure once the scope became clear. I had project rules configured to handle commits automatically.

The approach took more back and forth than an upfront plan would have. But those prompts weren't wasted effort. They were building the context that made the actual migration possible. By the time goose created its checklist, we both understood what needed to happen.

Learn more about the todo extension →

Configure your project rules with goosehints →

What's Your Style?

goose supports multiple planning philosophies because developers don't work in a single mode. The architect wants clarity before code. The director wants control. The explorer discovers the plan through the work.

None of these approaches is superior. Each fits different situations. The same developer might use /plan mode for a well scoped migration on Monday and conversational context building for an unfamiliar codebase on Tuesday.

The question isn't whether to plan. The question is which kind of planning fits your situation today.

Ready to try different planning approaches with goose? Start with our quickstart guide or explore the context engineering documentation to set up your scaffolding.

How I Built an MCP App to Roast My GitHub Year in Review

Rizèl Scarlett — Sat, 20 Dec 2025 06:07:09 +0000

I love GitHub Unwrapped because it lets me see all the progress (or lack of progress) I've made over the past year. Sidenote: I will be posting my GitHub Unwrapped on December 31st.

I wanted to take that idea one step further.

So instead of just looking at my stats, I built an MCP App that:

Pulls your GitHub activity for 2025
Shows you your commits, repos, top languages, and more
Gives you one roast
And one compliment

Here's my repo.

// Detect dark theme var iframe = document.getElementById('tweet-2002242591719395665-192'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2002242591719395665&theme=dark" }

What Are MCP Apps and Why I Care

I've been following the MCP (Model Context Protocol) ecosystem, you know that MCP servers have been limited to text and structured data. That's great for a lot of things, but what if your tool needs to show something visual? Or collect complex input from a user?

That's where MCP Apps come in.

MCP Apps are a new extension to MCP that lets servers render interactive UIs right inside the host application. The spec just dropped a few weeks ago, but it's one of the most requested features from the community.

MCP-UI was it's precursor, and I've played around with that a ton because my company build an AI agent called goose that actually has MCP support.

Here's a video of me showing off goose and MCP-UI, but I'm excited that it's going to become an official standard now.

I wanted to learn if there were any differences between building MCP Apps and MCP-UI. (And I secretly want to get more involved with shaping the future of MCP Apps), so I decided to build something fun and quick. Hence: the GitHub Year in Review with roasts. I also took this as an opportunity to learn a little more about MCP resources. I've used MCP servers before, but never had to set them up.

What I Built

The app has three MCP patterns working together:

Resource → github://user/{username}/2025-review

This exposes the cached review data so other tools or LLMs can read it.

Tool → get-year-in-review

This does the heavy lifting—fetches your GitHub data, crunches the stats, and generates your roast and compliment.

Prompt → year-in-review

A template that helps LLMs know how to ask for a review.

Plus an interactive UI that lets you type in any GitHub username and see the results.

Let's Build It

Project Setup

First, create a new directory and set things up:

mkdir github-year-review && cd github-year-review
npm init -y

Install the dependencies:

npm install @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps zod
npm install -D typescript vite vite-plugin-singlefile express cors @types/express @types/cors tsx

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["*.ts", "src/**/*.ts"]
}

Create vite.config.ts:

import { defineConfig } from "vite";
import { viteSingleFile } from "vite-plugin-singlefile";

export default defineConfig({
  plugins: [viteSingleFile()],
  build: {
    outDir: "dist",
    rollupOptions: {
      input: process.env.INPUT,
    },
  },
});

Update your package.json scripts:

{
  "type": "module",
  "scripts": {
    "build": "INPUT=mcp-app.html vite build",
    "serve": "npx tsx server.ts"
  }
}

The Server

Create server.ts. I'll walk through the important parts.

First, the setup and GitHub auth:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { type McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
import cors from "cors";
import express from "express";
import fs from "node:fs/promises";
import path from "node:path";
import * as z from "zod";

const server = new McpServer({
  name: "GitHub Year in Review 2025",
  version: "1.0.0",
});

// GitHub token is optional but gives you higher rate limits
const GITHUB_TOKEN = process.env.GITHUB_TOKEN;

const githubHeaders: Record<string, string> = {
  "User-Agent": "MCP-GitHub-Review",
  "Accept": "application/vnd.github.v3+json",
};

if (GITHUB_TOKEN) {
  githubHeaders["Authorization"] = `Bearer ${GITHUB_TOKEN}`;
  console.log("✅ GitHub token found");
} else {
  console.log("⚠️  No GITHUB_TOKEN - you'll hit rate limits faster");
}

const userCache = new Map<string, any>();

Fetching GitHub Data

Here's where I fetch the data. I use the GraphQL API when possible because it gives more accurate contribution counts:

async function fetchGitHubUser(username: string) {
  const response = await fetch(`https://api.github.com/users/${username}`, {
    headers: githubHeaders,
  });
  if (!response.ok) throw new Error(`User not found: ${username}`);
  return response.json();
}

async function fetchGitHub2025Activity(username: string) {
  // Fetch repos
  const reposResponse = await fetch(
    `https://api.github.com/users/${username}/repos?per_page=100&sort=updated`,
    { headers: githubHeaders }
  );
  const repos = await reposResponse.json();

  let totalContributions = 0;
  let totalCommits = 0;

  // GraphQL gives us the real contribution count
  if (GITHUB_TOKEN) {
    const graphqlQuery = {
      query: `query($username: String!) {
        user(login: $username) {
          contributionsCollection(from: "2025-01-01T00:00:00Z", to: "2025-12-31T23:59:59Z") {
            contributionCalendar { totalContributions }
            totalCommitContributions
          }
        }
      }`,
      variables: { username },
    };

    const graphqlResponse = await fetch("https://api.github.com/graphql", {
      method: "POST",
      headers: { ...githubHeaders, "Content-Type": "application/json" },
      body: JSON.stringify(graphqlQuery),
    });

    const data = await graphqlResponse.json();
    const contributions = data?.data?.user?.contributionsCollection;

    if (contributions) {
      totalContributions = contributions.contributionCalendar?.totalContributions || 0;
      totalCommits = contributions.totalCommitContributions || 0;
    }
  }

  // Fallback if no token
  if (totalContributions === 0) {
    const commitsResponse = await fetch(
      `https://api.github.com/search/commits?q=author:${username}+committer-date:2025-01-01..2025-12-31&per_page=1`,
      { headers: { ...githubHeaders, Accept: "application/vnd.github.cloak-preview" } }
    );
    const commitsData = await commitsResponse.json();
    totalCommits = commitsData.total_count || 0;
    totalContributions = totalCommits;
  }

  // Get top languages from repos
  const languages: Record<string, number> = {};
  repos.forEach((repo: any) => {
    if (repo.language) {
      languages[repo.language] = (languages[repo.language] || 0) + 1;
    }
  });
  const topLanguages = Object.entries(languages)
    .sort((a, b) => b[1] - a[1])
    .slice(0, 5)
    .map(([lang]) => lang);

  // Count repos created in 2025
  const repos2025 = repos.filter((repo: any) => 
    new Date(repo.created_at).getFullYear() === 2025
  );

  return {
    totalContributions,
    totalCommits,
    reposCreated: repos2025.length,
    topLanguages,
    starsEarned: repos2025.reduce((sum: number, repo: any) => sum + (repo.stargazers_count || 0), 0),
  };
}

A Quick Note on Data Accuracy

I spent way too long trying to get the contribution count to match what I see on my GitHub profile. Turns out, the API only shows public contributions—if you're in private orgs (like I am at Block), those don't show up unless you have special token permissions.

I built this to learn MCP Apps, not to solve GitHub's API quirks, so I moved on. Just know your numbers might be lower than expected if you work in private repos!

The Roast and Compliment Generator

This is the fun part:

function generateRoastAndCompliment(profile: any, stats: any) {
  const roasts = [];
  const compliments = [];

  // Roasts
  if (stats.totalContributions < 50) {
    roasts.push(`${stats.totalContributions} contributions in 2025? Your GitHub is basically a digital ghost town. 👻`);
  } else if (stats.totalContributions > 2000) {
    roasts.push(`${stats.totalContributions} contributions? Either you're a machine or you need to touch grass. 🤖`);
  }

  if (stats.reposCreated === 0) {
    roasts.push("Zero new repos in 2025? Living dangerously by not starting projects you'll never finish.");
  }

  if (stats.topLanguages.includes("JavaScript") && !stats.topLanguages.includes("TypeScript")) {
    roasts.push("Still writing JavaScript without TypeScript in 2025? Living life on hard mode. 💀");
  }

  if (!profile.bio) {
    roasts.push("No bio? The mystery is not as intriguing as you think. 🕵️");
  }

  // Compliments
  if (stats.totalContributions > 500) {
    compliments.push(`${stats.totalContributions} contributions shows real dedication. You actually showed up this year! 💪`);
  }

  if (stats.starsEarned > 0) {
    compliments.push(`${stats.starsEarned} stars earned in 2025! People actually like what you're building. ⭐`);
  }

  if (stats.topLanguages.length >= 3) {
    compliments.push(`Polyglot energy! You worked with ${stats.topLanguages.slice(0, 3).join(", ")} this year. 👑`);
  }

  if (stats.topLanguages.includes("TypeScript")) {
    compliments.push("TypeScript user? You believe in type safety and sanity. A true professional. ✨");
  }

  if (stats.topLanguages.includes("Rust")) {
    compliments.push("Rust in your stack? Big brain energy. 🦀");
  }

  const roast = roasts[Math.floor(Math.random() * roasts.length)] 
    || "Your GitHub is so vanilla I can't even roast it. 😐";
  const compliment = compliments[Math.floor(Math.random() * compliments.length)] 
    || "You have a GitHub account and that's more than most people! 🏟️";

  return { roast, compliment };
}

Registering the MCP Stuff

Now we wire up the Resource, Tool, and Prompt:

// Resource - exposes the cached data
server.registerResource(
  "github://user/{username}/2025-review",
  "github://user/{username}/2025-review",
  { mimeType: "application/json" },
  async (uri) => {
    const match = uri.href.match(/github:\/\/user\/([^/]+)\/2025-review/);
    const username = match?.[1];

    if (!username || !userCache.has(username)) {
      return {
        contents: [{
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify({ error: "Call get-year-in-review first" }),
        }],
      };
    }

    return {
      contents: [{
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify(userCache.get(username)),
      }],
    };
  }
);

// Tool - this is what actually does the work
const resourceUri = "ui://github-review/mcp-app.html";

server.registerTool(
  "get-year-in-review",
  {
    title: "Get GitHub Year in Review",
    description: "Fetches a GitHub user's 2025 activity and generates a roast and compliment.",
    inputSchema: {
      username: z.string().describe("GitHub username to review"),
    },
    _meta: { ui: { resourceUri } as McpUiToolMeta },
  },
  async ({ username }) => {
    const profile = await fetchGitHubUser(username);
    const stats = await fetchGitHub2025Activity(username);
    const { roast, compliment } = generateRoastAndCompliment(profile, stats);

    const review = {
      username: profile.login,
      avatarUrl: profile.avatar_url,
      name: profile.name,
      stats,
      roast,
      compliment,
    };

    userCache.set(username, review);

    return {
      content: [{ type: "text", text: `${roast} | ${compliment}` }],
      structuredContent: review,
    };
  }
);

// Prompt - helps LLMs know how to use this
server.registerPrompt(
  "year-in-review",
  {
    title: "GitHub Year in Review",
    description: "Generate a year in review for a GitHub user.",
    inputSchema: {
      username: z.string().describe("GitHub username"),
    },
  },
  async ({ username }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Use get-year-in-review to fetch the 2025 GitHub Year in Review for "${username}".`,
      },
    }],
  })
);

// UI Resource - serves the HTML
server.registerResource(
  resourceUri,
  resourceUri,
  { mimeType: "text/html;profile=mcp-app" },
  async () => {
    const html = await fs.readFile(
      path.join(import.meta.dirname, "dist", "mcp-app.html"),
      "utf-8"
    );
    return {
      contents: [{ uri: resourceUri, mimeType: "text/html;profile=mcp-app", text: html }],
    };
  }
);

Express Server

Finally, set up the Express server:

const app = express();
app.use(cors());
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
  });
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3001, () => {
  console.log("🎉 Server running at http://localhost:3001/mcp");
});

The UI

Create mcp-app.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>GitHub Year in Review 2025</title>
    <style>
      * { margin: 0; padding: 0; box-sizing: border-box; }

      body {
        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
        min-height: 100vh;
        background: linear-gradient(135deg, #0d1117 0%, #161b22 50%, #21262d 100%);
        color: #e6edf3;
        padding: 20px;
      }

      .container { max-width: 500px; margin: 0 auto; }

      .header { text-align: center; margin-bottom: 24px; }

      .header h1 {
        font-size: 24px;
        background: linear-gradient(90deg, #58a6ff, #a371f7, #f778ba);
        -webkit-background-clip: text;
        -webkit-text-fill-color: transparent;
      }

      .search-box { display: flex; gap: 12px; margin-bottom: 24px; }

      .search-box input {
        flex: 1;
        padding: 12px 16px;
        border-radius: 8px;
        border: 1px solid #30363d;
        background: #0d1117;
        color: #e6edf3;
        font-size: 16px;
      }

      .search-box button {
        padding: 12px 24px;
        border-radius: 8px;
        border: none;
        background: linear-gradient(135deg, #238636, #2ea043);
        color: white;
        font-weight: 600;
        cursor: pointer;
      }

      .profile-card, .verdict-card {
        background: #161b22;
        border: 1px solid #30363d;
        border-radius: 12px;
        padding: 24px;
        margin-bottom: 16px;
        display: none;
      }

      .profile-card.visible, .verdict-card.visible { 
        display: block; 
        animation: fadeIn 0.5s ease;
      }

      @keyframes fadeIn {
        from { opacity: 0; transform: translateY(10px); }
        to { opacity: 1; transform: translateY(0); }
      }

      .profile-header { display: flex; align-items: center; gap: 16px; margin-bottom: 20px; }
      .avatar { width: 80px; height: 80px; border-radius: 50%; }

      .stats-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
      .stat-item { background: #0d1117; border-radius: 8px; padding: 12px; text-align: center; }
      .stat-value { font-size: 24px; font-weight: 700; color: #58a6ff; }
      .stat-label { font-size: 11px; color: #8b949e; text-transform: uppercase; }

      .verdict-card.roast { border-left: 4px solid #f85149; }
      .verdict-card.compliment { border-left: 4px solid #3fb950; }

      .verdict-header { font-weight: 600; text-transform: uppercase; margin-bottom: 12px; }
      .roast .verdict-header { color: #f85149; }
      .compliment .verdict-header { color: #3fb950; }
    </style>
  </head>
  <body>
    <div class="container">
      <div class="header">
        <h1>✨ GitHub Year in Review 2025</h1>
        <p style="color: #8b949e; margin-top: 8px;">Get your stats, a roast, and a compliment</p>
      </div>

      <div class="search-box">
        <input type="text" id="username-input" placeholder="Enter GitHub username" />
        <button id="review-btn">Review</button>
      </div>

      <div class="profile-card" id="profile-card">
        <div class="profile-header">
          <img class="avatar" id="avatar" src="" alt="Avatar" />
          <div>
            <h2 id="name">Name</h2>
            <div style="color: #8b949e;" id="profile-username">@username</div>
          </div>
        </div>
        <div class="stats-grid">
          <div class="stat-item">
            <div class="stat-value" id="contributions">0</div>
            <div class="stat-label">Contributions</div>
          </div>
          <div class="stat-item">
            <div class="stat-value" id="repos-created">0</div>
            <div class="stat-label">New Repos</div>
          </div>
          <div class="stat-item">
            <div class="stat-value" id="commits">0</div>
            <div class="stat-label">Commits</div>
          </div>
        </div>
      </div>

      <div class="verdict-card roast" id="roast-card">
        <div class="verdict-header">🔥 The Roast</div>
        <div id="roast-text"></div>
      </div>

      <div class="verdict-card compliment" id="compliment-card">
        <div class="verdict-header">💚 The Compliment</div>
        <div id="compliment-text"></div>
      </div>
    </div>
    <script type="module" src="/src/mcp-app.ts"></script>
  </body>
</html>

Create src/mcp-app.ts:

import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";

const usernameInput = document.getElementById("username-input") as HTMLInputElement;
const reviewBtn = document.getElementById("review-btn") as HTMLButtonElement;
const profileCard = document.getElementById("profile-card")!;
const roastCard = document.getElementById("roast-card")!;
const complimentCard = document.getElementById("compliment-card")!;

const app = new App({ name: "GitHub Year in Review 2025", version: "1.0.0" });

function updateUI(review: any) {
  (document.getElementById("avatar") as HTMLImageElement).src = review.avatarUrl;
  document.getElementById("name")!.textContent = review.name || review.username;
  document.getElementById("profile-username")!.textContent = `@${review.username}`;

  document.getElementById("contributions")!.textContent = review.stats.totalContributions;
  document.getElementById("repos-created")!.textContent = review.stats.reposCreated;
  document.getElementById("commits")!.textContent = review.stats.totalCommits;

  document.getElementById("roast-text")!.textContent = review.roast;
  document.getElementById("compliment-text")!.textContent = review.compliment;

  profileCard.classList.add("visible");
  setTimeout(() => roastCard.classList.add("visible"), 200);
  setTimeout(() => complimentCard.classList.add("visible"), 400);
}

reviewBtn.addEventListener("click", async () => {
  const username = usernameInput.value.trim();
  if (!username) return;

  reviewBtn.disabled = true;
  reviewBtn.textContent = "Loading...";

  profileCard.classList.remove("visible");
  roastCard.classList.remove("visible");
  complimentCard.classList.remove("visible");

  try {
    const result = await app.callServerTool({
      name: "get-year-in-review",
      arguments: { username },
    });
    updateUI(result.structuredContent);
  } catch (error) {
    console.error(error);
  }

  reviewBtn.disabled = false;
  reviewBtn.textContent = "Review";
});

usernameInput.addEventListener("keypress", (e) => {
  if (e.key === "Enter") reviewBtn.click();
});

app.connect(new PostMessageTransport(window.parent));

Run It

Build the UI:

npm run build

Start the server (get a token from https://github.com/settings/tokens . I didn't add any scopes to mine.):

GITHUB_TOKEN=your_token_here npm run serve

Additional Reading and Resources

MCP Apps Blog Post - The announcement explaining why this matters
Official Quickstart - If you want the basics first
SEP-1865 - The full spec if you're into that
My repo