App Tools

Workhog provides three specialized tool systems for building, editing, and debugging HTML apps: the App Debugger, the App Editor, and the App Scaffold. Together, they let the AI agent create apps from templates, make surgical edits to large files, and diagnose issues without you describing anything in chat.

App Debugger

The mcp__app_debugger tools give the AI agent direct visibility into your running app. Instead of you describing what went wrong (see why in the Inspection vs. Prompting comparison), the agent captures console output, evaluates expressions, and takes screenshots on its own.

get_console_logs

Captures all console output from the app iframe — console.log,console.error, console.warn, and uncaught exceptions. Additionally, the tool runs smart diagnostics that auto-detect common issues:

  • SDK initialization status — confirms the Workhog SDK connected successfully
  • File list success — verifies workspace file listing completed
  • Auth errors — flags OAuth or permission problems
Example console log outputjson
[
  { "level": "log",   "message": "Workhog SDK connected", "timestamp": 1706820000 },
  { "level": "error", "message": "TypeError: Cannot read property 'amount' of undefined", "timestamp": 1706820001 },
  { "level": "warn",  "message": "No transactions found for date range", "timestamp": 1706820002 }
]

evaluate

Runs arbitrary JavaScript inside the app iframe and returns the result. This lets the agent inspect runtime state without guessing:

Example evaluate expressionsjavascript
// Check how many transactions loaded
document.querySelectorAll('.transaction-row').length

// Verify a calculation
parseFloat(document.getElementById('total-revenue').textContent.replace('$', ''))

// Inspect app state
JSON.stringify(window.__APP_STATE__, null, 2)

get_screenshot

Captures the current viewport of the app as an image. The agent can visually inspect layout, styling, broken elements, and rendering issues. The screenshot is saved to your workspace so the agent can reference it in follow-up turns.

Visual debugging is automatic

When you say "debug this," the agent automatically calls get_console_logs,evaluate, and get_screenshot in sequence. You never need to manually request each tool.

Why Better Than Prompting

Without Debugger

You:

"The chart isn't showing any data. I think the fetch is failing but I'm not sure. The console might have an error."

Claude:

"Can you open DevTools and tell me what errors you see? What does the Network tab show?"

You:

"TypeError: Cannot read property 'map' of undefined at line 47"

Claude:

"Can you share the code around line 47?"

4+ messages of back-and-forth to identify the bug

With Debugger

You:

"Debug this"

Claude automatically runs:

1
get_console_logs → TypeError at line 47
2
evaluate → data variable is undefined
3
get_screenshot → blank chart area visible

Claude:

"Found it. The fetch response isn't being awaited on line 42. Fixing now."

1 message. Bug found and fixed.

App Editor

The mcp__app_editor tools provide section-based editing for large HTML files. Instead of rewriting an entire file (which risks accidental damage and hits file size limits), the editor reads and writes individual sections by name.

Section Markers

Files are divided into named sections using marker comments. The editor supports two marker styles:

HTML comment markershtml
<!-- ===== SECTION: header ===== -->
<header class="app-header">
  <h1>My Dashboard</h1>
  <nav>...</nav>
</header>
<!-- ===== END SECTION: header ===== -->

<!-- ===== SECTION: chart ===== -->
<div id="chart-container">
  <canvas id="revenue-chart"></canvas>
</div>
<!-- ===== END SECTION: chart ===== -->
JS/CSS comment markersjavascript
/* ===== SECTION: data-fetch ===== */
async function loadData() {
  const res = await fetch('/api/revenue');
  return res.json();
}
/* ===== END SECTION: data-fetch ===== */

Editor Tools

list_sections

Shows all sections in the file with their line counts. Use this first to understand the file structure before making edits.

read_section

Reads the content of a single named section. Returns only the content between markers, not the markers themselves.

write_section

Replaces a section's content entirely. The markers are preserved. Only the content between them changes.

search_sections

Searches across all sections for a pattern. Returns matching sections with line numbers and context.

read_multi_sections

Reads multiple sections at once. More efficient than calling read_section repeatedly.

Why section-based editing is superior

Traditional file editing rewrites the entire file on every change. For a 300KB HTML app, that means re-sending 300KB even to change one line. Section-based editing is:

  • Safer — prevents accidental damage to unrelated sections
  • Scalable — no file size limits (apps can grow to 500KB+)
  • Atomic — each write operation targets exactly one section
  • Auditable — you can see which sections changed in version history

App Scaffold

The mcp__scaffold tools generate new HTML apps from battle-tested templates. Every template includes SDK initialization, error handling, dark mode, and diagnostics — so the agent starts from a solid foundation instead of writing boilerplate.

create_html_app

Creates a new HTML app file from a named template. Available templates:

basic

Minimal app with SDK init, error handling, and dark mode

image-gallery

4-column image grid with lightbox view from workspace files

data-viewer

CSV/JSON table display with search and filtering

chart

Chart.js integration that loads data from workspace files

form

Input form with state persistence across sessions

Built-In Features

Every scaffold template includes these features out of the box, so the agent does not need to implement them manually:

SDK initialization — 5-second connection timeout with retry
Standalone detection — works outside Workhog with mock data
AFS.diagnose() — built-in health check function
Dark mode — automatic theme matching with Workhog
Error handling — global error boundary with user-friendly display
Section markers — pre-defined for App Editor compatibility
Example

Try it yourself:

Ask Claude to "create a chart app that shows monthly revenue" and it will use the scaffold chart template to generate a fully functional app with SDK initialization, data loading, and Chart.js integration already wired up.

Best Practices

1

Use the debugger before describing bugs

Just say "debug this" instead of manually inspecting DevTools and pasting errors. The agent captures console logs, evaluates state, and takes a screenshot in one step.

2

Use scaffold for new apps

Starting from a template saves time and prevents common mistakes like missing SDK initialization, broken error handling, or dark mode mismatches.

3

Use the editor for large apps

Once an app exceeds a few hundred lines, section-based editing is safer and faster than full-file rewrites. The agent can read just the section it needs.

4

Add section markers early

When the agent creates an app from scaffold, sections are already defined. If you build from scratch, ask the agent to add section markers so future edits are surgical.

5

Let diagnose() do the talking

Every scaffold template includes AFS.diagnose(). If the app seems broken, the agent can call evaluate("AFS.diagnose()") to get a full health report.

Next Steps

App Tools - Workhog Help