Getting started

Build an app in Chataway

Describe an app and let your agent build it — app projects, the App strip, the builder loop and its tools, Use in…, sharing on GitHub and publishing to the store, all without leaving Chataway.

You don't need a terminal to make a Chataway app. Tell Chataway what the app should do, and your agent builds it in a project of its own: it writes the code, the app reloads on every save, the agent calls its tools to test them and looks at the panel it drew. You watch, steer, and use the app as soon as it works.

This page is about that flow. If you prefer your own editor and the CLI, the quickstart gets you to the same place.

#Create an app

Open Apps → + New app (on the phone: the Apps sheet → New app), or the new-project drawer's App tab. The sheet asks for:

Field
What should it do?	A sentence or a paragraph — "Pull my Shopify orders and turn them into a weekly sales poster". It becomes the agent's first message.
Name and Icon	An emoji or a letter for now; the agent can draw a proper mark later.
Kind	Runs on my Mac — a local app: `server.ts` running inside Chataway, with full access. Cloud app — store-shaped: a remote MCP server plus a panel, like every app in the store.
Agent	Which agent builds it — Claude Code, Codex, Cursor… It becomes the project's default.

Create app then:

makes a folder in ~/Chataway/Apps/<name>/ (change it in Settings → Developer), scaffolds the app there and makes the first git commit,
registers the folder as an app project and links the app into Chataway in developer mode (badge DEV),
switches the app on in its own project only,
switches on the App builder for that project (a skill with the full app API, plus the builder tools below),
opens a chat with your description as the first message. The agent starts building right away.

The app's id is local.<name> until you publish it. For a cloud app, the scaffold is the same one create-chataway-app makes, and package.json → chataway.devMcpUrl points Chataway at the MCP server running on your Mac while you develop. The agent installs dependencies and starts that server itself.

#The App strip

An app project is a normal project — chat, files, terminal, git, browser, phone — with one extra line under its header:

📈 Sales Poster  APP  DEV  ● Running · v0.3 · reloaded 12s ago     Inspector  Use in…  Share ▾  ⋮

Part	What it does
Status	Running, Reloading, Failed (tap for the error, with Ask agent to fix) or Off. Waiting for Browser when an app it requires isn't on yet — tap to switch it on.
`v0.3`	The `version` in `plugin.json`; `v0.3+` when there are uncommitted changes.
`reloaded 12s ago`	Every save validates the manifest and reloads the app's code and panel. A broken `plugin.json` keeps the last good version running and says Reload failed.
Inspector	The live feed: tool calls with arguments and results, cards, jobs, logs, errors, and MCP traffic for cloud apps.
Use in…	Switch the app on in other projects. They get it with a `DEV` badge, live-reloading as you work. Nothing else gets it until you pick it here.
Share	Push to GitHub, copy an install link, publish to the store — below.
⋮	Reload now · Turn off everywhere.

On the phone the strip shrinks to the status and a ⋮ menu with the same actions.

The app's panel docks next to the chat, and cards its tools raise show up inline in the builder chat — exactly as your users will see them.

#The builder loop

The agent in an app project gets six extra tools. They work with every provider (Claude, Codex, Cursor, Grok), and they only exist in app projects:

Tool	What the agent uses it for
`app_status`	Running / reloading / failed / off, the last error with `file:line`, manifest issues, the app's tools and panels.
`app_reload`	Force a reload (saving already reloads). Also re-links an app whose `plugin.json` was broken when Chataway started.
`app_call_tool(name, args)`	Call one of the app's own tools the way a user's agent would — through Chataway, with its cards shown in the chat.
`app_inspect(since?, kind?)`	Recent Inspector entries: calls, cards, MCP traffic, logs, load errors.
`app_validate(level)`	The validator at `dev` level, or `store` level (the bundle the store would receive), with a fix hint per issue.
`app_screenshot_panel(view?, theme?, width?, height?)`	A screenshot of the app's panel, rendered headlessly (dark theme by default), plus any console errors.

Two things close the loop without you:

Errors come to the agent. If the app failed to reload since the agent's last turn, the error (with file:line) is added to its next turn. Nobody pastes logs.
Event rows in the chat. Small muted rows — App reloaded · 3 tools, App failed to load — server.ts:42 TypeError…, Validation: 2 warnings for the store — so you can follow along.

A typical turn looks like this:

You    Add a tool that lists last week's orders, newest first.
Agent  (edits server.ts)  → App reloaded · 2 tools
       app_call_tool("list_orders", { "days": 7 })   → 14 orders
       app_screenshot_panel()                         → checks the new table
       Done — list_orders works; the panel shows the table under "This week".

The App builder skill the agent loads holds the manifest reference, the local app API, the panel bridge and theme tokens, three complete example apps, and the rules (anything with consequences behind a card, keys only as user-entered secrets, test like a user). Its reference pages are generated from these docs, so the agent reads the same thing you do.

#Use it everywhere

Use in… lists your other projects. Tick the ones that should have the app; untick to take it away. Each project gets the app as DEV and follows every reload — no install, no version bump. If the app requires other apps that are installed, they're switched on with it.

To stop it everywhere at once, use ⋮ → Turn off everywhere. Archiving the app project freezes the app at its last good version (it stops reloading); deleting the project unlinks the app and switches it off in every project — the confirmation lists them.

Share ▾ has three ways out:

Push to GitHub — commits what's pending, creates the repository with the GitHub CLI (gh) if there isn't one, pushes and tags v<version>. New repositories are private by default; Push to GitHub (public)… asks first. Without gh, Chataway shows the commands to run instead.
Copy install link — once the commit is pushed: https://chataway.co/install?repo=owner/repo&ref=<sha>, pinned to that exact commit. Anyone with access to the repo can install it from there. See Sharing via GitHub.
Publish to store… — cloud apps only. One click with the Chataway account your Mac is signed in to: pick or create a publisher, run the store checks (Ask agent to fix sends failures to the builder chat), see what people will be asked to allow, bump the version if needed, build, pack and upload. The strip then shows In review, Live v1.2 or Changes requested. Step by step: Publish from Chataway.

An app that runs on your Mac can't go to the store — the store only takes cloud apps. Share it on GitHub instead.

#Check the service first

Many services already run a hosted MCP server with sign-in — Canva, Notion, Linear, Sentry, Stripe. If all you need is their tools in your chats, don't build an app: add a connector. Build an app for what a connector can't do — a panel, cards, files from the Mac, combining services — and call the service through its connector's tools rather than reimplementing its API.