Agent builder

The Agent builder is how you grow your team. Describe an agent in plain English, and Claude Code writes it, tests it, and hands it to you, ready to join your team. No coding needed.

Agents it builds are ordinary files on your Mac. Once they’re built, they run on your own model, with no Claude Code and no internet needed. See Run it all on your Mac.

What you can build

Anything a small Python tool can do. For example:

A recipes agent called Basil, warm and a bit bossy. It should find recipes from what I have in the fridge, using TheMealDB.

An agent that reads my Home Assistant at http://homeassistant.local:8123 and tells me which lights are on and what the temperature is in each room.

An agent for our internal status page at https://status.example.internal. It should say which services are down and since when.

A plant-care agent that reads the moisture sensors my Raspberry Pi publishes at http://pi.local/sensors.json.

An agent that searches the CSV exports in my workspace folder and answers questions about last quarter’s sales, with a chart.

Agents that talk to things on your own network (a NAS, Home Assistant, a local database, an internal API) are a great fit: once built, they’re entirely on-prem.

Before you start

You need Claude Code installed and signed in on your Mac. See Requirements. The Setup check tells you whether it’s found.

Build an agent

1. On the Agents page, press Create agent. Agent builder opens, and appears in the sidebar while it’s open.
2. Describe the agent. Say what it should do, what service or data it uses, and what it should be called. A personality is optional but fun.
3. Answer its questions. Claude Code may ask about details, like which API to use or which units you want.
4. Watch it work. Every file it writes and every command it runs appears as it happens. It:
   • creates the agent’s folder from Agent City’s template,
   • writes the agent’s personality and instructions (SOUL.md),
   • writes its tools (tools.py),
   • adds a few test questions (evals.json) and notes (README.md),
   • runs Agent City’s checks, and
   • calls each tool for real to make sure it works.
5. Add it to your team. When it’s done, a card shows the new agent. Press add to Agent City. It joins straight away, with no restart, and My team can start asking it at once.

If something still isn’t right (a TODO left in, a tool that doesn’t match its description), the card lists what, and you can ask Claude Code to fix it.

Change an agent

Press Edit on one of your agents. The builder opens with “Change @agent:” started for you. Say what to change:

Change @recipes: always give quantities in grams, and add a tool that builds a shopping list.

When it’s done, press reload on the card it posts.

Agents installed from a source can’t be edited this way, because an update would replace your changes.

Tips for good agents

• One job per agent. “Weather” and “calendar” are two agents, not one. My team combines them for you.
• Name the data source. “Using Open-Meteo” or “from http://pi.local/sensors.json” beats “get the weather”.
• Prefer services with no API key. When one is needed, the agent lists it, and its card says Needs until you add it on Connections.
• Say what it must never do. “Read only, never change anything” is a good line for agents that touch your systems.
• Ask for approvals. For anything that sends, posts or changes something: “ask me before each post”. The agent will show an Approve / Skip card first. See Approvals.
• Ask for a table or chart when its results are data. The builder can add a view that draws them under the reply.

Building agents for automations

When you draft an automation and no agent can do one of its steps, the draft names the agent it needs. Press Build (or Build all) and the builder makes each one. They join your team as soon as they load, and the automation can use them.

What it’s allowed to do

The builder works inside a fenced-off space:

• It can only read and write files in your agents folder (~/Library/Application Support/Agent City/agents/).
• It can only run Agent City’s agent template, its tool tester and its checks.
• Everything else is refused rather than asked about, so it never stalls waiting for your approval.

Each message continues the same Claude Code session until you close the builder with the ×. Stop works here too, but whatever it already changed stays changed.

The builder runs Claude Code on your Mac, so it’s only available from your Mac, not from a paired phone.

Under the hood

The builder writes exactly the files described in Agent files. You can open them, read them, change them by hand, or publish them for others to install.