CueMarshal
Intelligent Workflow Orchestration for AI Agents.
Ask AI about CueMarshal
Powered by Claude Β· Grounded in docs
I know everything about CueMarshal. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
CueMarshal β AI-Powered DevOps for Software Teams
From issue to reviewed PR without leaving Git.
CueMarshal is self-hosted AI DevOps: GitHub Actions + an AI engineering orchestra on your own infrastructure. Open an issue, and CueMarshal plans, builds, reviews, tests, and documents the change through Git-native branches and pull requests. You keep final control: review every PR, request edits, and merge when ready.
- Marshal (Conductor) β routes work and keeps execution moving
- Ava (Architect) β designs the solution and opens a spec PR
- Dave (Developer) β writes the implementation on a feature branch
- Reese (Reviewer) β checks for bugs, risks, and code quality issues
- Tess (Tester) β runs test suites and validates behavior
- Devin (DevOps) β handles infrastructure and deployment tasks
- Dot (Docs) β keeps documentation clear and current
- Linton (Linter) β enforces code quality checks before merge
Every step lives in Gitea as issues, branches, pull requests, and labels. Full audit trail. Full human control.
β οΈ Early stage. Core workflow is functional. Self-improvement engine works but needs more testing. Mobile app and Kubernetes Helm charts are in progress.
Why CueMarshal?
| Traditional CI/CD | CueMarshal |
|---|---|
| Separate tools for tasks, reviews, docs | Everything lives in Git |
| Fixed pipelines, hard to customize | Flexible agents you configure |
| "Why did it fail?" is unclear | Full reasoning trail in PRs |
| Expensive cloud bills | Run on your hardware, pay only for model calls |
| Vendor lock-in | Open source, fully self-hosted |
Use Cases:
- Ship faster β Cut code review time from hours to minutes
- Better quality β AI reviewers catch security issues humans miss
- Data sovereignty β Your code never leaves your servers
- Cost control β ~$0.50/issue in API costs vs $100+/month in cloud CI
Quick Start Β· Architecture Β· Agents Β· Documentation
Meet the Orchestra
Each team member has a distinct avatar and working style, so activity feels like a real engineering squad instead of a black box.
| Avatar | Member | Role | Personality |
|---|---|---|---|
| Marshal | Conductor | Starts the symphony and coordinates handoffs | |
| Ava | Architect | Wise visionary planner | |
| Dave | Developer | Industrious builder | |
| Reese | Reviewer | Laser-sharp critic | |
| Tess | Tester | Clever bug washer | |
| Devin | DevOps | Master multi-tasker | |
| Dot | Docs | Explains it clearly | |
| Linton | Linter | Picky perfectionist |
Quick Start
# Clone the repository
git clone https://github.com/cuemarshal/cuemarshal.git
cd cuemarshal
# One-command setup (handles secrets, deps, and health checks)
./quick-start.sh
Open http://localhost:3300 β Gitea is ready.
Need full control? See the detailed setup guide.
Prerequisites
- Docker and Docker Compose v2+
- 8 GB RAM minimum (16 GB recommended)
- Local Ollama at
http://localhost:11434runninggemma4:26b, or at least one cloud LLM API key:- Groq (free, fast β primary)
- Google Gemini (free β fallback)
- Azure AI (paid β second fallback)
What's Implemented
- β Conductor orchestrator (task decomposition + agent routing)
- β 7 specialized AI agents (architect, developer, reviewer, tester, devops, docs, linter)
- β Git Flow execution (issue β branch β PR β review β merge)
- β LiteLLM gateway with 3-provider fallback (Groq β Gemini β Azure)
- β MCP servers for tool access (Gitea, Conductor, System)
- β Self-improvement loop (system scans and improves its own codebase)
- β Docker Compose deployment (11 services, one command)
- β³ Mobile app (React Native, in progress)
- β³ Kubernetes Helm charts (in progress)
- β³ Multi-repo support (planned)
How It Works
User creates issue in Gitea
β
Conductor receives webhook
β
Conductor decomposes task β assigns to agents
β
ββββββ΄βββββββββββββββββββββββββββββββββββ
β Architect β spec PR β
β Developer β implementation PR β
β Reviewer β review comments + fix β
β Tester β test results β
β DevOps β infra/deployment PR β
β Docs β documentation PR β
β Linter β pre-merge quality gate β
ββββββββββββββββββββββββββββββββββββββββββ
β
Human reviews + merges
β
Done. Full audit trail in Git.
Architecture
User (Mobile App / Gitea UI)
β
Conductor (TypeScript) ββ Redis/BullMQ
β β
MCP Servers LLM Gateway (LiteLLM)
βββ Gitea MCP βββ Groq
βββ Conductor MCP βββ Google Gemini
βββ System MCP βββ Azure AI
β
Gitea Server ββ PostgreSQL
β
Runners (Gitea Act Runner + OpenCode)
βββ Developer Agent
βββ Reviewer Agent
βββ Tester Agent
βββ Architect Agent
βββ DevOps Agent
βββ Docs Agent
βββ Linter Agent
See Architecture Overview for full diagrams and data flows.
Services
| Service | Port | Description |
|---|---|---|
| Gitea | 3300 | Git server, issues, PRs, workflows, webhooks |
| Conductor | 4000 (internal) | Orchestrator, webhook handler, mobile API |
| LLM Gateway | 4100 (internal) | LiteLLM proxy with 3-provider fallback |
| Gitea MCP | 4200 (internal) | MCP server for Gitea operations |
| Conductor MCP | 4201 (internal) | MCP server for task/agent coordination |
| System MCP | 4202 (internal) | MCP server for costs, runners, health |
| PostgreSQL | 5432 (internal) | Shared database |
| Redis | 6379 (internal) | Task queue (BullMQ) and cache |
| Nginx | 8180 | Reverse proxy |
Who Should Use CueMarshal?
- Software teams wanting AI-assisted code review and task automation
- Engineering leaders concerned about vendor lock-in or cloud costs
- Organizations with data residency requirements (your code stays on your servers)
- Developers already using Gitea who want AI-powered workflows
- Builders who want to experiment with AI agent orchestration
Technology Stack
| Layer | Technology |
|---|---|
| Orchestration | TypeScript, Node.js, Express, BullMQ, Drizzle ORM |
| LLM Gateway | LiteLLM (Python), custom callbacks |
| MCP Servers | TypeScript, @modelcontextprotocol/sdk |
| AI Engine | OpenCode (Go), headless/CLI mode |
| Git Platform | Gitea, Gitea Act Runner |
| Mobile | React Native, Expo, TypeScript |
| Database | PostgreSQL |
| Cache/Queue | Redis |
| Proxy | Nginx |
| Containers | Docker, Docker Compose |
Documentation
| Document | Description |
|---|---|
| Architecture | System architecture, data flows, component diagrams |
| Conductor | Conductor service specification |
| LLM Gateway | LiteLLM configuration, tiered models, fallback |
| MCP Servers | MCP server specs, tool schemas, dual transport |
| Agents | Agent profiles, system prompts, tool permissions |
| Workflows | Gitea Actions workflow templates |
| Runner | Custom runner Dockerfile and setup |
| Mobile App | React Native Expo app specification |
| Self-Improvement | Self-improvement engine |
| Model Selection | Automated model selection algorithm |
| Security | Security model and access control |
| Deployment | Deployment and infrastructure guide |
| API Reference | Conductor REST and WebSocket API |
Contributing
CueMarshal uses its own platform to manage contributions β improvements flow through Gitea issues and PRs, often executed by the AI agents themselves.
To contribute:
- Fork the repository and create a feature branch from
main - Open an issue describing what you plan to change before submitting a PR
- Follow Git Flow: one logical change per branch, one PR per issue
- Run tests before opening a PR:
cd services/mcp-servers && npm test cd services/conductor && npm test - Ensure Docker Compose starts cleanly with
./quick-start.sh
PRs are reviewed by the CueMarshal reviewer agent. Humans have final merge authority.
License
MIT β see LICENSE for details.
