# Tapir

**Drive your running Flutter app. Read by humans, driven by agents.**

Snapshot the Semantics tree, then tap, type, scroll and screenshot by ref. One contract backs the CLI and the MCP tools. Debug builds only.

## Snapshot. Act. Verify.

End-to-end testing on Flutter is a stitched-together ritual. Tapir gives the running app one extension family and one CLI for humans and agents alike.

### Semantics snapshot

A YAML tree of the running app with stable `[ref=eN]` tokens. Every action targets a ref.

[Learn more about Semantics snapshot](https://anilcancakir.com/tapir/docs/getting-started/quickstart.md)

### Actionability gate

Each gesture waits until the widget is enabled, on screen, stable and hit-testable.

[Learn more about Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md)

### Frame attribution

Bracket an interaction and see which widget types built, how often and for how long.

[Learn more about Frame attribution](https://anilcancakir.com/tapir/docs/reference/perf-trace.md)

### Built for agents

The same contracts back the CLI and the MCP tools, so a human and an agent drive alike.

[Learn more about Built for agents](https://anilcancakir.com/tapir/docs/mcp/overview.md)

### Magic aware

Snapshot enrichers let Magic add its own state beside the Semantics tree.

[Learn more about Magic aware](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md)

### Wind aware

Wind's class cache hit, miss and bypass counters show up next to the frame report.

[Learn more about Wind aware](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md)

## Your agent speaks Tapir.

The Tapir skill teaches your coding assistant to snapshot first, act by ref and verify after, before the first tap. One command wires it up.

```bash
npx skills add anilcancakir/ai --skill tapir
```

[other editors](https://github.com/anilcancakir/ai)

## And drives the app itself.

Skills teach the loop. The stdio MCP server gives your agent the whole CLI surface as tools, plus an evaluate call.

```bash
claude mcp add tapir -- dart run tapir mcp:serve
```

## Start building in seconds

```bash
flutter pub add tapir
```

Or add to `pubspec.yaml`:

```yaml
dependencies:
  tapir: ^0.0.24
```

Or give your AI agent this prompt:

```text
Read https://anilcancakir.com/tapir/docs/llms.txt and install the Tapir package in this project.
```

## Docs

### Getting Started

- [Getting Started](https://anilcancakir.com/tapir/docs/getting-started/index.md)
- [Installation](https://anilcancakir.com/tapir/docs/getting-started/installation.md)
- [Quickstart](https://anilcancakir.com/tapir/docs/getting-started/quickstart.md)
- [Driving real apps: gotchas for agents](https://anilcancakir.com/tapir/docs/getting-started/driving-real-apps-gotchas.md)

### Commands

- [Commands](https://anilcancakir.com/tapir/docs/commands/index.md)
- [tapir:install](https://anilcancakir.com/tapir/docs/commands/tapir-install.md)
- [tapir:run](https://anilcancakir.com/tapir/docs/commands/tapir-run.md)
- [tapir:doctor](https://anilcancakir.com/tapir/docs/commands/tapir-doctor.md)
- [tapir:snap](https://anilcancakir.com/tapir/docs/commands/tapir-snap.md)
- [tapir:find](https://anilcancakir.com/tapir/docs/commands/tapir-find.md)
- [tapir:observe](https://anilcancakir.com/tapir/docs/commands/tapir-observe.md)
- [tapir:tap](https://anilcancakir.com/tapir/docs/commands/tapir-tap.md)
- [tapir:fill](https://anilcancakir.com/tapir/docs/commands/tapir-fill.md)
- [tapir:screenshot](https://anilcancakir.com/tapir/docs/commands/tapir-screenshot.md)
- [tapir:reset_overlays](https://anilcancakir.com/tapir/docs/commands/tapir-reset-overlays.md)
- [tapir:perf_begin](https://anilcancakir.com/tapir/docs/commands/tapir-perf-begin.md)
- [tapir:perf_end](https://anilcancakir.com/tapir/docs/commands/tapir-perf-end.md)
- [tapir:perf_run](https://anilcancakir.com/tapir/docs/commands/tapir-perf-run.md)
- [tapir:perf_trace](https://anilcancakir.com/tapir/docs/commands/tapir-perf-trace.md)
- [tapir:perf_insight](https://anilcancakir.com/tapir/docs/commands/tapir-perf-insight.md)
- [tapir:perf_compare](https://anilcancakir.com/tapir/docs/commands/tapir-perf-compare.md)
- [tapir:perf_campaign](https://anilcancakir.com/tapir/docs/commands/tapir-perf-campaign.md)

### MCP

- [Tapir MCP Overview](https://anilcancakir.com/tapir/docs/mcp/overview.md)
- [Tapir MCP Setup](https://anilcancakir.com/tapir/docs/mcp/setup.md)
- [Tapir MCP Tool Reference](https://anilcancakir.com/tapir/docs/mcp/tool-reference.md)

### Plugins

- [Authoring a snapshot enricher](https://anilcancakir.com/tapir/docs/plugins/enricher-authoring.md)
- [Magic integration](https://anilcancakir.com/tapir/docs/plugins/magic-integration.md)
- [Wind integration](https://anilcancakir.com/tapir/docs/plugins/wind-integration.md)

### Reference

- [Actionability gate](https://anilcancakir.com/tapir/docs/reference/actionability-gate.md)
- [Frame production](https://anilcancakir.com/tapir/docs/reference/frame-production.md)
- [Interactions and the perf trace](https://anilcancakir.com/tapir/docs/reference/perf-trace.md)
- [The semantics hold](https://anilcancakir.com/tapir/docs/reference/semantics-hold.md)