https://github.com/andrmaz/swarm
Autonomous multi-agent system orchestrator for issues management
https://github.com/andrmaz/swarm
afk mastra-ai sandcastle
Last synced: about 1 month ago
JSON representation
Autonomous multi-agent system orchestrator for issues management
- Host: GitHub
- URL: https://github.com/andrmaz/swarm
- Owner: andrmaz
- Created: 2026-04-28T20:01:11.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-14T20:45:20.000Z (3 months ago)
- Last Synced: 2026-06-25T19:04:42.379Z (about 2 months ago)
- Topics: afk, mastra-ai, sandcastle
- Language: TypeScript
- Homepage:
- Size: 859 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Swarm
Welcome to your new [Mastra](https://mastra.ai/) project! We're excited to see what you'll build.
## Getting Started
Start the development server:
```shell
npm run dev
```
Open [http://localhost:4111](http://localhost:4111) in your browser to access [Mastra Studio](https://mastra.ai/docs/studio/overview). It provides an interactive UI for building and testing your agents, along with a REST API that exposes your Mastra application as a local service. This lets you start building without worrying about integration right away.
You can start editing files inside the `src/mastra` directory. The development server will automatically reload whenever you make changes.
## Learn more
To learn more about Mastra, visit our [documentation](https://mastra.ai/docs/). Your bootstrapped project includes example code for [agents](https://mastra.ai/docs/agents/overview), [tools](https://mastra.ai/docs/agents/using-tools), [workflows](https://mastra.ai/docs/workflows/overview), [scorers](https://mastra.ai/docs/evals/overview), and [observability](https://mastra.ai/docs/observability/overview).
If you're new to AI agents, check out our [course](https://mastra.ai/learn) and [YouTube videos](https://youtube.com/@mastra-ai). You can also join our [Discord](https://discord.gg/BTYqqHKUrf) community to get help and share your projects.
## GitHub Side-Project Workflow
This repo now includes a hybrid four-role GitHub delivery flow for personal side projects:
- Product manager selects or creates the next GitHub issue in Mastra
- Software architect turns that issue into an implementation plan in Mastra
- Software engineer executes the plan in an isolated Sandcastle worktree / sandbox and opens a pull request
- Code reviewer inspects the PR in an isolated Sandcastle run and submits the final GitHub review
Mastra owns orchestration, durable-ish workflow state, task progression, and GitHub coordination. Sandcastle owns isolated engineer / reviewer execution.
The orchestration is registered as `githubSideProjectWorkflow`, and the specialist agents are also available individually from `src/mastra/agents`.
### GitHub credentials
For autonomous repository and pull request operations, set `GITHUB_TOKEN`.
For GitHub webhook / @mention handling through `@chat-adapter/github`, configure either:
- `GITHUB_TOKEN` for the simplest personal-project setup, or
- `GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY`, and optionally `GITHUB_INSTALLATION_ID` for GitHub App mode
When using GitHub webhooks, also set:
- `GITHUB_WEBHOOK_SECRET`
- `GITHUB_BOT_USERNAME`
### Sandcastle setup
To run the engineer and reviewer stages, configure Sandcastle in `.env`:
- Set `SANDCASTLE_PROVIDER` to `docker` or `podman`
- Set `SANDCASTLE_IMAGE_NAME` to an image that has the tooling your target repos need
- Set `SANDCASTLE_AGENT_PROVIDER` and `SANDCASTLE_AGENT_MODEL`
- Provide the matching API key such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
- Optionally set `SANDCASTLE_SANDBOX_READY_COMMANDS` for one-time sandbox bootstrapping like `pnpm install --frozen-lockfile`
The hybrid workflow writes Sandcastle logs under each target repo's `.sandcastle/logs/` directory.
See [docs/hybrid-architecture.md](docs/hybrid-architecture.md) for the full MVP architecture, required env vars, and an example workflow input.
## Deploy to the Mastra platform
The [Mastra platform](https://projects.mastra.ai) provides two products for deploying and managing AI applications built with the Mastra framework:
- **Studio**: A hosted visual environment for testing agents, running workflows, and inspecting traces
- **Server**: A production deployment target that runs your Mastra application as an API server
Learn more in the [Mastra platform documentation](https://mastra.ai/docs/mastra-platform/overview).