I justed added support for Composable Fleets to herdctl. As I build herdctl into more projects, I increasingly find myself creating a fleet of agents per project, and wanted a way to run them all and see what's going on with them.

Fleet Composability means you can create hierarchical fleets of related agents, like this:

Fleet Composability means you can create a hierarchy of teams of agents, each with its own defined responsibilities and scratch directory that it can use to store state and artifacts. herdctl already has 4 of those agents so far, so I keep them a single fleet, but as herdctl itself is only one of the projects that I'm working on, I actually run a superfleet of all of them.

The web UI knows about fleet composability and renders my fleets like this:

For the herdctl project itself, I'm currently running 4 agents, in a single fleet for now:

• security - daily schedule scans the repo every day for new security issues
• docs - daily schedule, scans to see if any commits should have had docs updates but didn't, makes PRs if so
• changelog - scans each day to see if we did anything worthy of putting on the docs changelog page
• engineer - general purpose engineering agent that I can chat with

The first 3 of those are all "background" agents that run on a schedule and just continually fix things that can otherwise drift over time unless a human pays attention to them. I suspect I'll end up with a bunch more agents following the same pattern. Each agent gets its own agents/myAgent directory with its own configuration and prompts. It's Claude Code so it can do whatever you want it to really.

herdctl doesn't impose much structure on you. You don't have to use an agents subdirectory at all, you can put things wherever you like. But the agents subdirectory is a where I'd recommend you place them, as a couple of upcoming convenience features will work a little better if you do.

But I'm also developing other projects while I work on herdctl, and I have a set of personal agents that help me with my house-related projects like the homelab and the garden. Fleet Composition lets me group that second set of agents together into a "personal" fleet, and then run them plus all the other projects' agents in one command.

I write a bit more about how the homelab agent does its work in this post about continuous security with herdctl.

Sub-teams in Large Projects

It's pretty easy to see how a large project could start to benefit from having multiple fleets of agents. Marketing-related agents could:

• grab analytics regularly, synthesize the results in context and alert us when something looks wrong
• Optimize SEO for any new pages that have popped up, drive long-term ranking improvements
• Look for negative sentiment on social media, handle or escalate as appropriate

Those are all fairly straightforward things to get Claude Code to do, with a bit of tinkering, and I'm sure you can think of a bunch more too. You can probably also think about a bunch of possible Engineering-related agents you might want, and maybe even some Legal-related agents too:

• GDPR scanner - are we still GDPR compliant? Opens a browser every day and checks
• TOS scanner - has anything we've shipped lately accidentally broken our Terms of Service?
• Legal news scanner - has any law been passed in any country we operate in that might affect us?

Most of the above are arguably things that should be owned by Engineering in many organizations, but with Fleet Composability it's entirely possible for a Marketing team to have a set of herdctl agents in a separate repo, and just have them run as part of the wider fleet that Engineering maintains/supports.

With herdctl we can define all of the above with clean, source-controllable YAML files.

herdctl Agents Don't Really Exist

A herdctl agent is just a YAML file that is approximately:

• 50% config passed straight to Claude Agents SDK
• 20% discord/slack/web dashboard config
• 15% schedule config
• 10% docker config
• 5% other - optional extra prompts

Aside from that final 5%, none of that is much to do with what your agent does, it's just a way to configure the agent's permissions, connectors, schedules, etc, mostly just passing that config through to wherever it should go.

Schedules do usually provide a prompt that is given to Claude Code when the schedule is triggered, but you're encouraged to make that prompt very short, just something like "Run the /scan-for-missing-docs-in-recent-commits skill". The herdctl.yaml file is not the right place to put detailed agent instructions - use the existing Claude Code ecosystem for that.

Everything else that your agent does should be in the form of something like .md files. A common emerging pattern is to just instruct your agent to keep a STATE.md file up to date with whatever state it wants to persist between runs. If you provide the agent with a Github access token you can have it commit and push whatever work it does to wherever it makes sense to keep it.

Similarly, although there is a primitive hooks implementation, there's no intention at the moment to add a lot of connectors to that. If you need your agent to send an email as part of its scheduled work, for example, there are ways to make Claude Code do that, so herdctl doesn't aim to provide that plumbing and probably never will.

Find out more about herdctl at herdctl.dev.