Skitter

AI agent orchestrator using A2A-over-MQTT.

Skitter has two jobs:

• bundle individual agents into multi-step "apps"
• provide a harness for creating and running A2A-over-MQTT agents

The built-in runner wraps Claude Code and Codex, but any A2A-over-MQTT compliant process can participate.

Why A2A-over-MQTT

Most agent orchestration stacks keep transport, scheduling, and runtime control inside one framework process. That makes them harder to inspect, harder to distribute, and harder to integrate with systems outside that stack.

A2A-over-MQTT is a better boundary:

• routing and fan-out live in the broker, not in bespoke in-process orchestration code
• agents can run anywhere, as long as they can reach MQTT
• agents and the coordinator only need egress access to the broker, not public internet ingress
• discovery, requests, replies, and lifecycle events are all visible on the wire
• interoperable agents can participate without being rewritten around one SDK

Skitter packages that model into a usable CLI: create agents, run them locally or in Docker, and compose them into apps when one agent is not enough.

What Skitter Gives You

• An agent harness for Claude Code .md agents and Codex .toml agents
• An optional coordinator that turns multiple agents into a composed app
• A CLI for setup, service lifecycle, chat, and app/session inspection
• A local-broker workflow driven by skitter up

Quick Start

Prerequisites:

• Python 3.11+
• git
• uv
• Docker, if you want the default local broker flow
• At least one runtime installed and authenticated: Claude Code or Codex
• An API key for a supported LLM provider, if you want the orchestrator to compose agents into apps

git clone https://github.com/id/skitter.git
cd skitter
uv sync

uv run skitter setup
uv run skitter create-agent random-x "returns a random number as JSON"
uv run skitter up
uv run skitter ask random-x "go"

What happens here:

1. uv sync installs Skitter and its dependencies into a local virtual environment
2. uv run skitter setup writes config under ~/.skitter/
3. uv run skitter create-agent creates an agent definition under ~/.skitter/agents/
4. uv run skitter up starts the broker, coordinator, and local agents
5. uv run skitter ask sends an A2A request over MQTT and prints the reply

This quick start uses a single standalone agent, so no orchestrator API key is required. The provider key is only needed for composed apps created with skitter create-app.

Mental Model

• Agents are independent services that publish discovery cards and handle requests over MQTT.
• Skitter can run a single agent directly, or bundle multiple agents into an app with the coordinator.
• The built-in harness reads Claude Code .md agents and Codex .toml agents from ~/.skitter/agents/.

Next Steps

• Usage Guide: service management, multi-agent apps, chat, Docker, storage, and limitations
• Architecture: design, execution flow, recovery, and coordinator details
• A2A-over-MQTT Transport: topic scheme and protocol details
• Contributing: development setup, testing, and config reference

Further Reading

• MQTT.AI: broader MQTT-native AI ecosystem work, including MCP over MQTT