tiles-ai 0.1.4

Tiles AI — a phone-home-screen control plane for AI agents. Register, activate, observe, and permission tiles.

🟩 Tiles AI

A home screen for your AI agents. Lay your agents out as tiles on a board, tap one to run it, and stay in control of anything it does.

What is it?

Think of your phone's home screen — but every app is an AI agent.

• A board is a grid of tiles.
• Each tile is one agent that does a single job — "summarize my inbox", "tidy this folder", "draft a reply".
• Tap a tile and it turns green — running.

Tiles AI handles the parts around an agent — running it, watching it, asking your permission before it acts, and connecting it to your apps. You bring the agent's logic (plain Python, or wrap LangChain / CrewAI / the OpenAI SDK).

It's built for developers learning to build agents: start from a ready-made board and add your own tiles right from the screen.

Quick start

You'll need Python 3.11+. The board ships pre-built in the package:

pipx install tiles-ai      # or: pip install tiles-ai
tiles up --echo            # seeds a starter board here on first run

Open http://127.0.0.1:8000 — you'll see a starter board running on a free offline brain (no API key needed). The first run drops the starter tiles and connectors into the current folder (so you can edit them); run tiles init yourself to seed a board without starting the server. When you're ready for a real model, run tiles up and connect a brain from the screen.

From source (to hack on Tiles itself)

You'll also need Node 18+ to build the board once.

git clone https://github.com/Manav020201/tiles-ai && cd tiles-ai
pip install -e ".[dev]"
npm --prefix frontend install && npm --prefix frontend run build
tiles up --echo

What you can do

Right away — no API keys:

• Instant tiles — Ask, Summarize, Translate, Extract, Brainstorm.
• Your files — summarize a folder, find files, or tidy a folder (it proposes the moves; you approve them).

Add your apps — GitHub, Slack, web search, Gmail, and anything with an MCP server (local or remote). Paste any API key the app needs right in the board (stored locally in secrets.local.yaml, gitignored), or connect via OAuth.

All from the board — no editor required:

➕ Create a tile	fill a form; Tiles writes the files for you
🔌 Connect an app	paste its command; Tiles reads its tools automatically
🧠 Choose your model	cloud (Anthropic / OpenAI) or local (Ollama)
✅ Approve before it acts	anything that writes or sends waits for your OK
⏱ Schedule & chain	run a tile on a timer, or feed one tile's output into another
👀 Observe	live activity per tile, and clear errors as you go

How it works

Three ideas:

Concept	What it is
Tile	an agent — a model + instructions + a permission level. The thing you tap.
Connector	a reusable connection to one app (e.g. GitHub). Many tiles can share it.
Brain	the model that powers tiles. Set one once; a tile can pin its own.

Permissions are built in. Every tile has a level: read-only (never acts), draft (proposes actions you approve), or autonomous. Green means running, not unsupervised.

Architecture (for the curious)

React board ──HTTP/SSE──▶ FastAPI ──▶ runtime ──▶ permission gate ──▶ connector ──▶ app
                                         └──▶ model adapter ──▶ brain (cloud / local)

Connectors talk to apps over MCP (stdio or HTTP). The full design is in SPEC.md.

Make your own tile

The easy way: click ➕ New tile on the board, fill the form, and open the generated handler.py to customize.

In code, a tile is a small folder with a manifest and one method:

from tiles_ai.contracts import ActionPlan, Tile

class MyTile(Tile):
    async def run(self, input, context) -> ActionPlan:
        answer = await context.model.complete(str(input))
        return ActionPlan(result=answer)

Full guide, including how to connect a new app: docs/AUTHORING.md.

Troubleshooting

The board is empty, or http://127.0.0.1:8000 shows 404 Not Found

You're almost certainly running a source checkout or an editable install (pip install -e) instead of the published package. The board UI and the starter tiles are built into the wheel; a source tree only has them after a release build, so it serves nothing at / and shows no tiles.

The fix is to install the real package into an isolated environment so nothing shadows it (see the next item). If you do want a checkout to serve the board:

npm --prefix frontend run build && cp -r frontend/dist src/tiles_ai/web
python scripts/bundle_starter.py        # adds the seedable starter board

pip install tiles-ai says "Requirement already satisfied" / won't update

A pre-existing install — often an editable one from a clone — is registered, so import tiles_ai resolves to that, not the download. Install into a fresh virtual environment instead (non-destructive; leaves any dev checkout intact):

python3 -m venv ~/tiles-test-env
~/tiles-test-env/bin/pip install --upgrade pip tiles-ai
mkdir -p ~/tiles-demo && cd ~/tiles-demo
~/tiles-test-env/bin/tiles up --echo

Or, to use your base environment, remove the old install first: pip uninstall tiles-ai then pip install tiles-ai (re-run pip install -e ".[dev]" in your clone afterwards if you were developing).

pipx install tiles-ai fails with an ensurepip / venv error

This is a pipx + Python toolchain problem (commonly a freshly-installed Python whose ensurepip is broken), not a Tiles problem — pipx never reaches the package. Either point pipx at a known-good Python:

PIPX_DEFAULT_PYTHON=$(which python3) pipx install tiles-ai

or skip pipx and use the plain venv + pip recipe in the item above.

I added a real API key and Test passed, but tiles still just echo

You're running tiles up --echo. The --echo flag forces an offline demo brain — every tile (and the Test button) returns a canned echo, and real keys are ignored by design. Restart without --echo:

tiles up

then add your key in Settings (🧠). It's saved to brain.local.yaml and used for every tile. (On recent versions, clicking Test while in --echo mode says so explicitly instead of reporting a false "working".)

A tile fails with "model call failed" / HTTP 529 / 502

529 Overloaded (and 429, 503) are transient errors from the model provider, not a Tiles bug — your key is working, the provider is just busy. Tiles retries these automatically with backoff; if it still fails, wait a few seconds and run the tile again. A persistent 401/403 instead means a bad or unauthorized API key — re-check it in Settings (🧠).

I have an old version installed

Check with tiles --version and pip show tiles-ai. Upgrade with pip install --upgrade tiles-ai (inside the right environment — see above).

Docs

• SPEC.md — the design and the tile contract
• docs/AUTHORING.md — build a tile or a connector
• CONTRIBUTING.md — dev setup and how to help
• CHANGELOG.md — what's new

Status

Active development; well-tested with CI on Python 3.11 and 3.12.

Already here: tiles chain (sequential flows), run on an interval schedule, and connect via OAuth (authorization-code) or API keys.

Refinements still to come: branching / fan-out flows (only linear chains today) · cron and event triggers (only intervals today) · automatic OAuth token refresh. Out of scope for now: hosting and multi-user.

License

MIT.