Documentation

Mira connects stakeholders to AI coding assistants through structured feedback on builds, feature tracks that scope work into features, project context that persists your brand and technical decisions, skills that encode domain knowledge, and subagents that define specialized AI personas. All flow into your coding tool via MCP.

Get started with a single command:

npx @okmira/mcp setup

This opens a browser to authenticate, picks your org and project, and auto-configures your MCP server, API key, .mira.json, and hooks. See Setup for manual configuration options.

1. Deploy a build from your AI coding tool or via git push.
2. Plan — organize work with feature tracks, link to branches, and scope feedback automatically.
3. Shape — stakeholders give feedback with screenshots, create skills (brand rules, design standards), define agents, and build project context through context digests.
4. Fetch everything into your AI assistant via MCP — structured feedback, feature tracks, project context, installable skills, and specialized agents.
5. Apply and deploy again. Status tracking closes the loop — stakeholders see their input was addressed.

Mira connects to your AI coding tool via the Model Context Protocol (MCP) — an open standard supported by 18 tools including Claude Code, Cursor, Copilot, Windsurf, Gemini CLI, Amp, and more.

A complete walkthrough for first-time users — from sign-up to your first feedback loop.

Mira's auto-register hook detects deploy URLs from 7 hosting platforms. For tools with hook support (Claude Code, Codex CLI, Factory.ai, Kiro CLI), builds are registered automatically when a deploy completes.

curl -X POST https://okmira.ai/api/v1/projects/PROJECT_ID/builds \
  -H "Authorization: Bearer ccf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-deploy-url","git_ref":"abc123","track":"main"}'

For git-push deploys that bypass your AI coding tool, set up a Vercel deploy webhook to automatically register builds.

https://okmira.ai/api/webhooks/vercel?token=whk_YOUR_TOKEN

The webhook captures the deploy URL, git ref, branch, and commit message. It accepts both whk_ and ccf_ tokens for backwards compatibility.

Every piece of feedback has three parts, designed to give AI assistants actionable instructions:

Feedback statuses

• Pending — not yet reviewed by the developer
• Acknowledged — developer has seen it
• Applied — feedback has been addressed in a subsequent build
• Stale — no longer relevant

Internal vs external

Internal feedback comes from your agency or team — iterative, candid working feedback. External feedback comes from clients — more formal review feedback. Developers can filter and handle these separately via the MCP tools.

Image attachments

Stakeholders can paste or drag screenshots directly into the feedback form. Images appear on the review page alongside the text feedback, and the AI coding assistant receives them inline when fetching feedback via MCP — no separate links or attachments to manage.

Hooks enable two automations that are currently supported by Claude Code and Codex CLI:

Hooks require a .mira.json in your project root with the project ID. API credentials are read from the MCP server config — no duplication needed.

For tools without hook support (Cursor, Windsurf, Copilot, Gemini CLI), use the Vercel webhook to auto-register builds on deploy.

The embeddable issue widget lets end users report issues directly from your site. Issues appear in the Issues tab on the dashboard, and developers can fetch and triage them via MCP — no email copy-paste needed.

Setup

1. Generate a widget secret — go to the Widget tab in your project settings and generate a secret. Your server will use this to sign JWTs.

2. Sign a JWT on your server — create an HMAC-SHA256 JWT with the widget secret. The payload must include your user's ID and the project ID:

import jwt from "jsonwebtoken";

const token = jwt.sign(
  {
    sub: user.id,           // your user's ID
    pid: "YOUR_PROJECT_ID", // Mira project ID
    name: user.displayName, // optional
    email: user.email,      // optional
  },
  WIDGET_SECRET,
  { expiresIn: "1h" }
);

3. Embed the widget — add the script tag to your page and configure it with the signed JWT:

<script src="https://okmira.ai/api/v1/widget/script?pid=YOUR_PROJECT_ID"></script>
<script>window.Mira.configure({ jwt: serverSignedJwt });</script>
<button data-mira-issues>Report an issue</button>

Activation modes

• data-mira-issues — add to any element to open the widget on click
• window.Mira.openIssueReport({ severity? }) — open programmatically from your code
• data-floating="true" on the script tag — shows a floating action button in the bottom-right corner

MCP integration

Developers use three MCP tools to work with issues: fetch_issues to list and filter reported issues, update_issue_status to change status (open → triaged → in progress → resolved → closed), and assign_issue to take ownership of an issue.

Translations

The widget defaults to English. Pass a labels object to translate any or all UI strings:

window.Mira.configure({
  jwt: serverSignedJwt,
  labels: {
    heading: "Signaler un problème",
    titleLabel: "Titre",
    titlePlaceholder: "Brève description du problème",
    descriptionLabel: "Description",
    descriptionPlaceholder: "Étapes pour reproduire…",
    severityLabel: "Gravité",
    low: "Faible", medium: "Moyen",
    high: "Élevé", critical: "Critique",
    submit: "Envoyer",
    submitting: "Envoi en cours…",
    success: "Problème signalé. Merci !",
    required: "Le titre et la description sont requis.",

    // Past issues section
    myIssues: "Vos signalements",
    myIssuesCount: "Vos signalements ({count})",
    statusOpen: "Ouvert",
    statusTriaged: "Trié",
    statusInProgress: "En cours",
    statusResolved: "Résolu",
    statusClosed: "Fermé",
  }
});

