Build your first agent.

A Houston agent is a JSON file and a prompt. You can build one in 10 minutes.

What you need

Two files. That's it.

• houston.json — defines what your agent looks like, which tabs it has, and what category it belongs to.
• CLAUDE.md — the instructions your agent follows. This is the brain.

Optional: an icon.png (256x256) for the store card. Without one, Houston uses the Lucide icon from your manifest.

The manifest

Here's a minimal houston.json for a bookkeeping agent:

{
  "id": "bookkeeper",
  "name": "Bookkeeper",
  "description": "Categorize expenses, reconcile accounts, prepare reports.",
  "icon": "Calculator",
  "category": "business",
  "author": "Your Name",
  "tags": ["accounting", "bookkeeping", "finance"],
  "tabs": [
    { "id": "chat", "label": "Chat", "builtIn": "board", "badge": "activity" },
    { "id": "files", "label": "Files", "builtIn": "files" },
    { "id": "job-description", "label": "Instructions", "builtIn": "job-description" }
  ],
  "defaultTab": "chat"
}

The id must be unique. Use kebab-case. This is how Houston identifies your agent across installs and updates.

Fields reference

The prompt

Create a CLAUDE.md file next to your manifest. This is where your domain expertise lives.

# Bookkeeper

You are a bookkeeping agent. You help users manage their
finances by categorizing expenses, reconciling accounts,
and preparing reports.

## What you do
- Categorize transactions from bank statements
- Flag unusual expenses for review
- Generate monthly summaries
- Answer questions about spending patterns

## Rules
- Always ask which time period the user wants before starting
- Round currency to two decimal places
- When in doubt about a category, ask the user
- Never fabricate transaction data

The quality of your agent is the quality of this prompt. This is where founders spend their time. The domain knowledge, the edge case handling, the workflow design. This is your product.

Built-in tabs

Houston ships with tabs you can use out of the box. Add them to your tabs array with a builtIn key.

You can also disable a tab or add a chip label. Useful for features you're still building:

{ "id": "routines", "label": "Routines", "builtIn": "routines", "disabled": true, "chip": "Soon" }

Import and test

Two ways to get your agent into Houston:

From GitHub (recommended)

1. Push your houston.json, CLAUDE.md, and optional icon.png to a GitHub repo.
2. In Houston, click New Agent.
3. Switch to the GitHub tab.
4. Paste your repo URL or owner/repo.
5. Houston downloads the files and installs the agent.

Manually

1. Create a folder at ~/.houston/agents/your-agent-id/
2. Put your houston.json and CLAUDE.md there.
3. Restart Houston. Your agent appears in the New Agent picker.

Once installed, create a new agent from your definition. Houston seeds the working directory with your CLAUDE.md and any files from agentSeeds. Start chatting. Iterate on the prompt until it feels right.

Publish to GitHub

Your GitHub repo is your distribution channel. The minimum repo structure:

your-agent/
├── houston.json
├── CLAUDE.md
└── icon.png        (optional, 256x256)

Anyone can import your agent by pasting the repo URL into Houston. When you push updates, Houston detects them and updates installed agents automatically.

Going further

Seeding files

Use agentSeeds to pre-populate every new agent instance with default files:

"agentSeeds": {
  ".houston/prompts/execution.md": "You are a coding agent...",
  ".houston/config.json": "{\"mode\": \"default\"}"
}

Multi-agent setups

One agent definition can have multiple prompt profiles. Each profile gets its own prompt file and create button:

"agents": [
  {
    "id": "execution",
    "name": "Coder",
    "promptFile": "execution.md",
    "createLabel": "New Mission"
  },
  {
    "id": "planning",
    "name": "Planner",
    "promptFile": "planning.md",
    "createLabel": "New Planning Session"
  }
]

Custom React components

Built-in tabs not enough? You can build custom React components and bundle them with your agent. That's the next chapter.