The apps-in-toss-harness is an open-source monorepo project designed as an AI agent harness to streamline the entire lifecycle of "Apps in Toss" mini-app development. It enables developers to perform scaffolding, local development, debugging, bundling, and registration entirely within AI coding environments such as Claude Code, Codex, and Cursor, without leaving the IDE interface.

Core Methodology and Architecture

The harness acts as an orchestrator that integrates agent skills and Model Context Protocol (MCP) servers to automate tasks that would otherwise require manual context switching. The system is built on a pnpm monorepo structure containing three primary packages:

• @apps-in-toss/agent-plugin: The central orchestrator that maps user natural language requests or $/ait:<verb>$ slash commands to specific development skills and manages MCP manifest injection.
• @apps-in-toss/debugger: A specialized MCP-based daemon that facilitates on-device debugging, acting as a Chrome DevTools Protocol (CDP) relay and dev bridge.
• @apps-in-toss/debug-console: A lightweight runtime package designed for integration into production bundles to enable on-device debugging in controlled environments.

Technical Workflow

The harness manages development through a defined sequence of "stations" (states), utilizing two fundamental MCP servers for integration:

1. apps-in-toss-docs: An MCP server providing instant access to developer documentation, enabling the agent to context-awaken with official rules and constraints.
2. ait-console: An OAuth-authenticated MCP server that interfaces with the Toss mini-app console, allowing the agent to perform administrative operations such as miniapp_create, bundle_upload, and bundle_list securely.

Development Lifecycle Features

• Scaffolding: Utilizing create-ait-app, the agent performs greenfield project setup, injecting design tokens, icons, and the "Tossface" emoji typeface based on defined AGENTS.md rules.
• Debugging: The system provides setup-debugger to wire the MCP debugger into the project's .mcp.json (or .cursor/mcp.json). This allows the agent to analyze local and on-device states to resolve environment-specific bugs.
• Testing and Launch: The /ait:test-on-device command triggers an automated pipeline: building the bundle, uploading it via the console MCP, validating the compilation, and returning a URL for live testing in the Toss app. The /ait:launch command audits the code against official checklists before requesting review.
• Design and UX: Through the /ait:design skill, the agent manages aesthetic consistency, verifying compliance with hard constraints (e.g., minimum touch targets of 44px, safe-area CTA spacing) and automatically correcting code that violates design guidelines.

Technical Constraints and Implementation

• Communication Protocol: shared/internal-protocol provides the wire-protocol for device-to-host communication, ensuring the debugger and console packages maintain synchronization.
• Authentication: The harness enforces an OAuth (RFC 9728) flow for the ait-console server. It explicitly excludes the use of static Deploy Keys, preferring the session-based OAuth model to maintain higher security standards.
• Environment-Specific Adapters: The harness detects the host agent environment (e.g., Cursor vs. Claude Code) and dynamically adjusts its skill injection—such as using native tool execution for Cursor or command-line stubs for Claude Code—to ensure compatibility while maintaining a unified user interface for the developer.