A multi-model agent framework for running long, high-stakes projects with real quality control.
Starling orchestrates teams of LLM agents — each on its own model and provider — through plan-mode execution with a real quality gate. Designed for work that takes more than one prompt: long-form drafting, small-business loops, multi-step research, codebase work, anything where output quality matters.
Warning
Beta software — V2.2.0-beta.1. V2.2 is the producer-collapse / skills-first rebuild: agents are producers-with-skills and tasks are skill-routed, QC-as-fixer (when a producer can't clear the bar, QC patches the artifact from its own findings and the task completes — on by default), per-task artifact staging with a deterministic main-thread merge for concurrent waves, and provider thinking on/off control. 2264 tests pass; the engine was validated end-to-end on a heterogeneous live model lineup (reasoning Leader + agentic QC + thinking-off producer) and cleared a full multi-reviewer audit (Captain Nemo hull review + Lovecraft coherence pass). This is the first beta — it has not yet had external soak time at scale. Read V2.2 Beta calibration before kicking off serious work. Expect rough edges; pin a specific version if depending on Starling for production. Bug reports and discussions welcome on the issues tab and discussions.
Status: V2.2 Beta ships with the full documentation set (in-repo under
docs/, plusmkdocs servefor local browsing). Python 3.12+ (3.11 support ended with v2.1).
Until the Starling docs site is hosted, the canonical documentation lives in this repo as source markdown (renders directly on GitHub) plus a local mkdocs serve for the full navigable experience.
- V2.2 Beta calibration — what the engine does well, what it does NOT do yet, sizing rules of thumb, and the QC-as-fixer / self-heal scope. Read before kicking off serious work.
- Roadmap — job templates + persona continuity, V2.3 (different interface), long-horizon pillars.
- Install — Python 3.12+, venv, dependencies.
- Quickstart — a single-deliverable walkthrough.
- Setup wizard — the eight-step first-run flow.
- Worked examples: multi-piece deliverable · production-scale Phase 1
- Concepts overview — the mental model: project, plan, agent, skill, standard, vault.
- Agents — Leader / QC / producers (skills-first; no fixed roles).
- Plan lifecycle — full state machine.
- Providers & models — every supported provider with auth.
- Working memory (5 layers) — tool-loop summarization, context-budget gate, repo_map, team_state, terse-prose.
- Skill system — composition, dispatch, producer-vs-verifier discipline, profile system.
- Sandbox + tool execution — five layers of defense.
- Audit trails — five parallel surfaces of evidence.
- CLI reference — every command + flag.
- Skill catalog — every seed skill (17 in V2.1 Alpha).
- Tool catalog — every entry in
build_registry. - Python API — public types + functions for embedded callers.
- Daemon operator's guide — the background-process story.
- Multi-user host hardening —
0o600checklist. - Vault backup + restore — what to back up, how often, how to restore.
- CI integration — running Starling in GitHub Actions / similar.
- V2.0 → V2.1 Alpha migration
- Troubleshooting — symptom → fix mapping, including V2.1-specific entries.
Local preview (live site):
source .venv/bin/activate
uv pip install mkdocs-material
mkdocs serve
# opens http://127.0.0.1:8000/A V2.0 PDF + DOCX bundle is preserved in docs/dist/ (Starling-Docs-v2.0.pdf, Starling-Docs-v2.0.docx) for archive purposes. A V2.1 bundle ships in a follow-on commit; for now the markdown source above is canonical.
git clone https://github.com/StarlingAgents/Starling.git ~/starling-v2
cd ~/starling-v2
uv venv && uv pip install -e ".[dev]"
starling setupFull install with troubleshooting: Install guide.
Python 3.11 or 3.12 required. Starling's
requires-pythonis>=3.11; CI tests 3.11 and 3.12 only. If yourpython3is 3.13+ (common with linuxbrew), point the venv at/usr/bin/python3.12explicitly — newer Pythons aren't on the tested path. (V2.1 is the last release supporting 3.11; see CHANGELOG.)
- Multi-model routing per agent. Each agent (Leader, QC, every producer) runs on its own configured provider + model. Pick a fast/cheap model for routine work and a stronger one for the gate-class seats — native to the architecture, not an afterthought.
- Quality control as a first-class subsystem. Three-layer TQM (universal axes × per-artifact-kind standards × per-team overrides). QC reviews every artifact; rejects route back to producers in GENERATE or EDIT mode.
- Skills over fixed roles. Agents are compositions of skills; skills are conversationally creatable and persist to your vault.
- Plan-mode end-to-end. Leader is a conversational partner, plan is the unit of execution, daemon-driven async, Telegram approvals, audit trail.
- Open architecture. Your data, your vault, your providers, your models. No SaaS, no per-instance subscription.
See docs/index.md for the full picture.
The V2.0 PDF + DOCX in docs/dist/ are preserved as historical archives. To regenerate the bundle for the current docs (or to ship a V2.1 bundle):
source .venv/bin/activate
./scripts/build-docs-bundle.shOutputs land in docs/dist/. Commit the new artifacts alongside the source changes.
The script uses pandoc bundled inside pypandoc (no system pandoc install needed) and weasyprint for PDF output. Install weasyprint once: uv pip install weasyprint.
starling-v2/
├── src/starling/ # Source — agents, runners, daemon, TUI, CLI
├── tests/ # Pytest suite
├── docs/ # Full Tier-2 user documentation (mkdocs source + V2.0 archive PDF/DOCX)
├── scripts/ # Build / release scripts
├── mkdocs.yml # Docs site config
└── pyproject.toml # Package metadata + deps
Internal design docs (architecture history, gap analyses, V2.1 / V2.x specs) live outside the repo as working notes — not user-facing and not in source control.
GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
Plain-language summary (not legal advice; the LICENSE file is authoritative):
- Self-hosted private use — Use, modify, and run Starling on your own machines for your own work. No obligations.
- Modifications stay yours, until you share — If you fork and modify Starling for your own use, you can keep the changes private. Distributing modified copies (binaries, packages, source) means recipients must get the same AGPL-3.0 rights, including access to your modifications.
- Network use is distribution — The "AGPL" piece, vs. the regular GPL: if you run a modified Starling as a service that interacts with users over a network (a hosted UI, an API, a multi-tenant deployment), you must offer those users the modified source under the same license. This is intentional — Starling is built to stay open even when run as infrastructure.
- Commercial use is allowed — AGPL doesn't restrict commercial use; it restricts proprietary forks of network-deployed services.
If you need a license that allows building closed-source derivatives or proprietary network services, contact the maintainer about commercial licensing.
Issues and pull requests welcome at github.com/StarlingAgents/Starling. See CONTRIBUTING.md for the contribution guide. Three GitHub issue templates are wired (Bug report / Regression / Feature request) plus a labelset for severity / component / status / regression — file issues using the templates so the labels apply correctly.
Contributions are accepted under the project's AGPL-3.0-or-later license (see LICENSE). By submitting a contribution, you affirm you have the right to do so under those terms.