Guide

Guildhall is a local AI agent harness for software projects. Start with one small run, then come back for the vocabulary and the deeper machinery when the app starts using words like "blueprint" with a straight face.

First Read

• Start here — install, open one project, and run a small task.
• Why Guildhall exists — the problem it solves, who it helps, and why the product uses the name Guildhall.
• Core concepts — the vocabulary in one place when a term gets fuzzy.

After that, the docs follow the product domains you actually touch:

• Projects are the repos Guildhall can see.
• Tasks are the pieces of work you ask it to move.
• Specs and levers shape how work is planned, reviewed, recovered, and learned from.
• Blueprints and inspections keep work coherent without turning every run into a hidden chat transcript.

Setting up your first project? Start with Start here.

Projects

• Projects and work — service home, project cards, and the project shell.
• Project files and workspace state — what lives on disk.
• Running Guildhall — browser controls first, CLI commands when you need them.
• Guildhall app reference — screen-by-screen details when you need a specific app page.

How it works

• How the work loop works — the system model: survey, blueprint, context, workers, reviewers, gates, and memory.
• How Guildhall builds — the construction model behind planning, implementation, review, and release.
• Research-backed design — the research and practice ideas behind smaller tasks, bounded questions, visible uncertainty, and audit trails.
• Agent context — what agents receive before they act.
• Corpus Map — how Guildhall indexes a project without dumping the whole repo into every prompt.
• Memory, learning, and recovery — how Guildhall learns reusable habits without turning them into mystery behavior.
• External agents and MCP — how Codex, Claude Code, and other MCP-aware tools can read Guildhall project context.

Tasks

• Pressure-Test Intake — how broad requests become buildable specs without turning uncertainty into invisible guesswork.
• Task lifecycle — how a task moves from idea to done.
• Cleaner project notes — how Guildhall keeps shared project notes readable without losing the receipts.
• Git Story Closure — how Guildhall shows whether completed work is dirty, local, pushed, in a PR, merged, local-only, or deferred.

Specs And Levers

• Onboarding and levers — how behavior settings get proposed and approved.
• How Guildhall routes work — how Guildhall routes work without making you manage a steward roster.
• Agents and models — roles and provider assignments.
• Open model recommendations — tested open-model lanes and how to compare candidate models.