Agentic coding with Dala

AI coding assistants work best when they can close the loop themselves: make a change, verify it worked, decide what to do next. This guide explains how to give an agent the full context it needs to work effectively on a Dala app — and why the default approach most agents reach for will give you worse results.

The context problem

An LLM working on a dalaile app normally has two options for inspecting the running app:

1. Screenshots — xcrun simctl io booted screenshot or adb exec-out screencap
2. Accessibility trees — xcrun simctl ui or adb shell uiautomator dump

Both are what LLMs are trained on. Both are slow, noisy, and lossy. A screenshot tells the agent roughly what's on screen; an accessibility dump tells it roughly what widgets exist. Neither tells it what state the BEAM is in, what data is driving the render, or what the navigation stack looks like.

Dala apps are different. The UI is driven by a GenServer running on an Erlang node — and that node is reachable from your dev machine over Erlang distribution. You can query exact state, not infer it from pixels.

The agent should connect to the running Erlang node and ask it directly.

Priming the agent

Before the MCP tools and tunnels, give the agent the mental model of the project. Each Dala repo has an AGENTS.md at its root — a five-minute orientation covering what's where, how to drive a running app, and the pre-empt-failure rules that come from this team's hard-earned lessons. The file is the standard cross-tool entry point (Cursor, Codex, Aider all read it; Claude Code reads it via the CLAUDE.md reference).

Point your agent at the relevant AGENTS.md for the repo it's working in:

• dala/AGENTS.md — runtime library. The "what is Dala", three-repo topology, and the full "driving apps from your session" reference (Dala.Test, MCP fallbacks, round-trip workflow).
• dala_dev/AGENTS.md — build/deploy/devices toolkit. TDD policy and the public-but-undocumented testing seams.
• dala_new/AGENTS.md — project generator. Template gotchas and the LiveView phoenix-owned-files blocklist.

For multi-repo work, prime with all three. The root dala/AGENTS.md is the "system view" — the other two link back to it for cross-cutting context.

The files are deliberately short (≤ 200 lines) so agents read them in full rather than skimming — that's the difference between a session where the agent already knows your conventions and one where it stumbles into them. These docs go stale fast if the project moves and they don't. The top-of-file note in each AGENTS.md instructs the agent to update them in the same commit as any change that contradicts the guidance — keeping it up to date is a contract, not a suggestion.

Setting up the MCP tools

The Layer 2 visual tools require two MCP servers to be installed and registered with your AI agent.

ios-simulator-mcp

Interacts with the iOS Simulator from outside the app: screenshots, taps, text input, accessibility tree queries.

npm install -g ios-simulator-mcp

GitHub: https://github.com/joshuayoes/ios-simulator-mcp

Add to your Claude Code MCP config (~/.claude.json, under mcpServers):

"ios-simulator": {
  "type": "stdio",
  "command": "ios-simulator-mcp",
  "args": [],
  "env": {}
}

adb-mcp

Provides ADB-backed tools for Android: screenshots, UI dumps, shell access, logcat.

npm install -g adb-mcp

GitHub: https://github.com/srmorete/adb-mcp

Note: The npm package is marked deprecated but remains functional. It is the current recommended option until a maintained alternative stabilises.

Add to ~/.claude.json:

"adb": {
  "type": "stdio",
  "command": "npx",
  "args": ["adb-mcp"],
  "env": {}
}

Verifying the setup

After adding both servers, restart Claude Code and check that the tools are available. In a conversation, the mcp__ios-simulator__screenshot and mcp__adb__dump_image tools should appear in the tool list. You can also ask the agent: "List the MCP tools available to you" — it should enumerate both server namespaces.

Prerequisites

Before an agent can inspect the running app, tunnels must be established:

mix dala.connect --no-iex

This sets up the adb/simctl tunnels and prints node names, then exits — leaving the distribution network open. Keep this running in a terminal while you're working with an agent. Re-run it after a device restart or if mix dala.push loses contact.

Node names:

• iOS simulator: dala_demo_ios@127.0.0.1
• Android emulator: dala_demo_android@127.0.0.1

The three-layer inspection stack

Use these in order. Only go deeper if the layer above doesn't answer your question.

Layer 1 — Erlang distribution (always try this first)

Dala.Test gives the agent exact knowledge of what's happening inside the running app. No image parsing, no heuristics, no guessing.

node = :"dala_demo_ios@127.0.0.1"

Dala.Test.screen(node)
#=> dalaDemo.CounterScreen

Dala.Test.assigns(node)
#=> %{count: 3, safe_area: %{top: 62.0, bottom: 34.0, left: 0.0, right: 0.0}}

Dala.Test.find(node, "Increment")
#=> [{[0, 1], %{"type" => "button", "on_tap_tag" => "increment"}}]