Partial overrides work — only the keys you provide are replaced. You can call configure again at any time to update labels dynamically (e.g. after a language switch).

How it works

The widget runs in a closed shadow DOM — no CSS conflicts with your site. Form submissions include the page URL automatically. Draft text is saved to localStorage so users don't lose their work if they navigate away. Each issue captures a title, description, and severity (low / medium / high / critical).

Feature tracks organize work into scoped features with a full lifecycle. Each track moves through four stages: proposed (drafted with a brief), approved (stakeholders agree on scope), active (linked to a branch — builds and feedback scoped automatically), and merged or parked (completed or shelved).

When a track is active and linked to a branch, any build registered on that branch is automatically associated with the track. Feedback is scoped to the feature, not scattered across unrelated builds.

Feature brief

Each track includes a brief that gives AI context about what's being built:

• What — what the feature does
• Who — who it's for
• Success criteria — how you'll know it works
• Dependencies — what needs to be in place first

MCP tools

Five MCP tools manage the feature track lifecycle: fetch_feature_tracks, draft_feature_track, create_feature_track, activate_feature_track, complete_feature_track.

Project context is persistent knowledge that shapes how AI builds your product. It has two parts: the project brief and context digests.

Project brief

The project brief defines your product's identity across six sections:

• Description — what the product is
• Competitors — who you're positioned against
• Visual direction — design language, color palette, typography
• Tone — voice and writing style
• Technical — stack, constraints, conventions
• Scope — current boundaries and focus areas

The brief is fetched by the AI assistant at the start of work and used to inform every decision. Update it via the update_project_brief tool or through the web dashboard.

Context digests

When a feature track is completed, AI extracts key decisions and patterns from the track's feedback history. These become digest entries — pending items that stakeholders review and approve.

Approved entries become part of the project's persistent knowledge, building an evolving understanding of the product over time. Use fetch_context_digest and approve_context_entry to manage digest entries via MCP.

Skills are reusable instruction sets that encode domain knowledge — brand guidelines, SEO rules, design standards, accessibility requirements. Stakeholders create them through the web dashboard; developers install them into their AI coding tools as slash commands.

Creating skills

Stakeholders create skills from the organization dashboard. Three starting points:

• From scratch — write custom content and configure frontmatter
• From a template — 7 built-in templates (Brand Voice, Visual Design Standards, SEO Guidelines, Accessibility Checklist, Code Review Standards, Content Strategy, Performance Budget)
• Import from GitHub — import existing SKILL.md files from any repository

Installing skills

Developers use the MCP tools to discover and install skills:

1. fetch_skills — lists available skills with install paths
2. install_skill — returns the full SKILL.md content for a specific skill
3. The AI assistant writes the content to .agents/skills/{slug}/SKILL.md
4. The skill becomes available as a /slash-command in Claude Code

SKILL.md format

Skills follow the Claude Code SKILL.md format: YAML frontmatter + markdown body.

---
name: Brand Voice
description: Tone and terminology guidelines
allowed-tools:
  - Edit
  - Write
---

# Brand Voice Guidelines

Always use active voice. Refer to the product as "Mira", never "the platform"...

Subagents are specialized AI agent personas with custom system prompts, tool access, model selection, and execution configuration. Stakeholders define them through the web dashboard; developers install them and Claude auto-delegates based on task description.

Creating subagents

Stakeholders create subagents from the organization dashboard. Three starting points:

• From scratch — write a custom system prompt and configure execution settings
• From a template — 7 built-in templates (Code Reviewer, QA Lead, Security Auditor, Performance Auditor, Design System Guardian, Documentation Writer, Architecture Reviewer)
• Import from GitHub — import existing AGENT.md files from community repositories

Installing subagents

Developers use the MCP tools to discover and install subagents:

1. fetch_subagents — lists available subagents with install paths
2. install_subagent — returns the full AGENT.md content for a specific subagent
3. The AI assistant writes the content to .claude/agents/{slug}.md
4. Claude auto-delegates matching tasks to the installed agent

AGENT.md format

Subagents follow the Claude Code AGENT.md format: YAML frontmatter + markdown body (system prompt).

---
name: Security Auditor
description: Reviews code for security vulnerabilities
model: sonnet
tools:
  - Read
  - Grep
  - Glob
permissionMode: plan
maxTurns: 10
---

# Security Auditor

You are a security-focused code reviewer. Analyze code for OWASP Top 10 vulnerabilities...

Configuration options

The AGENT.md frontmatter supports these configuration fields: