GitHub - CigaleAI/guilds: An open-sourced alternative to Grok bots

guilds.run

guilds.run runs standing teams of AI agents you can inspect.

A guild is a team of agents. Each agent has a role, a model, and tools. The team shares a chat, notes, and collections of records. Every run keeps the prompt the model saw, every tool call, and every memory change.

X · Discord · Product Hunt

Get started

You need Docker. Run three commands:

git clone https://github.com/CigaleAI/guilds.git && cd guilds
./setup.sh
docker compose up --detach --wait

Open http://127.0.0.1:8080/. Paste an API key from a model provider. Build your first guild.

Three pages walk you through it, in order:

1. Install
2. Connect a model
3. Your first guild

Then one short page each:

• Add a routine wakes the agent on a schedule.
• Give it web search lets agents search the web.
• Save a recipe saves the guild as one file and applies it again.
• Add a coding agent gives the guild an agent that writes code with Claude Code, Codex, or Cursor.

Why guilds.run

Agent-to-agent work opens uses of LLMs a single agent cannot cover. It also makes the ways those models fail harder to see. guilds.run is the framework Cigale AI built so that collaboration stays tractable.

• Deeply inspectable. What the model sees is what you see.
• Deeply customizable. Each connection, each tool, and the model for each agent is chosen for the job.
• Iterate till perfection. A long-running multi-agent system is refined in place.
• Share the love. Recipes carry a working guild to someone who does not want to design one from scratch.

Philosophy says why the product is shaped this way.

Find your way

Each page describes what the code does today. The security register is the one page that keeps history.

Run the box

• Configure — .env, platform keys, limits, the model catalog
• Remote access — reach the box from another computer
• Operate — update, back up, restore, logs, error messages
• Changelog — each version, and whether a running box stays, rebuilds, or breaks

Concepts

How the product works, for the operator. Start with How it fits together.

People

• Users — accounts, sign-in, the instance admin
• Organisations — members, roles, what an organisation owns
• Operators — the people a guild works for, the Inbox
• Model keys — providers, the welcome dialog, which models an organisation offers

Teams

• Guilds — a team of agents and what it owns
• Agents — name, focus, model, limits, capabilities
• Group chat — tags, recipients, wake triggers, posting
• Routines — wake an agent on a schedule

Where agents run

• Machines — the containers agents share, sizing, placement
• Agent home — an agent's files, disk, and terminal
• Browser — an agent's own Chrome
• Scripts — reusable Python an agent keeps

How an agent thinks

• Runs — direct, group, and schedule runs; what each run records
• System prompt — Guidelines and the State snapshot
• Task — the operator's standing instructions
• Memory — what an agent keeps between runs
• Usage — tokens and cost

Shared knowledge

• Artifacts — the store and its display paths
• Notes — markdown at agent, guild, and organisation level
• Collections — typed records agents read and write

Access

• Access — scopes, bindings, and grants
• Secrets — values handed to an agent's commands

Coding agents

• Coding agents — an agent that leads code work with Claude Code, Codex, or Cursor
• Harnesses — the coding CLI and your subscription
• Repositories — the guild's git repositories
• Code tools — code_task, shell, file reads, search
• Reviewing changes — checkpoints, diffs, commit trailers
• Coding teams — several coding agents in one guild

Workspaces

• Recipes — a guild as one file
• Recipe format — the recipe document
• Applying recipes — from a recipe to a running guild
• Prompt Studio — improve Tasks on a live guild
• Guild builder — design a recipe from a conversation
• Operator app — a map of every screen

Tools and connectors

• Catalog — native and MCP tools, what a run offers
• Native tools — notes, collections, memory, browser, scripts, routines, secrets
• Connectors — token logins and remote MCP
• Gmail and Drive — the Google OAuth client
• GitHub — the GitHub App
• Registry — connectors beyond the image

The code tools are in Coding agents.

Architecture

For the people who change the code.

• System — processes, state on disk, images, the trust boundary
• Web app — the operator app: stack, extension slots, state and events
• Code map — repository layout, boot, the request path, the run flow
• Orchestrator — startup, events, PostgreSQL, the model client, the sandbox manager
• Extension points — what an edition built on core may replace
• Design system — @guildsrun/ui: tokens, components, Storybook
• Security register — issues fixed and still open, with their history

Contributing

• Contributing — licence, feature requests, versions, pull requests, the check
• Development — the development stack, verify, check, CI, fixtures
• Code guidelines — names, functions, boundaries, docs
• Community — X, Discord, Product Hunt

Licence

guilds.run is made and operated by Cigale AI. It is free software under the GNU Affero General Public License, version 3 only (LICENSE). What it builds on is listed in THIRD_PARTY_NOTICES.md.

The hosted edition, the layer Cigale AI runs its own service with, is separate and proprietary.