Dala.Test.tap(node, :increment)
#=> :ok

Dala.Test.inspect(node)
#=> %{screen: dalaDemo.CounterScreen, assigns: %{count: 4}, nav_history: [], tree: ...}

This is available via iex -S mix (after mix dala.connect has set up the tunnels) or directly from an agent that can run shell commands, using:

iex -S mix --eval 'IO.inspect Dala.Test.assigns(:"dala_demo_ios@127.0.0.1")'

Layer 2 — MCP platform tools (for rendering and layout)

When the question is visual — "does this text overflow?", "is the button in the right position?", "did the animation play?" — use the platform MCP servers.

These are available as tools in Claude Code:

iOS Simulator (mcp__ios-simulator__*):

Android (mcp__adb__*):

Layer 3 — Raw platform tools (almost never needed)

xcrun simctl, raw adb shell, Xcode Instruments. These are what agents reach for by default — resist it. They give you less information than Layer 1 and are slower than Layer 2. The only reason to drop here is if the MCP servers aren't configured or a specific low-level query has no higher-level equivalent.

The standard agent loop

1. Edit Elixir source
2. mix dala.push                      ← push changed BEAMs (no restart needed)
3. Dala.Test.screen(node)             ← confirm which screen is active
4. Dala.Test.assigns(node)            ← confirm data state is what you expect
5. Dala.Test.tap(node, :some_tag)     ← drive an interaction
6. Dala.Test.assigns(node)            ← confirm state updated
7. mcp__ios-simulator__screenshot    ← visual check only if layout matters
8. repeat from 1

For changes that touch native code (NIFs, Swift, Kotlin):

1. Edit source
2. mix dala.deploy --native           ← full rebuild + install + restart
3. mix dala.connect --no-iex          ← re-establish tunnels after restart
4. continue with loop above

Steering the agent

LLMs have extensive training data on xcrun simctl, adb, UIKit, and Jetpack Compose testing patterns. They will reach for that toolbox instinctively, especially when asked to "verify" or "check" something visual.

You need to redirect this explicitly. Put something like the following in your project's CLAUDE.md:

## Inspecting the running app

This is a Dala app. The running app is an Erlang/OTP node. Do NOT use xcrun simctl
screenshots or adb screencap as your primary inspection method.

Instead:
1. Run `mix dala.connect --no-iex` to establish distribution tunnels (if not already running)
2. Use `Dala.Test` from IEx to query exact state:
   - `Dala.Test.screen(node)` — what screen is active?
   - `Dala.Test.assigns(node)` — what is the live data?
   - `Dala.Test.tap(node, :tag)` — drive a tap by tag atom
   - `Dala.Test.find(node, "text")` — locate a widget by visible text
3. Only reach for `mcp__ios-simulator__screenshot` or `mcp__adb__dump_image` when
   you need to verify rendering or layout — not to check app state.

Node names:
- iOS simulator:    dala_demo_ios@127.0.0.1
- Android emulator: dala_demo_android@127.0.0.1

Replace dala_demo with your actual app name.

Why Dala.Test beats screenshots for state inspection

Screenshots are for humans and for verifying that the visual output looks right. They are not a substitute for inspecting what the program is actually doing.

Worked example: debugging a counter that doesn't update

A common first instinct for an agent:

# Wrong approach
xcrun simctl io booted screenshot /tmp/before.png
# ... make change ...
xcrun simctl io booted screenshot /tmp/after.png
# "The screenshots look the same, the counter didn't change"

The Dala approach:

# Check what state the app is actually in
iex -S mix

node = :"dala_demo_ios@127.0.0.1"

# Before
Dala.Test.assigns(node)
#=> %{count: 0}

Dala.Test.tap(node, :increment)

# After — immediate, exact
Dala.Test.assigns(node)
#=> %{count: 1}

# If it's still 0, the handle_event clause isn't matching — check the tag name
Dala.Test.find(node, "Increment")
#=> [{[0, 1], %{"type" => "button", "on_tap_tag" => "inc"}}]
# Ah — the tag is :inc, not :increment

The distribution layer tells you exactly what happened and why. No image comparison, no inference.

Quick reference: on_tap tags

Tags come from on_tap: {self(), :tag_atom} in the render tree. To see all widgets and their tags on the current screen, use the full snapshot:

node = :"dala_demo_ios@127.0.0.1"
Dala.Test.inspect(node)
# %{screen: ..., assigns: ..., tree: %{"type" => "column", "children" => [...]}}

Or just read the screen's render/1 function — every interactive widget has a tag in its props. The tag atom in on_tap: {self(), :my_tag} is what you pass to Dala.Test.tap(node, :my_tag).