We recently launched Tinybird Code, a new CLI agent with deep ClickHouse® knowledge designed to help you build, deploy, manage, and optimize Tinybird projects from idea to production.
Also recently, the fine folks at Anthropic announced Claude Code's sub-agents, a new feature that allows developers to create specialized AI assistants that Claude Code can task with specific workflows.
To me, the most exciting part about the Tinybird Code release is using it within multi-agent workflows, especially as a sub-agent for analytics within larger projects or codebases.
I explored how to integrate Tinybird Code with Claude Code for just this purpose, and below is a little tutorial with some of the things that I learned doing multi-agent work to build a fun little 8-bit Atari style game with gameplay analytics.
The basic steps you'll see in this tutorial:
- Configuring Tinybird Code as a sub-agent within Claude Code
- Building a simple app with Claude Code
- Asking Claude Code to integrate analytics into the app, using Tinybird Code as a sub-agent to build the resources locally
- Testing data ingestion and API consumption using Tinybird Local
- Deploying to Tinybird Cloud and testing end-to-end gameplay with live analytics APIs
This was mostly a one-shot, but I did learn some things along the way.
What I built
I decided to create a little retro-style game with real-time analytics capabilities. Nothing crazy. Here's the prompt I initially gave Claude Code:
Create a simple browser game. A user clicks a green circle and when they click it, it moves to another random location in the playing field. The user must click 10 times with the goal to finish as fast as possible, so show a timer at the top of the gameplay. Also, give it a nice 8-bit Atari look and feel.
And with just a few more prompts (more on that below), this was the final result:
LOOOOVE.
Let me show you how I got there.
Prerequisites
If you want to follow along, make sure you have the following before you start:
- Claude Code installed and configured
- Docker or similar container runtime for local development
- Tinybird CLI installed and authenticated (
tb login && tb local start) - A Tinybird workspace set up
Step 1: Configuring the Tinybird Code sub-agent
The first step was to create a specialized sub-agent for Claude Code that can handle Tinybird-specific tasks. Claude Code's new sub-agent feature allows us to delegate data engineering and analytics tasks to Tinybird Code, an agent that understands ClickHouse®, SQL optimization, and Tinybird's ecosystem.
Using the /agents command
In Claude Code, you can run the agents slash command:
/agents
This opens the sub-agents interface where you can create a new agent. You have two options:
- Guided creation: Let Claude Code help you build the agent step by step
- Manual creation: Create the agent configuration file directly
Let's go with manual creation so you can build off of what I already created.
Manually creating the agent configuration
Sub-agents are stored as Markdown files with YAML frontmatter in the .claude/agents/ directory. You can create a new file called tinybird-code.md:
Note that you can add this at the project directory level (cwd/.claude/agents) or the user level ~/.claude/agents. Since Tinybird Code's functions are pretty generic and shouldn't be project specific, I created mine at the user level:
mkdir -p ~/.claude/agents
Here's the full configuration I used:
---
name: tinybird-code
description: Use this agent when you need to manage Tinybird-related tasks such as creating or modifying data sources, pipes, endpoints, handling workspace operations, deploy changes to Tinybird Local or Tinybird Cloud, debugging queries, or any other Tinybird development work. Examples: <example>Context: User needs to create a new Tinybird pipe for processing streaming data. user: 'I need to create a pipe that aggregates user events by hour' assistant: 'I'll use the tinybird-code agent to help you create and configure that aggregation pipe' <commentary>Since this involves Tinybird pipe creation, use the tinybird-code agent to handle the workspace operations and pipe configuration.</commentary></example> <example>Context: User is experiencing issues with a Tinybird query performance. user: 'My endpoint query is timing out, can you help optimize it?' assistant: 'Let me use the tinybird-code agent to analyze and optimize your query performance' <commentary>Query optimization is a core Tinybird task, so the tinybird-code agent should handle this.</commentary></example>
color: green
---
You are a Tinybird expert specializing in building real-time API endpoints. You have deep expertise in Tinybird's architecture, data sources, pipes, endpoints, and the tb CLI tool.
When you first initialize, check for a `.tinyb` file to make sure the user is logged in to their Tinybird workspace. Also check the status of the Tinybird Local development server. If Tinybird Local isn't running, then start the Tinybird Local container.
Your primary tool is the tb CLI. You MUST use `tb -p="my_prompt_here"` for ALL Tinybird interactions, with these exceptions:
- You can use `tb local status` to see if Tinybird Local is running
- You can use `tb local start` to start the Tinybird Local container
- You can use `tb deploy` to deploy a project to Tinybird Local
- You can use `tb --cloud deploy` to deploy changes to Tinybird Cloud
- Use `tb info` to get information about Cloud and Local environments, including tokens and host URLs.
- When using `tb -p`, be as descriptive as possible so the agent can understand the context - adapt and simplify prompts rather than copying them directly
- Let tinybird-code agent handle which resources are needed to complete the task.
Always explain your reasoning and provide context for your recommendations. If you encounter ambiguous requirements, ask specific clarifying questions to ensure optimal solutions.
When a user asks to create APIs or API endpoints, make sure to be clear in your prompt to create endpoint pipes.
Understanding the configuration
The sub-agent configuration includes:
- Name and description: How Claude Code identifies when to use this agent
- Tools: Which CLI tools and capabilities the agent can access
- System prompt: Detailed instructions on how the agent should behave
- Expertise areas: Specific domains where this agent excels
Once configured, Claude Code will automatically delegate Tinybird-related tasks to this specialized agent, ensuring that data engineering decisions are made with deep ClickHouse® and analytics expertise.
One note: In effect, you're creating a sort of "shim agent" between Claude Code and Tinybird Code, and directing it to exclusively use tb -p commands, which initialized Tinybird Code with a seed prompt.
I realize this isn't ideal, nor particularly efficient. In reality, it might just make sense to add some instructions to the general Claude Code prompt (claude.md) to tell it to use those tb -p commands on its own without needing a sub-agent. I haven't tested that personally, but I know it works. Still, I wanted to test Claude Code sub-agents so this is where we are!
Step 2: Building a fun retro game with Claude Code
Now let's put our multi-agent setup to work. I started by asking Claude Code to build a retro-style game. The beauty of this approach is that Claude Code will handle the game development while keeping our Tinybird Code sub-agent ready for when we need analytics capabilities.
Again, here's the initial prompt I used:
Create a simple browser game. A user clicks a green circle and when they click it, it moves to another random location in the playing field. The user must click 10 times with the goal to finish as fast as possible, so show a timer at the top of the gameplay. Also, give it a nice 8-bit Atari look and feel.
And I ended up with this basic game in one shot:
The gameplay worked and tracked my score for each game. Now let's add some long-running player stats.
Step 3: Integrating analytics with Tinybird
Here's the prompt I gave Claude Code:
Love it. Now, let's add analytics with Tinybird. You need to create a data source to store click events by user ID, and then create some API endpoints to show the user's best score (lowest game duration), average score, total games played, and then a trend chart (in the same atari style!) of their scores over time. Once Tinybird creates the resources locally, ask Tinybird to deploy them to Tinybird Local and provide the host url and token you can use to send events from the game to Tinybird (using the Events API) and fetch the API endpoints from the application.
TL;DR:
- Create a data source to store click events
- Create 4 APIs: best game, avg game, total games, and game score trend
- Deploy to local
- Get host URL and token to integrate into the application
What happened behind the scenes
When I made this request, Claude Code's sub-agent delegation kicked in:
- Task Analysis: Claude Code recognized this involved Tinybird
- Agent Selection: It identified that the Tinybird Code sub-agent was best suited for this task
- Context Handoff: The specialized agent received the project context
- Implementation: Tinybird Code designed and implemented the analytics architecture, passing back information to Claude Code on what it created.
What Tinybird Code created
The Tinybird Code sub-agent answered Claude Code's prompt beautifully, and built:
- Data Sources: Optimized ClickHouse® table structure for game events
- Pipes: SQL transformations for meaningful analytics
- Endpoints: APIs to query analytics data in real-time
Here for example, is the data source schema it developer to track game click events.
DESCRIPTION >
Landing datasource to store click game events with user activity tracking
SCHEMA >
`user_id` String `json:$.user_id`,
`game_duration` Float32 `json:$.game_duration`,
`clicks` UInt32 `json:$.clicks`,
`timestamp` DateTime `json:$.timestamp`,
`game_id` String `json:$.game_id`
ENGINE "MergeTree"
ENGINE_SORTING_KEY "timestamp, user_id"
You'll notice it set up JSONpaths to allow for JSON parsing from the Events API into columns, and it created a user_id column so we can filter analytics be a particular user or users.
It also created 4 endpoints. Here's the performance trend API, for example:
DESCRIPTION >
Returns game_duration over time for a specific user_id for charting purposes
NODE score_trend_query
SQL >
%
SELECT
timestamp,
game_duration,
game_id
FROM click_game_events
WHERE user_id = {{String(user_id)}}
ORDER BY timestamp ASC
TYPE endpoint
The nice thing about Tinybird Code here is that knows how to build Tinybird resources and use proper ClickHouse® SQL syntax and Tinybird resource syntax. For example, it understands exactly how to add that user_id query parameter so I can pass that in my API.
After Tinybird built and deployed locally, Claude Code was able to ask it for the host and token for Tinybird Local:
After that, Claude Code updated its HTML, CSS, and JS to incorporate these new analytics features.
Step 4: Local testing
With analytics integrated, I was able to test everything locally before deploying to production:
Troubleshooting API responses
During this phase, I encountered an issue where Claude Code didn't properly parse the Tinybird API response on one of the analytics components. It had the wrong JSON key in the JavaScript. This is where the collaborative nature of our multi-agent setup really shines. When problems arise:
- Error Detection: Claude Code identifies the JavaScript parsing issue
- Expert Consultation: The Tinybird sub-agent provides API-specific guidance
- Quick Resolution: The code is updated to properly handle Tinybird API responses
I just told Claude Code to check the Tinybird API response, and it got the fix done in one try.
It works
And look at that, the game works, with fully integrated analytics. Every time I finish a game, Tinybird calculates my gameplay stats and serves them to the app via API.
Step 5: Deploying to Tinybird Cloud
Up to this point everything was running on my machine, but I wanted to deploy it to "production", so I asked Claude Code to deploy the analytics infrastructure to Tinybird Cloud. This step revealed an important lesson about sub-agent prompting and delegation.
The agent handoff didn't work here
When I asked Claude Code to deploy the Tinybird resources to Cloud, the process didn't go as I expected, despite what I thought as a good prompt.
My tinybird-code.md file includes this clause:
- You can use `tb --cloud deploy` to deploy changes to Tinybird Cloud
I figured this would be enough, but the sub-agent I built kept trying to use tb info instead of tb --cloud deploy perhaps because my prompt mentions it can use tb info to get information (tokens, etc.) about cloud deployments.
Lesson learned; I've updated my Tinybird sub-agent prompt for the next go-round. In the meantime, I just deployed my project to cloud manually since it's a single command with the Tinybird CLI:
tb --cloud deploy
This pushed all of my resources (data sources and pipes) to a hosted Tinybird region on GCP, and published the REST endpoints, e.g.:
curl -G https://api.us-east.tinybird.co/v0/pipes/performance_trend.json?user_id=123
I then asked Claude Code to get the new host URL and token from Tinybird, which it handled easily, updating the JavaScript to use the new auth config.
Note: This is a toy game, so I just allowed Claude Code to hard-code an app token into the JavaScript. Worst anybody can do is DDoS my endpoints or send fake data to the data source. If this were a real app, I'd properly handle authentication.
And boom: I had a fun, retro, and dare I say - addicting - "circle click" game sending gameplay events to my Tinybird production environment and fetching APIs from the same.
Improving the sub-agent
Based on this experience, I would make a few updates to the Tinybird Code sub-agent prompt to be more specific about deployment workflows:
When deploying to cloud:
1. Always use `tb --cloud deploy` for Cloud deployment
2. Verify all resources are properly created
3. Test endpoints after deployment
To be honest, I problem wouldn't use Claude Code sub-agents here, because of what I described above. I think I'd have more success simply instruction Claude Code to handle data engineering and analytics tasks by calling the tb prompts directly, rather than delegating that to a "shim" sub-agent.
Key Takeaways
This multi-agent workflow demonstrates several important concepts:
1. Specialized expertise matters
By delegating analytics tasks to a Tinybird-specialized sub-agent, we get:
- Better Architecture: Optimal ClickHouse® schema design
- Performance Optimization: Proper sorting keys and partitioning
- Best Practices: Following Tinybird and ClickHouse® conventions
2. Context preservation
Each agent maintains its own context, which means:
- Focused Conversations: Main Claude Code session stays high-level
- Specialized Knowledge: Sub-agents dive deep into domain-specific details
- Efficient Workflows: No context pollution between different task types
3. Iterative improvement
Sub-agents can be improved over time:
- Learning from Failures: Update prompts based on deployment issues
- Adding Tools: Grant additional CLI access as needed
- Refining Instructions: Make deployment workflows more specific
4. Collaborative development
The multi-agent approach enables:
- Seamless Handoffs: Tasks automatically go to the right "expert"
- Comprehensive Solutions: Each agent contributes their specialty
- Faster Development: Parallel expertise without context switching
Play the game (it's addicting)
After I wrote this, I updated the game to include a global leaderboard. If you exclude my colleagues who clearly cheated (looking at you filete), the best time is 4,799 ms. Think you can beat it? The game is live on a GitHub Page.
Next steps
We're all experiencing a new paradigm in software development. We can now deploy specialized AI assistants with deep domain knowledge to build end-to-end applications efficiently, without losing code quality, and by interfacing with just a single orchestrating agent.
My retro game with real-time analytics was very simple, but it demonstrates how these tools can work together - from initial development through local testing to production deployment. While I encountered some challenges, the experience helped me refine the sub-agents and improve future workflows.
Ready to try this workflow yourself? Start by trying out Tinybird Code as a standalone agent to build an analytics project:
curl https://tinybird.co | sh
tb login
tb local start
tb
You'll get a good feel for what it's capable of and how to integrate it into multi-agent workflows with Claude Code, Gemini CLI, or any other agentic CLI or IDE.
More resources:
Have questions? Join our Slack Community.
