OpenCode + Browser Annotations: The Open Source Stack

A bug report lands. It's 4:45 PM on a Friday. "The 'Add to Cart' button on the product page isn't working right. Sometimes it just spins. And it looks weird on my phone." That's it. No URL. No screenshot. No console errors. Just a gut feeling from a user who's probably already moved on.

You've got an AI coding agent like OpenCode humming in the background, ready to churn out fixes. But what do you feed it? That vague, frustrating message? You can't. You'd get garbage back. The agent needs context. It needs precision. It needs to see what's broken, where it's broken, and how it's broken, without you playing twenty questions with a non-technical stakeholder.

The Pitfall of Ambiguity: Why Text Fails AI

We've all been there. Endless Slack threads. "Which button?" "The blue one." "The other blue one?" Screenshots with big red circles drawn in Paint. This isn't just inefficient; it's a productivity black hole. When you're trying to describe a visual defect or an interaction bug to another human, it's already tough. When you're trying to explain it to an AI agent, it's impossible.

AI coding agents, OpenCode included, thrive on structured, contextual data. They don't have eyes. They can't click around your site. They can't infer intent from "it looks weird." If you feed it a prompt like "fix the broken button on the product page," OpenCode will give you a generic button fix, if anything at all. It won't know if you mean src/components/AddToCartButton.tsx, or div.product-card > button.add-to-cart, or that specific instance of the component nested deep in a complex DOM tree. You need to translate the visual problem into code-level context. That's the critical gap.

OpenCode: The Agent That Demands Clarity

OpenCode is powerful. It can write code, refactor, debug. It understands frameworks, design patterns, and common pitfalls. But its intelligence is only as good as the input you provide. Think of it as a brilliant but blind engineer. You wouldn't hand a blind engineer a vague verbal description of a broken circuit board and expect a perfect fix. You'd give them a detailed schematic, point to the exact faulty component, and explain its role.

That's precisely what you need to do for OpenCode. You can't just type "bug on checkout page." You need to provide the component name, the file path, the exact CSS selector, the DOM context, the specific page URL, and a clear description of the behavioral bug. Without this, OpenCode is guessing. And guessing costs you time, compute cycles, and ultimately, money. The promise of AI-driven development isn't just about faster code generation; it's about accurate faster code generation. Precision is paramount.

The Power of opencode browser annotations

This is where opencode browser annotations become non-negotiable. Forget describing things. Show them. Visual context, captured directly from the browser, provides the immutable, precise data OpenCode needs to operate effectively. We're not talking about a quick screenshot. We're talking about capturing the entire environment surrounding a bug or feature request.

When you annotate an element in the browser, you're not just drawing a box. You're extracting the metadata that defines that element's existence in your application's codebase. The component name. Its source file. Its exact CSS path. Its position relative to other elements. This isn't just helpful; it's fundamental for an AI agent to understand the target of its work. Without this rich, structured data, OpenCode is working in the dark. With it, you're providing a detailed blueprint, a surgical map of the problem area. This isn't an optional extra; it's the baseline for meaningful AI interaction. If your AI agent is your co-pilot, then opencode browser annotations are your flight plan.

Markagent: Your OpenCode Sidekick

You can't expect your AI agent to magically infer what you're pointing at. That's where a specialized tool comes in. Enter markagent. It's a Chrome extension built specifically to bridge the gap between visual context and AI agent prompts. Markagent isn't just taking screenshots; it's dissecting the DOM, extracting critical information, and packaging it into an agent-ready prompt.

Here's how it works: you click an element on any webpage. Markagent instantly captures its React component name (if it's a React app in dev mode), the source file path, the full DOM context, a stable CSS selector, the page URL, and the viewport dimensions. It's not a generic tool. It’s an opencode markagent solution, built for the precision AI demands. It even lets you drop a descriptive note and capture a cropped screenshot, tying everything together. This isn't just a convenience; it's a necessity for anyone serious about feeding their AI agent actionable data. You get a markdown prompt, perfectly formatted for tools like OpenCode, Cursor, or Claude Code. One click, all the context. No more "the button on the left, no, the other one." Mark the spot. Ship the prompt.

Crafting an opencode visual workflow

Building an effective opencode visual workflow isn't complicated. It's a structured approach that removes ambiguity from the very first step.

1. Identify the Target: A user reports a bug, or you spot a UI inconsistency. Instead of typing a description, you go directly to the page.
2. Annotate with Precision: Activate your markagent opencode chrome extension. Click the problematic element. Add a brief, clear note describing the issue or desired change. For example, "This button should be disabled until all form fields are valid."
3. Capture Context: Markagent does the heavy lifting. It automatically grabs the component name (e.g., AddToCartButton), its file path (src/components/buttons/AddToCartButton.tsx), a unique CSS selector (#main-product-details > div.actions > button.add-to-cart), the full DOM snippet, and the page URL. It even records the viewport, so OpenCode knows if it's a mobile or desktop issue.
4. Export the Prompt: With a single click, markagent generates a structured markdown prompt. This isn't just text; it's a data-rich instruction set, ready for your AI agent.
5. Engage OpenCode: Paste the markagent output directly into your OpenCode interface. The agent now has all the context it needs: the what, the where, and the how of the problem.
6. Review and Refine: OpenCode generates the proposed code fix. You review it, test it, and deploy.

This workflow drastically cuts down on back-and-forth, ensures the AI agent is working on the exact problem, and accelerates your development cycle. It's the difference between guessing and knowing.

Practical Application: Fixing a Stubborn CSS Bug

Let's walk through a real scenario. Your design team flags an issue: "The product image on the category page is overflowing its container on smaller screens." Classic responsive design headache.

Without opencode browser annotations, you'd open dev tools, inspect, try different media queries, maybe tweak some max-width: 100% rules, all while guessing which specific image and container they're talking about. You'd then try to articulate your findings to OpenCode, probably poorly.

With markagent, you navigate to the category page. You open the opencode chrome extension. You click the overflowing image. Markagent immediately tells you:

• Component: ProductImageGridItem
• File Path: src/components/products/ProductImageGridItem.vue (if you're in dev mode)
• CSS Selector: div.category-grid > div.product-card > img.product-thumbnail
• DOM Context: A small snippet showing the img tag within its parent div.
• URL: https://yourstore.com/category/electronics
• Viewport: 375x667 (iPhone SE)

Your note: "Product image overflows container on mobile. Needs object-fit: cover and potentially a max-width adjustment on the parent div for smaller screens."

Markagent then exports this into a markdown prompt. You feed that directly to OpenCode. OpenCode, armed with this surgical precision, can now propose specific CSS changes to ProductImageGridItem.vue, targeting that exact image and its container, ensuring it behaves correctly at the specified viewport. It won't touch other images or unrelated CSS. That's targeted, efficient AI-assisted debugging.

The Future Is Annotated

AI coding agents are here to stay. They're going to transform how we build software. But they aren't magic. They need precise, unambiguous instructions. The days of "fix the thingy" are over. If you want to get the most out of tools like OpenCode, you must feed them clean, contextual data.

opencode browser annotations isn't just a nice-to-have; it's a fundamental shift in how you interact with your AI coding agent. It’s about clarity, speed, and accuracy. Stop describing. Start showing.

P.S. — markagent is the Chrome extension I use to ship pixel-precise UI feedback to AI coding agents. Free, local, no account.