SWARM BUDDY & FRIENDS
Swarm management for sensitive environments. . REST. Serve agents using static binary. Deploy anywhere, scale instantly.
Binary Size
5.4 MB
Type
Coding Agent
Tools
12
License
MIT
Hook Chains
16
WHAT_IS.SWARM
ChatGPT invented single-turn interactions with LLMs. 3 years later AI can control computer shell (thing that runs your GUI and Applications) very efficiently. Today we can run 100s of these "agents" to solve various problems. "Swarm-Buddy" is a helper AI in running such "swarms". It provides the critical infrastructure to deploy, manage, and coordinate these agents.
USE_CASE.LOG
Autonomous swarms for research and data processing tasks. Discovering novel architectures, organising our heritage all done with swarm-buddy & friends.
Swarm-Buddy (codename: swb) will help you manage the swarm better. He is not a tryhard, he knows how to handle swarm not solve your tasks. All intelligence is offloaded into to the LLMs and user prompts. If your prompt contains instructions to use Codex, Swarm-Buddy will happily use it.
Built for your AI. Start swb and ask Claude to connect and help you. Everything can be done from the comfort of your laptop.
Research Farming
Using swb we run over 30 autoresearch agents in parallel to discover new neural architectures to
build highly efficient neural computers.
- Industrial Automaton
Map-Reduce ETL pipelines
Using toroid we built scripts to standardize and record
Sanskrit texts. So far we have indexed 103K+ shloka. Manage multiple agents like downloader,
article creator.
- Project
Artha
Home Codebase
We use Swarm Buddy to maintain the codebase. Using swb we schedule it to checkout the latest code from various online inspirations (incl. Opencode). If there are any changes it will update the codebase and notify us.
HLD
In the Swarm-Buddy architecture, users exercise total control over distributed nodesβwhich can be anything from K8S pods and E2B machines to bare-metal VMs or local environments.
Each node is a standalone unit. There is no complex primary/secondary handshake; instead, every instance is individually accessible via a dedicated REST network interface. This shared-nothing approach ensures that each pod remains isolated, secure, and focused exclusively on its assigned workload.
Each SWB node houses a server that manages multiple Toroid Kernels. These kernels ingest data from user prompts and tools, emitting real-time events that hooks use to export traces or metrics. Built for high-sensitivity tasks, Swarm-Buddy automatically tracks and logs all internet-bound commands, ensuring complete auditability.
Screenshot and share this diagram with an AI to understand more.
FRIENDS.MODULES
Swarm buddy is a gang that comes with multiple modules that fit together to form a complete swarm.
Toroid
A no-bullshit coding agent package in Go to run your own custom agentic loops. The core agentic coding loop. Performs autonomous with high-fidelity OS permissions. MIT License.
SWB
Herds your swarm ensuring tasks operate reliably. Your node is the playground for your swarm. Exposes a REST API for easy integration.
SWB
swb your swarm ensuring tasks operate reliably. Your node is the playground for your swarm. Exposes a REST API for easy integration.
Start by installing the binary like:
Then start the server like:
Swarm-Buddy will already be present for you at /swb/ endpoint. Ask it any question you want.
When you first start swb it will not contain any agent, you can create a new folder (say morty) and move your prompt files in there. Then you can call the agent directly using the /app/<morty>/ endpoint.
mkdir -p .swb/agents/morty && \
echo 'You will always talk like you are panicking.' >> \
.swb/agents/morty/agent.md
The above request will give you an ID that you can poll for results:
Toroid Kernel
Import toroid.Agent and run event loops with 16 hooks.
go get github.com/yashbonde/swarm-buddyimport "swarm-buddy/pkg/toroid"
func main() {
ctx := context.Background()
kernel, _ := toroid.New(ctx, toroid.Config{})
// Register lifecycle hooks
kernel.On(toroid.EventPreToolUse, func(ctx context.Context, e toroid.Event) error {
fmt.Println("Toroid is about to execute a tool...")
return nil
})
// Print usage
kernel.On(toroid.EventStop, func(ctx context.Context, e toroid.Event) error {
if p, ok := e.Payload.(*toroid.UsagePayload); ok {
fmt.Println("Usage:", p.Tokens)
}
return nil
})
resp, _ := kernel.Run(ctx, "Analyze this repository")
fmt.Println(resp.Text())
// continue the conversation anytime, automatically picks up the context
resp, _ = kernel.Run(ctx, resp, "Can you search all the prompts in this repository?")
fmt.Println(resp.Text())
}TOOLS.SYS
Toroid comes equipped with a set of hardened system tools that allow agents to interact with the local environment with surgical precision.
bash
Execute non-interactive shell commands.
read / write
High-fidelity filesystem operations.
grep / glob
Efficient pattern matching and file discovery.
multiedit
Perform batch atomic edits across multiple files.
subagent
Spawn recursive intelligence nodes for complex sub-tasks.
todo
Internal task management and state tracking.
HOOK_CHAIN.SYS
Toroid exposes 16 lifecycle hooks allowing you to inject logic, monitoring, or constraints at every stage of the agent's execution loop.
SessionStart
Initial handshake and context loading.
UserPromptSubmit
Fired when raw user input is received.
Token
Real-time stream of LLM generated text.
PermissionRequest
Pre-flight check for destructive operations.
PreToolUse
Last buffer before tool execution begins.
PostToolUse
Validation and processing of tool output.
PostToolUseFailure
Error recovery and retry logic point.
SessionEnd
Final cleanup and database sync.
READY TO JOIN?
Join the developers building the next generation of autonomous swarms.